feat: add Instruction, OutputStyle, FrameDest, TokenKind, FrameOp; renumber all opcodes to 5-bit hardware encoding; remove ALUInst, SMInst, Addr, FREE_CTX

cm_inst.py

···
 from dataclasses import dataclass
-from enum import IntEnum
+from enum import Enum, IntEnum
 from typing import Optional
 
 
···
 
 
 class ArithOp(ALUOp):
-    ADD = 0b0000
-    SUB = 0b0001
-    INC = 0b0010
-    DEC = 0b0011
-    SHIFT_L = 0b0100
-    SHIFT_R = 0b0101
-    ASHFT_R = 0b0110
+    ADD = 0b00000      # 0
+    SUB = 0b00001      # 1
+    INC = 0b00010      # 2
+    DEC = 0b00011      # 3
+    # gap: 4-7 are LogicOp
+    SHL = 0b01000      # 8  (was SHIFT_L = 4)
+    SHR = 0b01001      # 9  (was SHIFT_R = 5)
+    ASR = 0b01010      # 10 (was ASHFT_R = 6)
 
 
 class LogicOp(ALUOp):
-    AND = 0b0111
-    OR = 0b1000
-    XOR = 0b1001
-    NOT = 0b1010
-    EQ = 0b1011
-    LT = 0b1100
-    LTE = 0b1101
-    GT = 0b1110
-    GTE = 0b1111
+    AND = 0b00100      # 4
+    OR  = 0b00101      # 5
+    XOR = 0b00110      # 6
+    NOT = 0b00111      # 7
+    # gap: 8-10 are ArithOp shifts
+    EQ  = 0b01011      # 11
+    LT  = 0b01100      # 12
+    LTE = 0b01101      # 13
+    GT  = 0b01110      # 14
+    GTE = 0b01111      # 15
 
 
 class RoutingOp(ALUOp):
-    BREQ = 0b10000000
-    BRGT = 0b10000001
-    BRGE = 0b10000010
-    BROF = 0b10000011
-    # + more?
-    SWEQ = 0b11000000
-    SWGT = 0b11000001
-    SWGE = 0b11000010
-    SWOF = 0b11000011
-    # + more?
-    GATE = 0b11100000
-    PASS = 0b01000000
-    CONST = 0b0010000
-    FREE_CTX = 0b1010000
-    # uncertain
-    SEL = 0b11110000
-    MRGE = 0b11111000
+    BREQ         = 0b10000  # 16
+    BRGT         = 0b10001  # 17
+    BRGE         = 0b10010  # 18
+    BROF         = 0b10011  # 19
+    SWEQ         = 0b10100  # 20
+    SWGT         = 0b10101  # 21
+    SWGE         = 0b10110  # 22
+    SWOF         = 0b10111  # 23
+    GATE         = 0b11000  # 24
+    SEL          = 0b11001  # 25
+    MRGE         = 0b11010  # 26
+    PASS         = 0b11011  # 27
+    CONST        = 0b11100  # 28
+    FREE_FRAME   = 0b11101  # 29 (was FREE_CTX)
+    ALLOC_REMOTE = 0b11110  # 30
+    EXTRACT_TAG  = 0b11111  # 31
 
 
-@dataclass(frozen=True)
-class Addr(object):
-    a: int
-    port: Port
-    pe: Optional[int]
+class OutputStyle(Enum):
+    INHERIT = 0
+    CHANGE_TAG = 1
+    SINK = 2
 
 
-@dataclass(frozen=True)
-class ALUInst(object):
-    """
-    Instruction stored in IRAM
-    """
+class TokenKind(Enum):
+    DYADIC = 0
+    MONADIC = 1
+    INLINE = 2
+
 
-    op: ALUOp
-    dest_l: Optional[Addr]
-    dest_r: Optional[Addr]
-    const: Optional[int]
-    ctx_mode: int = 0  # 0=inherit, 1=CTX_OVRD (const overrides ctx)
+class FrameOp(IntEnum):
+    ALLOC = 0
+    FREE = 1
 
 
 @dataclass(frozen=True)
-class SMInst(object):
-    """
-    SM instruction stored in IRAM. Causes PE to emit an SMToken
-    instead of routing through the ALU.
+class FrameDest:
+    target_pe: int
+    offset: int
+    act_id: int
+    port: Port
+    token_kind: TokenKind
 
-    Operand mapping (PE constructs SMToken from instruction + token operands):
-      READ (monadic):    cell_addr = const or token.data, result → ret
-      WRITE (monadic):   cell_addr = const, write_data = token.data
-      WRITE (dyadic):    cell_addr = left, write_data = right
-      CLEAR/ALLOC/FREE:  cell_addr = const or token.data
-      RD_INC/RD_DEC:     cell_addr = const or token.data, result → ret
-      CMP_SW (dyadic):   cell_addr = const, expected = left, new = right, result → ret
-    """
 
-    op: MemOp
-    sm_id: int
-    const: Optional[int] = None
-    ret: Optional[Addr] = None
-    ret_dyadic: bool = False
+FrameSlotValue = int | FrameDest | None
+
+
+@dataclass(frozen=True)
+class Instruction:
+    opcode: ALUOp | MemOp
+    output: OutputStyle
+    has_const: bool
+    dest_count: int
+    wide: bool
+    fref: int
 
 
 # Monadic ALU operations: take a single operand
···
 _MONADIC_ARITH_OPS = frozenset({
     ArithOp.INC,
     ArithOp.DEC,
-    ArithOp.SHIFT_L,
-    ArithOp.SHIFT_R,
-    ArithOp.ASHFT_R,
+    ArithOp.SHL,
+    ArithOp.SHR,
+    ArithOp.ASR,
 })
 
 _MONADIC_LOGIC_OPS = frozenset({
···
 _MONADIC_ROUTING_OPS = frozenset({
     RoutingOp.PASS,
     RoutingOp.CONST,
-    RoutingOp.FREE_CTX,
+    RoutingOp.FREE_FRAME,
+    RoutingOp.ALLOC_REMOTE,
+    RoutingOp.EXTRACT_TAG,
 })
 
 

design-notes/pe-design.md

···
 
 **Hardware cost:**
 
-| Component                  | Chips | Notes                                   |
-|----------------------------|-------|-----------------------------------------|
-| act_id -> frame_id lookup  | 2     | 74LS670, indexed by act_id              |
-| Presence + port metadata   | 4     | 74LS670, indexed by frame_id            |
-| Bit select mux             | 1-2   | offset-based selection of presence/port |
-| **Total match metadata**   | **~8** |                                        |
+| Component                 | Chips  | Notes                                   |
+| ------------------------- | ------ | --------------------------------------- |
+| act_id -> frame_id lookup | 2      | 74LS670, indexed by act_id              |
+| Presence + port metadata  | 4      | 74LS670, indexed by frame_id            |
+| Bit select mux            | 1-2    | offset-based selection of presence/port |
+| **Total match metadata**  | **~8** |                                         |
 
 **Constraint: 8 matchable offsets per frame.** The assembler enforces
 this. 8 dyadic instructions per function chunk per PE is reasonable --
···
   15       14-10     9-7     6       5-0
 ```
 
-| Field  | Bits | Purpose |
-|--------|------|---------|
-| type   | 1    | 0 = CM compute, 1 = SM operation |
-| opcode | 5    | Operation code (CM and SM have independent 32-entry spaces) |
-| mode   | 3    | Combined tag/frame-reference mode (see mode table below) |
+| Field  | Bits | Purpose                                                      |
+| ------ | ---- | ------------------------------------------------------------ |
+| type   | 1    | 0 = CM compute, 1 = SM operation                             |
+| opcode | 5    | Operation code (CM and SM have independent 32-entry spaces)  |
+| mode   | 3    | Combined tag/frame-reference mode (see mode table below)     |
 | wide   | 1    | 0 = 16-bit frame values, 1 = 32-bit (consecutive slot pairs) |
-| fref   | 6    | Frame slot base index (64 slots per activation) |
+| fref   | 6    | Frame slot base index (64 slots per activation)              |
 
 **type:1** -- operation space select:
 ```

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_01.md

···
+# PE Frame-Based Redesign — Phase 1: Foundation Types
+
+**Goal:** Establish all shared types that both the emulator and assembler depend on, plus encoding boundary functions.
+
+**Architecture:** Add new types (`Instruction`, `OutputStyle`, `FrameOp`, `FrameDest`, `TokenKind`, `FrameSlotValue`) to `cm_inst.py`, restructure the token hierarchy in `tokens.py` with a new `PEToken` intermediate base class, create `encoding.py` with pack/unpack boundary functions, and update `emu/events.py` and `emu/types.py` for frame-based config. Old types (`ALUInst`, `SMInst`, `IRAMWriteToken`, `MatchEntry`) are removed — this will break existing consumers. Fixes come in later phases.
+
+**Tech Stack:** Python 3.12 (dataclasses, enums, IntEnum)
+
+**Scope:** Phase 1 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-06
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC1: Token hierarchy correctly models frame-based architecture
+- **pe-frame-redesign.AC1.1 Success:** `PEToken` base class exists; `CMToken`, `PELocalWriteToken`, `FrameControlToken` all inherit from it
+- **pe-frame-redesign.AC1.2 Success:** `CMToken.act_id` replaces `ctx` throughout; `DyadToken` has no `gen` field
+- **pe-frame-redesign.AC1.3 Success:** `PELocalWriteToken` carries `region`, `slot`, `data`, `is_dest` fields
+- **pe-frame-redesign.AC1.4 Success:** `FrameControlToken` carries `act_id`, `op` (FrameOp), `payload`
+- **pe-frame-redesign.AC1.6 Failure:** Token with invalid `act_id` (no tag store mapping) is dropped with `TokenRejected` event
+
+### pe-frame-redesign.AC2: Semantic Instruction model with pack/unpack
+- **pe-frame-redesign.AC2.1 Success:** `Instruction` carries `opcode`, `OutputStyle`, `has_const`, `dest_count`, `wide`, `fref`
+- **pe-frame-redesign.AC2.2 Success:** `pack_instruction()` and `unpack_instruction()` round-trip for all valid mode combinations
+- **pe-frame-redesign.AC2.3 Success:** CM vs SM type derived from `isinstance(opcode, MemOp)`, not a stored field
+- **pe-frame-redesign.AC2.4 Success:** Emulator PE never touches raw mode bits — only semantic fields
+
+---
+
+<!-- START_SUBCOMPONENT_A (tasks 1-3) -->
+<!-- START_TASK_1 -->
+### Task 1: Add new types to cm_inst.py
+
+**Verifies:** pe-frame-redesign.AC2.1, pe-frame-redesign.AC2.3
+
+**Files:**
+- Modify: `cm_inst.py` (add new types, remove ALUInst/SMInst/Addr, replace FREE_CTX with FREE_FRAME)
+
+**Implementation:**
+
+Remove the `ALUInst`, `SMInst`, and `Addr` dataclasses entirely from `cm_inst.py`. This will break consumers — that is intentional and will be fixed in later phases.
+
+Renumber ALL enum values to match the 5-bit hardware opcode encoding from `design-notes/alu-and-output-design.md`. The Python IntEnum values become identical to the hardware opcodes — no mapping table needed. This changes the grouping: shifts move from ArithOp to their own positions (8-10), and logic ops move to positions 4-7.
+
+```python
+class ArithOp(ALUOp):
+    ADD = 0b00000      # 0
+    SUB = 0b00001      # 1
+    INC = 0b00010      # 2
+    DEC = 0b00011      # 3
+    # gap: 4-7 are LogicOp
+    SHL = 0b01000      # 8  (was SHIFT_L = 4)
+    SHR = 0b01001      # 9  (was SHIFT_R = 5)
+    ASR = 0b01010      # 10 (was ASHFT_R = 6)
+
+
+class LogicOp(ALUOp):
+    AND = 0b00100      # 4
+    OR  = 0b00101      # 5
+    XOR = 0b00110      # 6
+    NOT = 0b00111      # 7
+    # gap: 8-10 are ArithOp shifts
+    EQ  = 0b01011      # 11
+    LT  = 0b01100      # 12
+    LTE = 0b01101      # 13
+    GT  = 0b01110      # 14
+    GTE = 0b01111      # 15
+
+
+class RoutingOp(ALUOp):
+    BREQ         = 0b10000  # 16
+    BRGT         = 0b10001  # 17
+    BRGE         = 0b10010  # 18
+    BROF         = 0b10011  # 19
+    SWEQ         = 0b10100  # 20
+    SWGT         = 0b10101  # 21
+    SWGE         = 0b10110  # 22
+    SWOF         = 0b10111  # 23
+    GATE         = 0b11000  # 24
+    SEL          = 0b11001  # 25
+    MRGE         = 0b11010  # 26
+    PASS         = 0b11011  # 27
+    CONST        = 0b11100  # 28
+    FREE_FRAME   = 0b11101  # 29 (was FREE_CTX)
+    ALLOC_REMOTE = 0b11110  # 30
+    EXTRACT_TAG  = 0b11111  # 31 (reserved slot in design notes)
+```
+
+Shifts stay in `ArithOp` but are renamed (`SHIFT_L` → `SHL`, `SHIFT_R` → `SHR`, `ASHFT_R` → `ASR`) and renumbered to match the 5-bit hardware encoding (8-10 instead of 4-6). IntEnum doesn't require contiguous values, so the gap between DEC(3) and SHL(8) is fine.
+
+`ALLOC_REMOTE` (opcode 30) is new — constructs and emits a frame control token targeting another PE. See `design-notes/alu-and-output-design.md` Frame Management section.
+
+Update `_MONADIC_ARITH_OPS` and `_MONADIC_ROUTING_OPS`:
+
+```python
+_MONADIC_ARITH_OPS = frozenset({
+    ArithOp.INC,
+    ArithOp.DEC,
+    ArithOp.SHL,
+    ArithOp.SHR,
+    ArithOp.ASR,
+})
+
+_MONADIC_ROUTING_OPS = frozenset({
+    RoutingOp.PASS,
+    RoutingOp.CONST,
+    RoutingOp.FREE_FRAME,
+    RoutingOp.ALLOC_REMOTE,
+    RoutingOp.EXTRACT_TAG,
+})
+```
+
+`_MONADIC_LOGIC_OPS` remains unchanged — it contains `LogicOp.NOT` by enum identity (frozenset membership uses the enum member object, not the integer value, so the renumbering from 10 to 7 does not affect it).
+
+Add the following new types to `cm_inst.py`, after the existing `MemOp` enum but before `_MONADIC_ARITH_OPS`:
+
+```python
+from enum import Enum
+
+class OutputStyle(Enum):
+    INHERIT = 0
+    CHANGE_TAG = 1
+    SINK = 2
+
+
+class TokenKind(Enum):
+    DYADIC = 0
+    MONADIC = 1
+    INLINE = 2
+
+
+class FrameOp(IntEnum):
+    ALLOC = 0
+    FREE = 1
+
+
+@dataclass(frozen=True)
+class FrameDest:
+    target_pe: int
+    offset: int
+    act_id: int
+    port: Port
+    token_kind: TokenKind
+
+
+FrameSlotValue = int | FrameDest | None
+
+
+@dataclass(frozen=True)
+class Instruction:
+    opcode: ALUOp | MemOp
+    output: OutputStyle
+    has_const: bool
+    dest_count: int
+    wide: bool
+    fref: int
+```
+
+The `Instruction` dataclass has no stored `type` field — CM vs SM is derived via `isinstance(inst.opcode, MemOp)` per AC2.3.
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC2.1: `Instruction` dataclass can be constructed with all field types and is frozen
+- pe-frame-redesign.AC2.3: `isinstance(Instruction(opcode=MemOp.READ, ...).opcode, MemOp)` returns True; `isinstance(Instruction(opcode=ArithOp.ADD, ...).opcode, MemOp)` returns False
+- `FrameDest` is frozen and stores all fields correctly
+- `OutputStyle`, `TokenKind`, `FrameOp` enum values are correct
+- `RoutingOp.EXTRACT_TAG` exists with value 31 and `is_monadic_alu(RoutingOp.EXTRACT_TAG)` returns True
+- `RoutingOp.FREE_FRAME` exists with value 29
+- `RoutingOp.FREE_CTX` does NOT exist
+- `RoutingOp.ALLOC_REMOTE` exists with value 30 and `is_monadic_alu(RoutingOp.ALLOC_REMOTE)` returns True
+- `ArithOp.SHIFT_L`, `ArithOp.SHIFT_R`, `ArithOp.ASHFT_R` do NOT exist (renamed to SHL/SHR/ASR)
+- `ArithOp.SHL` exists with value 8, `ArithOp.SHR` with value 9, `ArithOp.ASR` with value 10
+- All ALUOp enum values fit in 5 bits (0-31)
+
+Test file: `tests/test_foundation_types.py`
+
+**Verification:**
+Run: `python -m pytest tests/test_foundation_types.py -v`
+Expected: Foundation type tests pass
+
+**Commit:** `feat: add Instruction, OutputStyle, FrameDest, TokenKind, FrameOp; renumber all opcodes to 5-bit hardware encoding; remove ALUInst, SMInst, Addr, FREE_CTX`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Restructure token hierarchy in tokens.py
+
+**Verifies:** pe-frame-redesign.AC1.1, pe-frame-redesign.AC1.2, pe-frame-redesign.AC1.3, pe-frame-redesign.AC1.4
+
+**Files:**
+- Modify: `tokens.py` (insert PEToken between Token and CMToken, add new token types, rename ctx→act_id, remove gen from DyadToken, remove IRAMWriteToken)
+
+**Implementation:**
+
+Rewrite `tokens.py` to the new hierarchy. The key changes:
+
+1. Add `PEToken(Token)` base class — carries only `target` (inherited from Token)
+2. `CMToken` now inherits from `PEToken` instead of `Token`
+3. Rename `CMToken.ctx` → `CMToken.act_id`
+4. Remove `DyadToken.gen` field
+5. Add `PELocalWriteToken(PEToken)` with `act_id`, `region`, `slot`, `data`, `is_dest` fields
+6. Add `FrameControlToken(PEToken)` with `act_id`, `op` (FrameOp), `payload` fields
+7. Remove `IRAMWriteToken` entirely
+
+The import from `cm_inst` no longer needs `ALUInst` or `SMInst` since `IRAMWriteToken` is gone:
+
+```python
+from dataclasses import dataclass
+from typing import Optional
+
+from cm_inst import FrameOp, MemOp, Port
+
+
+@dataclass(frozen=True)
+class Token:
+    target: int
+
+
+@dataclass(frozen=True)
+class PEToken(Token):
+    pass
+
+
+@dataclass(frozen=True)
+class CMToken(PEToken):
+    offset: int
+    act_id: int
+    data: int
+
+
+@dataclass(frozen=True)
+class DyadToken(CMToken):
+    port: Port
+    wide: bool
+
+
+@dataclass(frozen=True)
+class MonadToken(CMToken):
+    inline: bool
+
+
+@dataclass(frozen=True)
+class PELocalWriteToken(PEToken):
+    act_id: int
+    region: int
+    slot: int
+    data: int
+    is_dest: bool
+
+
+@dataclass(frozen=True)
+class FrameControlToken(PEToken):
+    act_id: int
+    op: FrameOp
+    payload: int
+
+
+@dataclass(frozen=True)
+class SMToken(Token):
+    addr: int
+    op: MemOp
+    flags: Optional[int]
+    data: Optional[int]
+    ret: Optional[CMToken]
+```
+
+Note: `PELocalWriteToken` and `FrameControlToken` have their own `act_id` field (not inherited from CMToken, since they don't carry `offset`/`data` with the same semantics).
+
+**Testing:**
+
+Tests must verify each AC:
+- pe-frame-redesign.AC1.1: `issubclass(CMToken, PEToken)`, `issubclass(PELocalWriteToken, PEToken)`, `issubclass(FrameControlToken, PEToken)`, and `issubclass(PEToken, Token)`
+- pe-frame-redesign.AC1.2: `CMToken` constructor uses `act_id` keyword (not `ctx`); `DyadToken` constructor has no `gen` parameter
+- pe-frame-redesign.AC1.3: `PELocalWriteToken` has `region`, `slot`, `data`, `is_dest` fields
+- pe-frame-redesign.AC1.4: `FrameControlToken` has `act_id`, `op`, `payload` fields; `op` accepts `FrameOp` values
+- `isinstance(DyadToken(...), PEToken)` returns True (transitive inheritance)
+- `isinstance(SMToken(...), PEToken)` returns False
+- All token types are frozen dataclasses
+- `IRAMWriteToken` does NOT exist in `tokens.py`
+
+Test file: `tests/test_foundation_types.py` (append to same file from Task 1)
+
+**Verification:**
+Run: `python -m pytest tests/test_foundation_types.py -v`
+Expected: Foundation type tests pass
+
+**Commit:** `feat: restructure token hierarchy with PEToken base, act_id rename, new token types; remove IRAMWriteToken`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Update conftest.py Hypothesis strategies
+
+**Verifies:** None (infrastructure — supports future test phases)
+
+**Files:**
+- Modify: `tests/conftest.py` (update strategies for ctx→act_id rename, gen removal)
+
+**Implementation:**
+
+Update the Hypothesis strategies to match the new token field names:
+
+1. `dyad_token` strategy: rename `ctx` parameter → `act_id`, remove `gen` parameter, update `DyadToken` constructor call
+2. `monad_token` strategy: rename `ctx` parameter → `act_id`, update `MonadToken` constructor call
+3. `sm_return_route` strategy: update `CMToken` constructor to use `act_id` instead of `ctx`
+4. `sm_token` strategy: update the embedded `CMToken` return route to use `act_id`
+5. Add new strategies for `PELocalWriteToken` and `FrameControlToken`
+
+Updated `dyad_token`:
+```python
[e-mail]
+def dyad_token(draw, target: int = 0, offset: int | None = None, act_id: int | None = None) -> DyadToken:
+    return DyadToken(
+        target=target,
+        offset=draw(st.integers(min_value=0, max_value=63)) if offset is None else offset,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        data=draw(uint16),
+        port=draw(st.sampled_from(list(Port))),
+        wide=False,
+    )
+```
+
+Updated `monad_token`:
+```python
[e-mail]
+def monad_token(draw, target: int = 0, offset: int | None = None, act_id: int | None = None) -> MonadToken:
+    return MonadToken(
+        target=target,
+        offset=draw(st.integers(min_value=0, max_value=63)) if offset is None else offset,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        data=draw(uint16),
+        inline=False,
+    )
+```
+
+Updated `sm_return_route`:
+```python
[e-mail]
+def sm_return_route(draw, target=0):
+    return CMToken(
+        target=target,
+        offset=draw(st.integers(min_value=0, max_value=63)),
+        act_id=draw(st.integers(min_value=0, max_value=7)),
+        data=0,
+    )
+```
+
+Updated `sm_token` (the embedded CMToken):
+```python
[e-mail]
+def sm_token(draw, addr=None, op=None, data=None):
+    _addr = draw(st.integers(min_value=0, max_value=255)) if addr is None else addr
+    _op = draw(sm_all_ops) if op is None else op
+    _data = draw(uint16) if data is None else data
+    ret = CMToken(target=0, offset=0, act_id=0, data=0)
+    return SMToken(
+        target=0,
+        addr=_addr,
+        op=_op,
+        flags=None,
+        data=_data,
+        ret=ret,
+    )
+```
+
+New strategies to add:
+```python
+from cm_inst import FrameOp
+from tokens import FrameControlToken, PELocalWriteToken
+
[e-mail]
+def pe_local_write_token(draw, target: int = 0, act_id: int | None = None) -> PELocalWriteToken:
+    return PELocalWriteToken(
+        target=target,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        region=draw(st.integers(min_value=0, max_value=1)),
+        slot=draw(st.integers(min_value=0, max_value=63)),
+        data=draw(uint16),
+        is_dest=draw(st.booleans()),
+    )
+
[e-mail]
+def frame_control_token(draw, target: int = 0, act_id: int | None = None) -> FrameControlToken:
+    return FrameControlToken(
+        target=target,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        op=draw(st.sampled_from(list(FrameOp))),
+        payload=draw(uint16),
+    )
+```
+
+Note: `act_id` range is 0-7 (3-bit), not 0-3 as the old `ctx` was. This matches the design's 3-bit activation ID with `frame_count` up to 8.
+
+Also update the `conftest.py` imports to include `FrameControlToken`, `PELocalWriteToken`, and `FrameOp`.
+
+**Verification:**
+Run: `python -m pytest tests/test_foundation_types.py -v`
+Expected: Foundation type tests pass (strategies are used by foundation type tests)
+
+**Commit:** `refactor: update Hypothesis strategies for act_id rename and new token types`
+
+<!-- END_TASK_3 -->
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_SUBCOMPONENT_B (tasks 4-6) -->
+<!-- START_TASK_4 -->
+### Task 4: Create encoding.py with pack/unpack boundary functions
+
+**Verifies:** pe-frame-redesign.AC2.2
+
+**Files:**
+- Create: `encoding.py` (project root, alongside cm_inst.py and tokens.py)
+
+**Implementation:**
+
+Create `encoding.py` containing the six boundary functions specified in the design. These convert between semantic Python types and 16-bit hardware word representations.
+
+The instruction word format is: `[type:1][opcode:5][mode:3][wide:1][fref:6]`
+
+Mode encoding uses the 3-bit table from `design-notes/alu-and-output-design.md`:
+
+```
+mode  tag behaviour   output behaviour
+----  -------------   --------------------------
+  0   INHERIT         single output, no constant
+  1   INHERIT         single output with constant
+  2   INHERIT         fan-out, no constant
+  3   INHERIT         fan-out with constant
+  4   CHANGE_TAG      dynamic routing, no constant
+  5   CHANGE_TAG      dynamic routing with constant
+  6   SINK            write result to frame, no output
+  7   SINK+CONST      read-modify-write frame slot
+```
+
+Bit-level decode (directly from mode[2:1:0]):
+```
+output_enable  = NOT mode[2]              modes 0-3
+change_tag     = mode[2] AND NOT mode[1]  modes 4-5
+sink           = mode[2] AND mode[1]      modes 6-7
+has_const      = mode[0]                  modes 1, 3, 5, 7
+has_fanout     = mode[1] AND NOT mode[2]  modes 2-3
+```
+
+Since the Python IntEnum values match the 5-bit hardware opcodes (set up in Task 1), opcode encoding is a trivial identity operation — no mapping table needed.
+
+```python
+from __future__ import annotations
+
+from cm_inst import (
+    ALUOp, ArithOp, FrameDest, Instruction, LogicOp, MemOp,
+    OutputStyle, Port, RoutingOp, TokenKind,
+)
+from tokens import (
+    CMToken, DyadToken, FrameControlToken, MonadToken,
+    PELocalWriteToken, PEToken, SMToken, Token,
+)
+
+
+def _encode_mode(output: OutputStyle, has_const: bool, dest_count: int) -> int:
+    """Encode OutputStyle + has_const + dest_count into 3-bit mode field.
+
+    Follows the mode table from design-notes/alu-and-output-design.md.
+    """
+    const_bit = int(has_const)
+    if output == OutputStyle.INHERIT:
+        if dest_count == 1:
+            return 0b000 | const_bit  # mode 0 or 1
+        elif dest_count == 2:
+            return 0b010 | const_bit  # mode 2 or 3
+        raise ValueError(f"INHERIT requires dest_count 1 or 2, got {dest_count}")
+    elif output == OutputStyle.CHANGE_TAG:
+        return 0b100 | const_bit      # mode 4 or 5
+    elif output == OutputStyle.SINK:
+        return 0b110 | const_bit      # mode 6 or 7
+    raise ValueError(f"Unknown OutputStyle: {output}")
+
+
+def _decode_mode(mode: int) -> tuple[OutputStyle, bool, int]:
+    """Decode 3-bit mode field into (OutputStyle, has_const, dest_count)."""
+    has_const = bool(mode & 0b001)
+    if not (mode & 0b100):
+        # modes 0-3: INHERIT
+        dest_count = 2 if (mode & 0b010) else 1
+        return OutputStyle.INHERIT, has_const, dest_count
+    elif not (mode & 0b010):
+        # modes 4-5: CHANGE_TAG
+        # dest_count=1 is nominal — CHANGE_TAG reads destination from the left
+        # operand (packed flit 1), not from frame slots. The PE ignores dest_count
+        # for CHANGE_TAG; this value exists only for round-trip consistency.
+        return OutputStyle.CHANGE_TAG, has_const, 1
+    else:
+        # modes 6-7: SINK
+        return OutputStyle.SINK, has_const, 0
+
+
+def _encode_opcode(opcode: ALUOp | MemOp) -> tuple[int, int]:
+    """Return (type_bit, 5-bit opcode).
+
+    Python IntEnum values match hardware encoding directly.
+    MemOp uses type_bit=1 with its own independent 5-bit opcode space.
+    ALUOp (ArithOp, LogicOp, RoutingOp) uses type_bit=0.
+    """
+    if isinstance(opcode, MemOp):
+        return 1, int(opcode) & 0x1F
+    return 0, int(opcode) & 0x1F
+
+
+def _decode_opcode(type_bit: int, raw_opcode: int) -> ALUOp | MemOp:
+    """Decode type_bit + 5-bit opcode into Python enum."""
+    if type_bit:
+        return MemOp(raw_opcode)
+    for cls in (ArithOp, LogicOp, RoutingOp):
+        try:
+            return cls(raw_opcode)
+        except ValueError:
+            continue
+    raise ValueError(f"Unknown ALU opcode: {raw_opcode}")
+
+
+def pack_instruction(inst: Instruction) -> int:
+    """Convert semantic Instruction to 16-bit hardware word.
+
+    Format: [type:1][opcode:5][mode:3][wide:1][fref:6]
+    """
+    type_bit, opcode_bits = _encode_opcode(inst.opcode)
+    mode_bits = _encode_mode(inst.output, inst.has_const, inst.dest_count)
+    wide_bit = int(inst.wide)
+    fref_bits = inst.fref & 0x3F
+    return (type_bit << 15) | (opcode_bits << 10) | (mode_bits << 7) | (wide_bit << 6) | fref_bits
+
+
+def unpack_instruction(word: int) -> Instruction:
+    """Convert 16-bit hardware word to semantic Instruction."""
+    type_bit = (word >> 15) & 1
+    opcode_raw = (word >> 10) & 0x1F
+    mode = (word >> 7) & 0x07
+    wide = bool((word >> 6) & 1)
+    fref = word & 0x3F
+
+    opcode = _decode_opcode(type_bit, opcode_raw)
+    output, has_const, dest_count = _decode_mode(mode)
+    return Instruction(
+        opcode=opcode,
+        output=output,
+        has_const=has_const,
+        dest_count=dest_count,
+        wide=wide,
+        fref=fref,
+    )
+```
+
+For the flit-level functions, the flit 1 format matches the hardware encoding from `architecture-overview.md`. Destinations are "pre-formed flit 1 values stored in frame slots" — the emulator uses the exact hardware bit layout so frame slots can be put on the bus verbatim.
+
+The encoding varies by token kind:
+
+```
+DYADIC:         [00][port:1][PE:2][offset:8][act_id:3]    = 16 bits
+MONADIC:        [010][PE:2][offset:8][act_id:3]           = 16 bits
+INLINE:         [011][PE:2][10][offset:7][spare:2]        = 16 bits
+```
+
+```python
+def pack_flit1(dest: FrameDest) -> int:
+    """Pack structured FrameDest to 16-bit flit 1 value.
+
+    Uses the exact hardware bit layout from architecture-overview.md.
+    """
+    if dest.token_kind == TokenKind.DYADIC:
+        # [00][port:1][PE:2][offset:8][act_id:3]
+        return (
+            ((dest.port & 0x1) << 13)
+            | ((dest.target_pe & 0x3) << 11)
+            | ((dest.offset & 0xFF) << 3)
+            | (dest.act_id & 0x7)
+        )
+    elif dest.token_kind == TokenKind.MONADIC:
+        # [010][PE:2][offset:8][act_id:3]
+        return (
+            (0b010 << 13)
+            | ((dest.target_pe & 0x3) << 11)
+            | ((dest.offset & 0xFF) << 3)
+            | (dest.act_id & 0x7)
+        )
+    else:
+        # INLINE: [011][PE:2][10][offset:7][spare:2]
+        return (
+            (0b011 << 13)
+            | ((dest.target_pe & 0x3) << 11)
+            | (0b10 << 9)
+            | ((dest.offset & 0x7F) << 2)
+        )
+
+
+def unpack_flit1(flit1: int) -> FrameDest:
+    """Unpack 16-bit flit 1 value to structured FrameDest."""
+    top2 = (flit1 >> 14) & 0x3
+    if top2 == 0b00:
+        # DYADIC WIDE
+        return FrameDest(
+            target_pe=(flit1 >> 11) & 0x3,
+            offset=(flit1 >> 3) & 0xFF,
+            act_id=flit1 & 0x7,
+            port=Port((flit1 >> 13) & 0x1),
+            token_kind=TokenKind.DYADIC,
+        )
+    elif (flit1 >> 13) == 0b010:
+        # MONADIC NORMAL
+        return FrameDest(
+            target_pe=(flit1 >> 11) & 0x3,
+            offset=(flit1 >> 3) & 0xFF,
+            act_id=flit1 & 0x7,
+            port=Port.L,
+            token_kind=TokenKind.MONADIC,
+        )
+    else:
+        # MONADIC INLINE: [011][PE:2][10][offset:7][spare:2]
+        return FrameDest(
+            target_pe=(flit1 >> 11) & 0x3,
+            offset=(flit1 >> 2) & 0x7F,
+            act_id=0,
+            port=Port.L,
+            token_kind=TokenKind.INLINE,
+        )
+```
+
+For `pack_token`, `unpack_token`, and `flit_count`, these encode/decode full Token objects as flit sequences using the exact hardware wire format from `architecture-overview.md`. Flit 1 is the first flit on the wire — it contains the prefix, routing, and type fields. Subsequent flits carry data.
+
+**Note on SMToken.ret:** The `ret` field (return route CMToken) is NOT preserved through pack/unpack. This is by design — in the frame model, SM return routes are stored as `FrameDest` values in frame slots, not embedded in the token. T0 storage only needs to hold the SM request parameters (target, addr, op, data, flags). The PE reads the return route from the frame when constructing the SMToken.
+
+```python
+def flit_count(flit1: int) -> int:
+    """Given flit 1 (the first/header flit), return total flit count for this packet."""
+    if flit1 & 0x8000:
+        # SM token: bit[15]=1. Standard = 2 flits, CAS/EXT = 3.
+        return 2
+    prefix3 = (flit1 >> 13) & 0x7
+    if prefix3 <= 0b001:
+        # Dyadic wide (00x): flit 1 + flit 2 (data)
+        return 2
+    elif prefix3 == 0b010:
+        # Monadic normal: flit 1 + flit 2 (data)
+        return 2
+    elif prefix3 == 0b011:
+        sub = (flit1 >> 9) & 0x3
+        if sub == 0b10:
+            # Monadic inline: 1 flit only (no data flit)
+            return 1
+        else:
+            # Frame control, PE-local write: flit 1 + flit 2
+            return 2
+    return 2
+
+
+def pack_token(token: Token) -> list[int]:
+    """Encode a token as a sequence of 16-bit flits.
+
+    Uses the exact hardware wire format. Flit 1 is the routing/header flit.
+    Used for T0 storage (EXEC reads these back) and future binary output.
+    """
+    if isinstance(token, DyadToken):
+        dest = FrameDest(
+            target_pe=token.target,
+            offset=token.offset,
+            act_id=token.act_id,
+            port=token.port,
+            token_kind=TokenKind.DYADIC,
+        )
+        flit1 = pack_flit1(dest)
+        flit2 = token.data & 0xFFFF
+        return [flit1, flit2]
+    elif isinstance(token, MonadToken):
+        kind = TokenKind.INLINE if token.inline else TokenKind.MONADIC
+        dest = FrameDest(
+            target_pe=token.target,
+            offset=token.offset,
+            act_id=token.act_id,
+            port=Port.L,
+            token_kind=kind,
+        )
+        flit1 = pack_flit1(dest)
+        if token.inline:
+            return [flit1]  # monadic inline: 1 flit only
+        flit2 = token.data & 0xFFFF
+        return [flit1, flit2]
+    elif isinstance(token, SMToken):
+        # SM: [1][SM_id:2][op:3][addr:10] (tier 1 layout)
+        flit1 = (1 << 15) | ((token.target & 0x3) << 13) | ((int(token.op) & 0x7) << 10) | (token.addr & 0x3FF)
+        flit2 = (token.data or 0) & 0xFFFF
+        return [flit1, flit2]
+    raise ValueError(f"Cannot pack token type: {type(token).__name__}")
+
+
+def unpack_token(flits: list[int]) -> Token:
+    """Decode a flit sequence into a Token object.
+
+    Flit 1 (flits[0]) is the header/routing flit. Decodes using hardware format.
+    """
+    flit1 = flits[0]
+
+    if flit1 & 0x8000:
+        # SM token: [1][SM_id:2][op:3][addr:10]
+        sm_id = (flit1 >> 13) & 0x3
+        op = MemOp((flit1 >> 10) & 0x7)
+        addr = flit1 & 0x3FF
+        return SMToken(
+            target=sm_id,
+            addr=addr,
+            op=op,
+            flags=None,
+            data=flits[1] if len(flits) > 1 else 0,
+            ret=None,
+        )
+
+    dest = unpack_flit1(flit1)
+
+    if dest.token_kind == TokenKind.DYADIC:
+        return DyadToken(
+            target=dest.target_pe,
+            offset=dest.offset,
+            act_id=dest.act_id,
+            data=flits[1] if len(flits) > 1 else 0,
+            port=dest.port,
+            wide=False,
+        )
+    elif dest.token_kind == TokenKind.INLINE:
+        return MonadToken(
+            target=dest.target_pe,
+            offset=dest.offset,
+            act_id=dest.act_id,
+            data=0,
+            inline=True,
+        )
+    else:
+        # MONADIC normal
+        return MonadToken(
+            target=dest.target_pe,
+            offset=dest.offset,
+            act_id=dest.act_id,
+            data=flits[1] if len(flits) > 1 else 0,
+            inline=False,
+        )
+```
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC2.2: `pack_instruction` / `unpack_instruction` round-trip for all valid mode combinations (modes 0-7 from design-notes table) × (wide True/False) × various opcodes (ArithOp, LogicOp, RoutingOp, MemOp) × fref values 0-63
+- Verify mode encoding matches design-notes bit decode: `_encode_mode(INHERIT, False, 1)` → 0, `_encode_mode(INHERIT, True, 2)` → 3, `_encode_mode(CHANGE_TAG, False, 1)` → 4, `_encode_mode(SINK, True, 0)` → 7
+- Verify opcode encoding is identity: `_encode_opcode(ArithOp.ADD)` → `(0, 0)`, `_encode_opcode(RoutingOp.BREQ)` → `(0, 16)`, `_encode_opcode(MemOp.READ)` → `(1, 0)`
+- `pack_flit1` / `unpack_flit1` round-trip for all CM token formats (various target_pe, offset, act_id, port, token_kind combinations)
+- `pack_token` / `unpack_token` round-trip for DyadToken, MonadToken, SMToken (note: SMToken.ret is NOT preserved — verify it round-trips as None)
+- `flit_count` returns correct counts for each prefix type
+- Edge cases: fref=0, fref=63, target_pe=0, target_pe=15, act_id=0, act_id=7
+
+Use Hypothesis property-based testing for round-trip verification — generate random valid Instruction/FrameDest values and verify pack→unpack identity.
+
+Test file: `tests/test_encoding.py`
+
+**Verification:**
+Run: `python -m pytest tests/test_encoding.py -v`
+Expected: Encoding tests pass
+
+**Commit:** `feat: create encoding.py with pack/unpack boundary functions`
+
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Update emu/events.py for frame-based events
+
+**Verifies:** pe-frame-redesign.AC1.6
+
+**Files:**
+- Modify: `emu/events.py` (rename Matched.ctx → act_id, add frame_id; add new event types; update SimEvent union)
+
+**Implementation:**
+
+Changes to `emu/events.py`:
+
+1. Update `Matched` — rename `ctx` to `act_id`, add `frame_id: int` field:
+```python
+@dataclass(frozen=True)
+class Matched:
+    time: float
+    component: str
+    left: int
+    right: int
+    act_id: int
+    offset: int
+    frame_id: int
+```
+
+2. Add four new event types after `ResultSent`:
+```python
+@dataclass(frozen=True)
+class FrameAllocated:
+    time: float
+    component: str
+    act_id: int
+    frame_id: int
+
+
+@dataclass(frozen=True)
+class FrameFreed:
+    time: float
+    component: str
+    act_id: int
+    frame_id: int
+
+
+@dataclass(frozen=True)
+class FrameSlotWritten:
+    time: float
+    component: str
+    frame_id: int
+    slot: int
+    value: int | None
+
+
+@dataclass(frozen=True)
+class TokenRejected:
+    time: float
+    component: str
+    token: Token
+    reason: str
+```
+
+3. Update the `SimEvent` union to include all new types:
+```python
+SimEvent = (
+    TokenReceived | Matched | Executed | Emitted | IRAMWritten
+    | CellWritten | DeferredRead | DeferredSatisfied | ResultSent
+    | FrameAllocated | FrameFreed | FrameSlotWritten | TokenRejected
+)
+```
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC1.6: `TokenRejected` event can be constructed with token and reason fields; it's a valid `SimEvent` member
+- `Matched` now uses `act_id` and has `frame_id`
+- All new event types are frozen dataclasses
+- All new event types are included in `SimEvent` union (isinstance checks)
+
+Test file: `tests/test_foundation_types.py` (append to existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_foundation_types.py -v`
+Expected: Foundation type tests pass
+
+**Commit:** `feat: add frame-based events and rename Matched.ctx to act_id`
+
+<!-- END_TASK_5 -->
+
+<!-- START_TASK_6 -->
+### Task 6: Update emu/types.py for frame-based PEConfig
+
+**Verifies:** None directly (infrastructure for Phase 2, but validates pe-frame-redesign.AC3.1 field existence)
+
+**Files:**
+- Modify: `emu/types.py` (replace MatchEntry and legacy PEConfig fields with frame-based config)
+
+**Implementation:**
+
+Remove `MatchEntry` entirely from `emu/types.py`. Remove the legacy fields `ctx_slots`, `offsets`, and `gen_counters` from `PEConfig`. Remove the `ALUInst`/`SMInst` import — `iram` now only holds `Instruction`.
+
+```python
+from cm_inst import FrameSlotValue, Instruction, Port
+from emu.events import EventCallback
+from sm_mod import Presence
+from tokens import CMToken
+
+
+@dataclass(frozen=True)
+class DeferredRead:
+    cell_addr: int
+    return_route: CMToken
+
+
+@dataclass(frozen=True)
+class PEConfig:
+    pe_id: int
+    iram: dict[int, Instruction]
+    frame_count: int = 8
+    frame_slots: int = 64
+    matchable_offsets: int = 8
+    initial_frames: Optional[dict[int, list[FrameSlotValue]]] = None
+    initial_tag_store: Optional[dict[int, int]] = None
+    allowed_pe_routes: Optional[set[int]] = None
+    allowed_sm_routes: Optional[set[int]] = None
+    on_event: EventCallback | None = None
+```
+
+Key changes:
+- `MatchEntry` removed entirely
+- `iram` type is now `dict[int, Instruction]` only
+- Legacy fields `ctx_slots`, `offsets`, `gen_counters` removed
+- Added `frame_count` (default 8), `frame_slots` (default 64), `matchable_offsets` (default 8)
+- Added `initial_frames` (dict mapping frame_id to slot value lists) and `initial_tag_store` (dict mapping act_id to frame_id)
+
+`SMConfig` is unchanged in this task.
+
+**Testing:**
+
+Tests must verify:
+- `PEConfig` can be constructed with new fields (`frame_count`, `frame_slots`, `matchable_offsets`)
+- `PEConfig` defaults are correct (frame_count=8, frame_slots=64, matchable_offsets=8)
+- `PEConfig` accepts `Instruction` objects in `iram`
+- `initial_frames` and `initial_tag_store` can be set
+- `MatchEntry` does NOT exist in `emu/types.py`
+
+Test file: `tests/test_foundation_types.py` (append)
+
+**Verification:**
+Run: `python -m pytest tests/test_foundation_types.py -v`
+Expected: Foundation type tests pass
+
+**Commit:** `feat: replace MatchEntry and legacy PEConfig fields with frame-based config`
+
+<!-- END_TASK_6 -->
+<!-- END_SUBCOMPONENT_B -->
+
+<!-- START_TASK_7 -->
+### Task 7: Record test breakage
+
+**Verifies:** None (breakage inventory)
+
+**Files:**
+- No file changes — verification only
+
+**Step 1: Run full test suite**
+
+Run: `python -m pytest tests/ -v`
+
+Expected: Many tests will fail due to removed types (`ALUInst`, `SMInst`, `IRAMWriteToken`, `MatchEntry`, `FREE_CTX`), renamed fields (`ctx` → `act_id`, `gen` removed), and restructured hierarchy. This is expected.
+
+**Step 2: Record what breaks**
+
+List all failing tests and the reason for each failure. This inventory will guide the per-phase fix work in Phases 2–8. Do NOT attempt to fix anything here.
+
+<!-- END_TASK_7 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_02.md

···
+# PE Frame-Based Redesign — Phase 2: Emulator Core — PE Rewrite
+
+**Goal:** Rewrite `ProcessingElement` with frame-based matching, reversed pipeline order (IFETCH before MATCH), mode-driven output routing via `OutputStyle`, and PE-level EXTRACT_TAG handling.
+
+**Architecture:** Replace the `matching_store` 2D array + `gen_counters` with `frames` (list of frame slot arrays), `tag_store` (act_id → frame_id mapping), `presence` (per-frame dense match metadata indexed by match slot), `port_store` (per-frame port metadata), and `free_frames` (available frame IDs). Match operands are stored in the frame's low slots (0 to `matchable_offsets - 1`), indexed by the token's IRAM offset (`token.offset`). Constants and destinations are in higher frame slots, indexed by the instruction's `fref` field per the mode table. Pipeline becomes IFETCH → act_id resolution → MATCH/FRAME → EXECUTE → EMIT. Output routing is driven by `Instruction.output` (OutputStyle enum) rather than `_output_mode()` reading dest_l/dest_r from ALUInst. The PE only handles `Instruction` objects — legacy ALUInst/SMInst are gone.
+
+**Tech Stack:** Python 3.12, SimPy 4.1
+
+**Scope:** Phase 2 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC3: Frame-based PE matching and output routing
+- **pe-frame-redesign.AC3.1 Success:** PE constructor accepts `frame_count`, `frame_slots`, `matchable_offsets` as configurable parameters
+- **pe-frame-redesign.AC3.2 Success:** Pipeline order is IFETCH → act_id resolution → MATCH/FRAME → EXECUTE → EMIT
+- **pe-frame-redesign.AC3.3 Success:** Dyadic matching uses tag store + presence bits + frame SRAM (not matching_store array)
+- **pe-frame-redesign.AC3.4 Success:** INHERIT output reads `FrameDest` from frame slot and constructs token directly
+- **pe-frame-redesign.AC3.5 Success:** CHANGE_TAG output calls `unpack_flit1()` on left operand to get `FrameDest`
+- **pe-frame-redesign.AC3.6 Success:** SINK output writes result to `frames[frame_id][fref]`, emits no token
+- **pe-frame-redesign.AC3.7 Success:** EXTRACT_TAG handled PE-level (not ALU), produces packed flit 1 via `pack_flit1()`
+- **pe-frame-redesign.AC3.8 Success:** Frame allocation (ALLOC) and deallocation (FREE) via FrameControlToken work correctly
+- **pe-frame-redesign.AC3.9 Success:** PELocalWriteToken with `is_dest=True` decodes data to FrameDest on write
+- **pe-frame-redesign.AC3.10 Success:** Pipeline timing preserved: 5 cycles dyadic, 4 cycles monadic, 1 cycle side paths
+
+### pe-frame-redesign.AC1: Token hierarchy correctly models frame-based architecture
+- **pe-frame-redesign.AC1.5 Success:** Network routing uses `isinstance(token, PEToken)` for all PE-bound tokens
+- **pe-frame-redesign.AC1.6 Failure:** Token with invalid `act_id` (no tag store mapping) is dropped with `TokenRejected` event
+
+---
+
+<!-- START_SUBCOMPONENT_A (tasks 1-2) -->
+<!-- START_TASK_1 -->
+### Task 1: Update emu/alu.py for opcode renames
+
+**Verifies:** None (infrastructure — prerequisite for PE rewrite)
+
+**Files:**
+- Modify: `emu/alu.py` (rename shift ops and FREE_CTX, add EXTRACT_TAG and ALLOC_REMOTE)
+
+**Implementation:**
+
+Phase 1 renumbers all opcodes and renames shifts (`SHIFT_L` → `SHL`, `SHIFT_R` → `SHR`, `ASHFT_R` → `ASR`). Shifts stay in `ArithOp`, so no structural change to ALU dispatch. Update `emu/alu.py`:
+
+1. In `_execute_arith()`: rename match cases:
+   ```python
+   case ArithOp.SHL:       # was SHIFT_L
+       result = (left << const) & UINT16_MASK
+   case ArithOp.SHR:       # was SHIFT_R
+       result = (left >> const) & UINT16_MASK
+   case ArithOp.ASR:       # was ASHFT_R
+       signed = to_signed(left)
+       result = (signed >> const) & UINT16_MASK
+   ```
+
+2. In `_execute_routing()`: rename `FREE_CTX` → `FREE_FRAME`, add `EXTRACT_TAG` and `ALLOC_REMOTE` as no-op fallbacks (both handled at PE level):
+   ```python
+   case RoutingOp.FREE_FRAME:
+       return 0, False
+   case RoutingOp.EXTRACT_TAG:
+       return 0, False
+   case RoutingOp.ALLOC_REMOTE:
+       return 0, False
+   ```
+
+**Verification:**
+Run: `python -m pytest tests/test_alu.py -v`
+Expected: All ALU tests pass
+
+**Commit:** `refactor: rename shift ops (SHL/SHR/ASR), FREE_CTX→FREE_FRAME, add EXTRACT_TAG and ALLOC_REMOTE`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Rewrite ProcessingElement in emu/pe.py
+
+**Verifies:** pe-frame-redesign.AC3.1, pe-frame-redesign.AC3.2, pe-frame-redesign.AC3.3, pe-frame-redesign.AC3.4, pe-frame-redesign.AC3.5, pe-frame-redesign.AC3.6, pe-frame-redesign.AC3.7, pe-frame-redesign.AC3.8, pe-frame-redesign.AC3.9, pe-frame-redesign.AC3.10, pe-frame-redesign.AC1.6
+
+**Files:**
+- Modify: `emu/pe.py` (full rewrite of ProcessingElement class)
+
+**Implementation:**
+
+This is a full rewrite. The new `ProcessingElement` replaces the matching_store/gen_counters model with frames/tag_store/presence. There is no legacy path — the PE only handles `Instruction` objects.
+
+**Constructor changes:**
+
+Replace the old constructor parameters and instance variables. The PE now accepts:
+- `frame_count` (from PEConfig, default 8)
+- `frame_slots` (from PEConfig, default 64)
+- `matchable_offsets` (from PEConfig, default 8)
+- `initial_frames` and `initial_tag_store` (optional, for pre-loaded state)
+
+New instance variables:
+```python
+self.frames: list[list[FrameSlotValue]]       # [frame_count][frame_slots] — all per-activation data
+self.tag_store: dict[int, int]                 # act_id → frame_id
+self.presence: list[list[bool]]                # [frame_count][matchable_offsets] — match pending
+self.port_store: list[list[Port | None]]       # [frame_count][matchable_offsets] — port of pending operand
+self.free_frames: list[int]                    # available frame IDs
+```
+
+Match metadata (`presence`, `port_store`) is a dense, small structure — one entry per matchable offset per frame, NOT one per frame slot. The match slot index is derived from the low bits of the token's IRAM offset: `match_slot = token.offset % matchable_offsets`. This allows dyadic instructions to be placed at ANY IRAM offset — the assembler just ensures no two simultaneously-live dyadic instructions in the same activation collide in their low-bit hash. Match operands are stored in `frames[frame_id][match_slot]`. `fref` is separate — it indexes into the frame for const/dest reads by the output formatter.
+
+Remove: `matching_store`, `gen_counters`, `_ctx_slots`, `_offsets`
+
+The `iram` type is `dict[int, Instruction]`.
+
+**Updated imports:**
+
+```python
+import logging
+from typing import Optional
+
+import simpy
+
+from cm_inst import (
+    ALUOp, ArithOp, FrameDest, FrameOp, FrameSlotValue,
+    Instruction, LogicOp, MemOp, OutputStyle, Port, RoutingOp,
+    TokenKind, is_monadic_alu,
+)
+from encoding import pack_flit1, unpack_flit1, unpack_instruction
+from emu.alu import execute
+from emu.events import (
+    Emitted, EventCallback, Executed, FrameAllocated, FrameFreed,
+    FrameSlotWritten, IRAMWritten, Matched, TokenReceived, TokenRejected,
+)
+from tokens import (
+    CMToken, DyadToken, FrameControlToken,
+    MonadToken, PELocalWriteToken, PEToken, SMToken,
+)
+```
+
+**Pipeline rewrite — `_process_token()`:**
+
+The new pipeline order is:
+1. Side path handling (PELocalWriteToken, FrameControlToken) — 1 cycle each
+2. For CMTokens (DyadToken, MonadToken):
+   a. IFETCH — look up IRAM by `token.offset` (1 cycle)
+   b. Act_id resolution — validate `token.act_id` against tag_store
+   c. MATCH — for dyadic: presence-based matching on `frames[frame_id][token.offset % matchable_offsets]`
+   d. EXECUTE — ALU execute or SM dispatch (1 cycle)
+   e. EMIT — mode-driven output routing (1 cycle)
+
+**Side path: FrameControlToken handling:**
+
+```python
+if isinstance(token, FrameControlToken):
+    self._handle_frame_control(token)
+    yield self.env.timeout(1)
+    return
+```
+
+`_handle_frame_control`:
+- ALLOC: pop frame_id from `free_frames`, set `tag_store[token.act_id] = frame_id`, initialise frame slots to None, emit `FrameAllocated` event
+- FREE: look up frame_id from tag_store, remove tag_store entry, push frame_id back to `free_frames`, emit `FrameFreed` event. Frame slot data is NOT cleared (stale data overwritten on next ALLOC, matching hardware)
+
+**Side path: PELocalWriteToken handling:**
+
+```python
+if isinstance(token, PELocalWriteToken):
+    self._handle_local_write(token)
+    yield self.env.timeout(1)
+    return
+```
+
+`_handle_local_write`:
+- `region=0`: IRAM write — `self.iram[token.slot] = unpack_instruction(token.data)`, emit `IRAMWritten` event
+- `region=1`: Frame write — look up `frame_id = self.tag_store[token.act_id]`, write to `self.frames[frame_id][token.slot]`. If `token.is_dest` is True, decode `token.data` via `unpack_flit1()` and store the resulting `FrameDest`. Otherwise store `token.data` as int. Emit `FrameSlotWritten` event.
+
+**Main pipeline for CMTokens:**
+
+```python
+# IFETCH (1 cycle)
+inst = self.iram.get(token.offset)
+yield self.env.timeout(1)
+if inst is None:
+    logger.warning("PE %d: no instruction at offset %d", self.pe_id, token.offset)
+    return
+
+# Act_id resolution
+if token.act_id not in self.tag_store:
+    self._on_event(TokenRejected(
+        time=self.env.now, component=self._component,
+        token=token, reason=f"act_id {token.act_id} not in tag store",
+    ))
+    return
+frame_id = self.tag_store[token.act_id]
+```
+
+**Matching:**
+
+Determine monadic/dyadic from the token type:
+
+```python
+if isinstance(token, MonadToken):
+    left, right = token.data, None
+elif isinstance(token, DyadToken):
+    if is_monadic_alu(inst.opcode) if isinstance(inst.opcode, ALUOp) else True:  # all SM ops are monadic
+        left, right = token.data, None
+    else:
+        # Dyadic matching via presence bits
+        operands = self._match_frame(token, inst, frame_id)
+        yield self.env.timeout(1)  # match cycle
+        if operands is None:
+            return  # waiting for partner
+        left, right = operands
+else:
+    return
+
+# EXECUTE
+if isinstance(inst.opcode, MemOp):
+    yield self.env.timeout(1)
+    self._build_and_emit_sm_new(inst, left, right, token.act_id, frame_id)
+    yield self.env.timeout(1)
+elif inst.opcode == RoutingOp.EXTRACT_TAG:
+    # PE-level: pack current PE/act_id/offset into flit 1
+    yield self.env.timeout(1)
+    result = pack_flit1(FrameDest(
+        target_pe=self.pe_id,
+        offset=token.offset,
+        act_id=token.act_id,
+        port=Port.L,
+        token_kind=TokenKind.DYADIC,
+    ))
+    self._on_event(Executed(
+        time=self.env.now, component=self._component,
+        op=inst.opcode, result=result, bool_out=False,
+    ))
+    self._do_emit_new(inst, result, False, token.act_id, frame_id)
+    yield self.env.timeout(1)
+elif inst.opcode == RoutingOp.ALLOC_REMOTE:
+    # PE-level: read target PE and act_id from frame constants, construct
+    # and deliver a FrameControlToken(ALLOC) to the target PE.
+    # fref points to const/dest slots (mode table). ALLOC_REMOTE reads
+    # target PE and act_id from frame constants at fref, fref+1.
+    yield self.env.timeout(1)
+    target_pe = self.frames[frame_id][inst.fref]       # target PE id from frame constant
+    target_act = self.frames[frame_id][inst.fref + 1]  # target act_id from frame constant
+    fct = FrameControlToken(
+        target=target_pe,
+        act_id=target_act,
+        op=FrameOp.ALLOC,
+        payload=0,
+    )
+    self._on_event(Executed(
+        time=self.env.now, component=self._component,
+        op=inst.opcode, result=0, bool_out=False,
+    ))
+    self.env.process(self._deliver(self.route_table[target_pe], fct))
+    yield self.env.timeout(1)
+elif inst.opcode == RoutingOp.FREE_FRAME:
+    # Deallocate frame: clear tag_store entry, return frame to free pool.
+    # Frame slot data is NOT cleared — stale data is harmless (overwritten
+    # on next ALLOC). This matches hardware behavior.
+    yield self.env.timeout(1)
+    result, bool_out = execute(inst.opcode, left, right, None)
+    self._on_event(Executed(...))
+    if token.act_id in self.tag_store:
+        freed_frame = self.tag_store.pop(token.act_id)
+        self.free_frames.append(freed_frame)
+        self._on_event(FrameFreed(
+            time=self.env.now, component=self._component,
+            act_id=token.act_id, frame_id=freed_frame,
+        ))
+    # No emit — FREE_FRAME suppresses output
+    yield self.env.timeout(1)
+else:
+    # Normal ALU execute
+    # fref points to const/dest per mode table. For modes 1/3/5/7: const at fref.
+    const_val = self.frames[frame_id][inst.fref] if inst.has_const else None
+    result, bool_out = execute(inst.opcode, left, right, const_val)
+    self._on_event(Executed(
+        time=self.env.now, component=self._component,
+        op=inst.opcode, result=result, bool_out=bool_out,
+    ))
+    yield self.env.timeout(1)
+    self._do_emit_new(inst, result, bool_out, token.act_id, frame_id, left=left)
+    yield self.env.timeout(1)
+```
+
+**Frame-based matching — `_match_frame()`:**
+
+Matching derives the match slot from the low bits of the token's IRAM offset: `match_slot = token.offset % matchable_offsets`. Dyadic instructions can be at any IRAM offset — the assembler ensures no two simultaneously-live dyadic instructions in the same activation collide in their match slot. `fref` is separate — it points to const/dest slots for the output formatter.
+
+Both L and R tokens for the same instruction write to `frames[frame_id][match_slot]`. The stored port metadata determines left/right ordering when the second token arrives.
+
+```python
+def _match_frame(self, token: DyadToken, inst: Instruction, frame_id: int) -> tuple[int, int] | None:
+    match_slot = token.offset % self._matchable_offsets  # low bits of IRAM offset
+
+    if self.presence[frame_id][match_slot]:
+        # Partner already waiting — pair them
+        partner_data = self.frames[frame_id][match_slot]
+        partner_port = self.port_store[frame_id][match_slot]
+        self.presence[frame_id][match_slot] = False
+        self.frames[frame_id][match_slot] = None
+
+        # Use port metadata to determine left/right ordering
+        if partner_port == Port.L:
+            left, right = partner_data, token.data
+        else:
+            left, right = token.data, partner_data
+
+        self._on_event(Matched(
+            time=self.env.now, component=self._component,
+            left=left, right=right, act_id=token.act_id,
+            offset=token.offset, frame_id=frame_id,
+        ))
+        return left, right
+    else:
+        # Store and wait for partner
+        self.frames[frame_id][match_slot] = token.data
+        self.port_store[frame_id][match_slot] = token.port
+        self.presence[frame_id][match_slot] = True
+        return None
+```
+
+**Mode-driven output routing — `_do_emit_new()`:**
+
+Note: `left` operand must be preserved through the execute stage and passed here for CHANGE_TAG routing. The PE's execute path must thread `left` alongside `result`.
+
+```python
+def _do_emit_new(self, inst: Instruction, result: int, bool_out: bool, act_id: int, frame_id: int, left: int = 0):
+    if isinstance(inst.opcode, RoutingOp) and inst.opcode == RoutingOp.GATE and not bool_out:
+        return  # GATE suppressed
+
+    match inst.output:
+        case OutputStyle.INHERIT:
+            self._emit_inherit(inst, result, bool_out, frame_id)
+        case OutputStyle.CHANGE_TAG:
+            self._emit_change_tag(inst, result, left)
+        case OutputStyle.SINK:
+            self._emit_sink(inst, result, frame_id)
+```
+
+**INHERIT output — `_emit_inherit()`:**
+
+Read `FrameDest` from frame slots starting at `inst.fref`. The mode table defines the layout starting from fref: mode 0 = `[dest]`, mode 1 = `[const, dest]`, mode 2 = `[dest1, dest2]`, mode 3 = `[const, dest1, dest2]`. Match operands are in a separate region (indexed by token.offset, slots 0–7); fref points to const/dest slots only.
+
+```python
+def _emit_inherit(self, inst: Instruction, result: int, bool_out: bool, frame_id: int):
+    # fref is the base of [const?, dest1, dest2?] — see mode table.
+    # If has_const, const is at fref and dests start at fref+1.
+    # If no const, dests start at fref.
+    dest_base = inst.fref + (1 if inst.has_const else 0)
+
+    if inst.dest_count >= 1:
+        dest_l: FrameDest = self.frames[frame_id][dest_base]
+        out_token = self._make_token_from_dest(dest_l, result)
+        self.output_log.append(out_token)
+        self._on_event(Emitted(time=self.env.now, component=self._component, token=out_token))
+        self.env.process(self._deliver(self.route_table[dest_l.target_pe], out_token))
+
+    if inst.dest_count >= 2:
+        dest_r: FrameDest = self.frames[frame_id][dest_base + 1]
+        # For switch ops, route based on bool_out
+        if isinstance(inst.opcode, RoutingOp) and inst.opcode in (
+            RoutingOp.SWEQ, RoutingOp.SWGT, RoutingOp.SWGE, RoutingOp.SWOF,
+        ):
+            # Undo the dest_l append above — switch re-routes both outputs
+            self.output_log.pop()
+            if bool_out:
+                taken, not_taken = dest_l, dest_r
+            else:
+                taken, not_taken = dest_r, dest_l
+            data_tok = self._make_token_from_dest(taken, result)
+            trig_tok = self._make_token_from_dest(not_taken, 0)
+            self.output_log.append(data_tok)
+            self.output_log.append(trig_tok)
+            # ... events and delivery for both tokens
+        else:
+            out_r = self._make_token_from_dest(dest_r, result)
+            self.output_log.append(out_r)
+            self._on_event(Emitted(time=self.env.now, component=self._component, token=out_r))
+            self.env.process(self._deliver(self.route_table[dest_r.target_pe], out_r))
+```
+
+**CHANGE_TAG output — `_emit_change_tag()`:**
+
+The left operand carries the packed flit 1 (destination descriptor from the caller's EXTRACT_TAG). The ALU result is the data payload to send. These are distinct values — `left` determines WHERE to send, `result` determines WHAT to send.
+
+```python
+def _emit_change_tag(self, inst: Instruction, result: int, left: int):
+    dest = unpack_flit1(left)
+    out_token = self._make_token_from_dest(dest, result)
+    self.output_log.append(out_token)
+    self._on_event(Emitted(time=self.env.now, component=self._component, token=out_token))
+    self.env.process(self._deliver(self.route_table[dest.target_pe], out_token))
+```
+
+**SM dispatch — `_build_and_emit_sm_new()`:**
+
+For SM instructions (where `isinstance(inst.opcode, MemOp)`), the PE constructs an SMToken. The return route is a FrameDest stored in the frame slot following the mode table layout at `inst.fref`. The `FrameDest.token_kind` determines whether the SM return token will be a DyadToken or MonadToken — this replaces the old `SMInst.ret_dyadic` field.
+
+```python
+def _build_and_emit_sm_new(self, inst: Instruction, left: int, right: int, act_id: int, frame_id: int):
+    # fref layout per mode table: [const?, dest]. For SM ops with return routes,
+    # the dest slot holds the return FrameDest.
+    ret_slot = inst.fref + (1 if inst.has_const else 0)
+    ret_dest: FrameDest | None = self.frames[frame_id][ret_slot] if inst.dest_count > 0 else None
+
+    # Build return CMToken from FrameDest if return route exists
+    ret_token: CMToken | None = None
+    if ret_dest is not None:
+        ret_token = self._make_token_from_dest(ret_dest, 0)  # data will be filled by SM
+
+    # SM target (SM_id + address) can come from frame[fref] OR from
+    # operand data, depending on the operation. The exact source mapping
+    # is determined by the instruction's mode and opcode — the assembler's
+    # codegen sets up frame slots and operand routing accordingly.
+    # Flit 2 source (ALU out / R operand / frame slot) also varies by
+    # operation — see pe-design.md flit 2 source mux table.
+    #
+    # For the emulator, we dispatch based on has_const: when the instruction
+    # has a constant (frame[fref] holds SM params), target comes from frame.
+    # Otherwise, target comes from the left operand.
+    if inst.has_const:
+        target_packed = self.frames[frame_id][inst.fref]
+    else:
+        target_packed = left
+    sm_token = SMToken(
+        target=(target_packed >> 8) & 0xFF,
+        addr=target_packed & 0xFF,
+        op=inst.opcode,
+        flags=right if right is not None else None,
+        data=right if inst.has_const else left,
+        ret=ret_token,
+    )
+    self.output_log.append(sm_token)
+    self._on_event(Emitted(time=self.env.now, component=self._component, token=sm_token))
+    self.env.process(self._deliver(self.sm_routes[sm_token.target], sm_token))
+```
+
+Note: SM target source (frame slot vs operand) depends on the operation and mode. The `has_const` dispatch above is a simplified emulator heuristic — the hardware uses the instruction decoder EEPROM to select the source mux. The return route's token kind comes from `FrameDest.token_kind` in the frame slot, not from a separate instruction field.
+
+**SINK output — `_emit_sink()`:**
+
+```python
+def _emit_sink(self, inst: Instruction, result: int, frame_id: int):
+    self.frames[frame_id][inst.fref] = result
+    self._on_event(FrameSlotWritten(
+        time=self.env.now, component=self._component,
+        frame_id=frame_id, slot=inst.fref, value=result,
+    ))
+    # No output token emitted
+```
+
+**Token construction from FrameDest — `_make_token_from_dest()`:**
+
+```python
+def _make_token_from_dest(self, dest: FrameDest, data: int) -> CMToken:
+    match dest.token_kind:
+        case TokenKind.DYADIC:
+            return DyadToken(
+                target=dest.target_pe, offset=dest.offset,
+                act_id=dest.act_id, data=data,
+                port=dest.port, wide=False,
+            )
+        case TokenKind.MONADIC:
+            return MonadToken(
+                target=dest.target_pe, offset=dest.offset,
+                act_id=dest.act_id, data=data, inline=False,
+            )
+        case TokenKind.INLINE:
+            return MonadToken(
+                target=dest.target_pe, offset=dest.offset,
+                act_id=dest.act_id, data=data, inline=True,
+            )
+```
+
+**Timing invariants:**
+- Dyadic CMToken: dequeue(1) + IFETCH(1) + MATCH(1) + EXECUTE(1) + EMIT(1) = 5 cycles
+- Monadic CMToken: dequeue(1) + IFETCH(1) + EXECUTE(1) + EMIT(1) = 4 cycles
+- FrameControlToken / PELocalWriteToken: dequeue(1) + handle(1) = 2 cycles (1 cycle side path after dequeue)
+
+**Testing:**
+
+Tests must verify each AC:
+- pe-frame-redesign.AC3.1: Construct PE with `frame_count=4`, `frame_slots=32`, `matchable_offsets=4` and verify they're stored
+- pe-frame-redesign.AC3.2: Inject a DyadToken pair, capture events, verify event order is TokenReceived → Matched → Executed → Emitted (IFETCH is implicit before match)
+- pe-frame-redesign.AC3.3: Set up tag_store and frame with presence bits, inject two DyadTokens at same offset/act_id, verify they match via frame SRAM (not matching_store)
+- pe-frame-redesign.AC3.4: Set up frame with FrameDest in destination slot, inject tokens, verify output token has target/offset/act_id from the FrameDest
+- pe-frame-redesign.AC3.5: Set up CHANGE_TAG instruction, inject token whose left operand is a packed flit 1 value, verify output token destination matches unpacked FrameDest
+- pe-frame-redesign.AC3.6: Set up SINK instruction, inject tokens, verify result written to frame slot and no output token emitted
+- pe-frame-redesign.AC3.7: Set up EXTRACT_TAG instruction, inject MonadToken, verify result is packed flit 1 of (pe_id, offset, act_id, port, kind)
+- pe-frame-redesign.AC3.8: Inject FrameControlToken(ALLOC), verify tag_store updated and FrameAllocated event. Inject FrameControlToken(FREE), verify tag_store cleared and FrameFreed event. Also test FREE_FRAME opcode path: set up a FREE_FRAME instruction in IRAM, inject a MonadToken, verify tag_store cleared, frame returned to free_frames, FrameFreed event emitted, and no output token produced. Also test ALLOC_REMOTE: set up ALLOC_REMOTE instruction with target PE/act_id in frame slots, inject MonadToken, verify a FrameControlToken(ALLOC) is delivered to the target PE's input store.
+- pe-frame-redesign.AC3.9: Inject PELocalWriteToken(region=1, is_dest=True, data=pack_flit1(some_dest)), verify frame slot contains FrameDest object (not raw int)
+- pe-frame-redesign.AC3.10: Time dyadic pair processing, verify 5 cycles. Time monadic, verify 4 cycles. Time side paths, verify 1 cycle after dequeue.
+- pe-frame-redesign.AC1.6: Inject DyadToken with act_id not in tag_store, verify TokenRejected event and no crash
+
+Test file: `tests/test_pe_frames.py` (new file)
+
+**Verification:**
+Run: `python -m pytest tests/test_pe_frames.py -v`
+Expected: All new frame-based tests pass. Legacy PE tests (test_pe_events.py, test_cycle_timing.py) will break — they will be fixed in the cleanup/E2E phase.
+
+**Commit:** `feat: rewrite ProcessingElement with frame-based matching and output routing`
+
+<!-- END_TASK_2 -->
+<!-- END_SUBCOMPONENT_A -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_03.md

···
+# PE Frame-Based Redesign — Phase 3: Emulator Supporting — SM, Network, ALU
+
+**Goal:** Update SM for T0 raw int storage, network for PEToken routing, and wire everything together with new PEConfig fields.
+
+**Architecture:** SM's `t0_store` changes from `list[Token]` to `list[int]`. EXEC handler uses `flit_count()` + `unpack_token()` to reconstitute tokens from raw int sequences. Network routing changes from `isinstance(token, CMToken)` to `isinstance(token, PEToken)` to route all PE-bound tokens (CMToken, PELocalWriteToken, FrameControlToken). `build_topology()` passes new PEConfig frame parameters to ProcessingElement constructor.
+
+**Tech Stack:** Python 3.12, SimPy 4.1
+
+**Scope:** Phase 3 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC4: T0 raw storage and EXEC
+- **pe-frame-redesign.AC4.1 Success:** SM T0 stores `list[int]` (16-bit words), not Token objects
+- **pe-frame-redesign.AC4.2 Success:** EXEC reads consecutive ints, uses `flit_count()` for packet boundaries, reconstitutes tokens via `unpack_token()`
+- **pe-frame-redesign.AC4.3 Success:** `pack_token()` / `unpack_token()` round-trip for all token types
+- **pe-frame-redesign.AC4.4 Failure:** Malformed flit sequence in T0 (invalid prefix bits) is handled gracefully
+
+### pe-frame-redesign.AC1: Token hierarchy correctly models frame-based architecture
+- **pe-frame-redesign.AC1.5 Success:** Network routing uses `isinstance(token, PEToken)` for all PE-bound tokens
+
+---
+
+<!-- START_SUBCOMPONENT_A (tasks 1-2) -->
+<!-- START_TASK_1 -->
+### Task 1: Update SM for T0 raw int storage and EXEC
+
+**Verifies:** pe-frame-redesign.AC4.1, pe-frame-redesign.AC4.2, pe-frame-redesign.AC4.4
+
+**Files:**
+- Modify: `emu/sm.py` (change t0_store type, rewrite EXEC handler, update T0 WRITE)
+
+**Implementation:**
+
+Changes to `emu/sm.py`:
+
+1. Change `t0_store` type from `list[Token]` to `list[int]`:
+```python
+self.t0_store: list[int] = []
+```
+
+2. Add import for encoding functions:
+```python
+from encoding import flit_count, unpack_token
+```
+
+3. Rewrite `_handle_exec()` to parse raw ints using flit boundaries:
+
+```python
+def _handle_exec(self, addr: int):
+    """EXEC: read raw int sequences from T0, reconstitute tokens, inject into network."""
+    if self.system is None:
+        logger.warning("SM%d: EXEC but no system reference", self.sm_id)
+        return
+    t0_idx = addr - self.tier_boundary
+    if t0_idx >= len(self.t0_store):
+        return
+    yield self.env.timeout(1)  # process cycle
+
+    pos = t0_idx
+    while pos < len(self.t0_store):
+        header = self.t0_store[pos]
+        if header is None:
+            break
+        try:
+            count = flit_count(header)
+        except (ValueError, KeyError):
+            logger.warning("SM%d: malformed flit at T0[%d], stopping EXEC", self.sm_id, pos)
+            break
+        if pos + count > len(self.t0_store):
+            logger.warning("SM%d: truncated packet at T0[%d], stopping EXEC", self.sm_id, pos)
+            break
+        flits = self.t0_store[pos:pos + count]
+        try:
+            token = unpack_token(flits)
+        except (ValueError, KeyError):
+            logger.warning("SM%d: failed to unpack token at T0[%d], stopping EXEC", self.sm_id, pos)
+            break
+        yield from self.system.send(token)
+        yield self.env.timeout(1)  # per-token injection cycle
+        pos += count
+```
+
+4. `_handle_t0_write()` already stores `token.data` (an int) — no change needed for the write path. The t0_store type annotation changes but the actual stored values were already ints.
+
+5. `_handle_t0_read()` — verify it returns int values (it does: `self.t0_store[t0_idx]`). No change needed.
+
+6. Remove any isinstance(entry, Token) checks in the EXEC path — the new implementation processes raw ints via flit_count/unpack_token instead.
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC4.1: After construction, `sm.t0_store` is `list[int]` type. After T0 WRITE, stored values are ints.
+- pe-frame-redesign.AC4.2: Pre-load t0_store with packed token flits (via `pack_token()`), trigger EXEC, verify reconstituted tokens arrive at target PE with correct field values.
+- pe-frame-redesign.AC4.4: Pre-load t0_store with invalid prefix bits (e.g., `[0xFFFF]`), trigger EXEC, verify it stops gracefully without crash and logs warning.
+- Test multiple consecutive packets in T0 — EXEC should parse each one by flit_count boundary.
+- Test truncated packet (flit_count says 3 but only 2 ints remain) — should stop gracefully.
+
+Test file: `tests/test_sm_t0_raw.py` (new file)
+
+**Verification:**
+Run: `python -m pytest tests/test_sm_t0_raw.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: change SM T0 to raw int storage with flit-based EXEC parsing`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Update SM T0 tests for raw int storage
+
+**Verifies:** pe-frame-redesign.AC4.3
+
+**Files:**
+- Modify: `tests/test_sm_tiers.py` (update T0 tests for int storage instead of Token storage)
+- Modify: `tests/test_exec_bootstrap.py` (update EXEC tests to pre-load packed flits)
+
+**Implementation:**
+
+Existing T0 tests that pre-load `t0_store` with Token objects need updating to pre-load with packed int flits instead.
+
+In `tests/test_sm_tiers.py`:
+- Any test that does `sm.t0_store.append(some_token)` or `t0_store.append(some_token)` must change to `t0_store.extend(pack_token(some_token))`
+- Import `pack_token` from `encoding`
+- T0 READ tests: stored values are now ints, verify int retrieval
+
+In `tests/test_exec_bootstrap.py`:
+- Tests that pre-load T0 with Token objects for EXEC to read must change to `t0_store.extend(pack_token(token))` for each token
+- Verify EXEC reconstitutes the same tokens (round-trip via pack_token -> t0_store -> flit_count -> unpack_token)
+- pe-frame-redesign.AC4.3: pack_token/unpack_token round-trip is implicitly tested through EXEC end-to-end
+
+**Verification:**
+Run: `python -m pytest tests/test_sm_tiers.py tests/test_exec_bootstrap.py tests/test_sm_t0_raw.py -v`
+Expected: `test_sm_t0_raw.py` and the updated T0 tests in `test_sm_tiers.py` and `test_exec_bootstrap.py` pass. Other tests in these files that depend on types removed in Phase 1 (e.g. `IRAMWriteToken`, `DyadToken.gen`, `MatchEntry`) may fail — that is expected and will be addressed in Phase 8.
+
+**Commit:** `refactor: update T0 tests for raw int storage with packed flits`
+
+<!-- END_TASK_2 -->
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_SUBCOMPONENT_B (tasks 3-4) -->
+<!-- START_TASK_3 -->
+### Task 3: Update network routing for PEToken
+
+**Verifies:** pe-frame-redesign.AC1.5
+
+**Files:**
+- Modify: `emu/network.py` (update _target_store routing, update build_topology for new PEConfig fields)
+
+**Implementation:**
+
+1. Update `_target_store()` in System class to route on `PEToken` instead of `CMToken`:
+
+```python
+from tokens import PEToken, SMToken
+
+def _target_store(self, token: Token) -> simpy.Store:
+    if isinstance(token, SMToken):
+        return self.sms[token.target].input_store
+    if isinstance(token, PEToken):
+        return self.pes[token.target].input_store
+    raise TypeError(f"Unknown token type: {type(token).__name__}")
+```
+
+This ensures `CMToken`, `PELocalWriteToken`, and `FrameControlToken` all route to the target PE's input store.
+
+2. Update `build_topology()` PE construction to pass new PEConfig fields. The PE constructor only accepts frame-based parameters — do not pass `ctx_slots`, `offsets`, or `gen_counters`, which no longer exist:
+
+```python
+for cfg in pe_configs:
+    pe = ProcessingElement(
+        env=env,
+        pe_id=cfg.pe_id,
+        iram=cfg.iram,
+        frame_count=cfg.frame_count,
+        frame_slots=cfg.frame_slots,
+        matchable_offsets=cfg.matchable_offsets,
+        fifo_capacity=fifo_capacity,
+        on_event=cfg.on_event,
+    )
+    # Load initial frames if provided
+    if cfg.initial_frames is not None:
+        for frame_id, slot_values in cfg.initial_frames.items():
+            pe.frames[frame_id] = list(slot_values)
+    if cfg.initial_tag_store is not None:
+        pe.tag_store.update(cfg.initial_tag_store)
+        # Mark these frames as allocated (remove from free_frames)
+        for frame_id in cfg.initial_tag_store.values():
+            if frame_id in pe.free_frames:
+                pe.free_frames.remove(frame_id)
+    pes[cfg.pe_id] = pe
+```
+
+3. Update `t0_store` type annotation:
+```python
+t0_store: list[int] = []
+```
+
+4. Update `inject()` method — check `PEToken` instead of `CMToken`:
+```python
+def inject(self, token: Token):
+    if isinstance(token, SMToken):
+        store = self.sms[token.target].input_store
+    elif isinstance(token, PEToken):
+        store = self.pes[token.target].input_store
+    else:
+        raise TypeError(f"Unknown token type: {type(token).__name__}")
+    store.items.append(token)
+```
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC1.5: Inject `PELocalWriteToken(target=0, ...)`, verify it arrives at PE 0's input_store. Inject `FrameControlToken(target=0, ...)`, verify it arrives at PE 0's input_store. Inject `DyadToken(target=0, ...)`, verify it arrives at PE 0's input_store. Inject `SMToken(target=0, ...)`, verify it arrives at SM 0's input_store.
+- `build_topology` constructs PE with frame_count, frame_slots, matchable_offsets from config
+- `build_topology` loads initial_frames and initial_tag_store into PE
+
+Test file: `tests/test_network_routing.py` (new file, or append to test_network_events.py)
+
+**Verification:**
+Run: `python -m pytest tests/test_network_routing.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: update network routing to PEToken and pass frame config to PE`
+
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Update emu/__init__.py exports
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `emu/__init__.py` (add new event types to exports)
+
+**Implementation:**
+
+Add the new event types to the exports:
+
+```python
+from emu.events import (
+    CellWritten,
+    DeferredRead,
+    DeferredSatisfied,
+    Emitted,
+    EventCallback,
+    Executed,
+    FrameAllocated,
+    FrameFreed,
+    FrameSlotWritten,
+    IRAMWritten,
+    Matched,
+    ResultSent,
+    SimEvent,
+    TokenReceived,
+    TokenRejected,
+)
+from emu.network import System, build_topology
+from emu.types import PEConfig, SMConfig
+```
+
+**Verification:**
+Run: `python -c "from emu import FrameAllocated, FrameFreed, FrameSlotWritten, TokenRejected; print('OK')"`
+Expected: Prints "OK"
+
+**Commit:** `feat: export new frame-based event types from emu package`
+
+<!-- END_TASK_4 -->
+<!-- END_SUBCOMPONENT_B -->
+
+<!-- START_TASK_5 -->
+### Task 5: Run phase 2-3 emulator tests
+
+**Verifies:** None (regression check for new work only)
+
+**Files:**
+- None (test-only verification step)
+
+**Implementation:**
+
+Run only the test files that were created or updated in phases 2 and 3:
+
+```
+python -m pytest tests/test_sm_t0_raw.py tests/test_network_routing.py tests/test_pe_frames.py -v
+```
+
+Legacy tests (`test_pe_events.py`, `test_sm_events.py`, `test_sm_tiers.py`, `test_exec_bootstrap.py`, `test_cycle_timing.py`, `test_network_events.py`, etc.) reference removed types — `ALUInst`, `SMInst`, `MatchEntry`, `IRAMWriteToken`, `DyadToken.gen`, and similar — and will fail. That is expected. These tests will be addressed in Phase 8 when the old test suite is updated to match the new architecture.
+
+**Verification:**
+Run: `python -m pytest tests/test_sm_t0_raw.py tests/test_network_routing.py tests/test_pe_frames.py -v`
+Expected: All tests in these three files pass. Failures in any other test file are out of scope for this phase.
+
+**Commit:** None (verification step only)
+
+<!-- END_TASK_5 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_04.md

···
+# PE Frame-Based Redesign — Phase 4: Assembler Foundation — IR and Upstream Passes
+
+**Goal:** Update IR types and upstream assembler passes (lower, expand, place, opcodes) for the frame model.
+
+**Architecture:** Rename context-slot terminology to activation terminology throughout the assembler IR. Add frame-related fields to IRNode and SystemConfig. Update placement to use frame_count instead of ctx_slots and change IRAM cost to 1 for all node types (frames handle matching separately). Add EXTRACT_TAG and FREE_FRAME to opcode maps.
+
+**Tech Stack:** Python 3.12
+
+**Scope:** Phase 4 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase does not directly implement any AC test cases — it is infrastructure for Phases 5-6 which cover AC5 and AC6. However, the changes here enable:
+
+### pe-frame-redesign.AC5: Assembler allocate produces frame layouts
+- **pe-frame-redesign.AC5.3 Success:** Activation IDs assigned sequentially (0-7), at most `frame_count` concurrent per PE
+- **pe-frame-redesign.AC5.8 Edge:** Matchable offset exceedance warns but does not error
+
+---
+
+<!-- START_TASK_1 -->
+### Task 1: Update asm/ir.py for frame model
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/ir.py` (rename ctx fields, add frame fields, update SystemConfig)
+
+**Implementation:**
+
+1. Rename `IRNode.ctx` → `IRNode.act_id`:
+   - Line 88: `ctx: Optional[int] = None` → `act_id: Optional[int] = None`
+
+2. Rename `IRNode.ctx_slot` → `IRNode.act_slot`:
+   - Line 86: `ctx_slot: Optional[Union[int, CtxSlotRef, CtxSlotRange]] = None` → `act_slot: Optional[Union[int, ActSlotRef, ActSlotRange]] = None`
+
+3. Add new fields to IRNode (after `act_id`):
+   ```python
+   mode: Optional[tuple] = None          # (OutputStyle, has_const, dest_count) — set by allocate
+   fref: Optional[int] = None            # frame slot base index — set by allocate
+   wide: bool = False                    # wide operation flag
+   frame_layout: Optional[FrameLayout] = None  # frame slot map — set by allocate
+   ```
+
+4. Rename type aliases directly — no backward-compat aliases:
+   - `CtxSlotRef` → `ActSlotRef`
+   - `CtxSlotRange` → `ActSlotRange`
+
+5. Add new types:
+   ```python
+   @dataclass(frozen=True)
+   class FrameSlotMap:
+       match_slots: tuple[int, ...]      # offsets of match operand slots
+       const_slots: tuple[int, ...]      # offsets of constant slots
+       dest_slots: tuple[int, ...]       # offsets of destination slots
+       sink_slots: tuple[int, ...]       # offsets of sink/SM param slots
+
+   @dataclass(frozen=True)
+   class FrameLayout:
+       slot_map: FrameSlotMap
+       total_slots: int
+   ```
+
+6. Update SystemConfig:
+   - Remove `ctx_slots` field entirely
+   - Add `frame_count: int = 8`
+   - Add `frame_slots: int = 64`
+   - Add `matchable_offsets: int = 8`
+   - Bump `iram_capacity` default from 128 to 256
+   - Remove `DEFAULT_CTX_SLOTS` entirely
+
+   ```python
+   DEFAULT_IRAM_CAPACITY = 256
+   DEFAULT_FRAME_COUNT = 8
+   DEFAULT_FRAME_SLOTS = 64
+   DEFAULT_MATCHABLE_OFFSETS = 8
+
+   @dataclass(frozen=True)
+   class SystemConfig:
+       pe_count: int
+       sm_count: int
+       iram_capacity: int = DEFAULT_IRAM_CAPACITY
+       frame_count: int = DEFAULT_FRAME_COUNT
+       frame_slots: int = DEFAULT_FRAME_SLOTS
+       matchable_offsets: int = DEFAULT_MATCHABLE_OFFSETS
+       loc: SourceLoc = SourceLoc(0, 0)
+   ```
+
+**Testing:**
+
+Tests must verify:
+- `IRNode` has `act_id` field (not `ctx`)
+- `IRNode` has `act_slot` field (not `ctx_slot`)
+- `IRNode` has `mode`, `fref`, `wide`, `frame_layout` fields
+- `SystemConfig` has `frame_count`, `frame_slots`, `matchable_offsets` (not `ctx_slots`)
+- `SystemConfig` defaults are correct
+- `ActSlotRef` and `ActSlotRange` exist
+- `FrameSlotMap` and `FrameLayout` are frozen dataclasses
+
+Test file: `tests/test_ir_frame_types.py` (new file)
+
+**Verification:**
+Run: `python -m pytest tests/test_ir_frame_types.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: update IR types for frame model (act_id, frame_count, FrameLayout)`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Update asm/opcodes.py
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/opcodes.py` (add free_frame and extract_tag mnemonics)
+
+**Implementation:**
+
+Phase 1 renumbered all ALUOp enum values to match 5-bit hardware encoding and renamed/moved shift operations. Update opcodes.py to match:
+
+1. Rename shift mnemonics to match new enum names:
+   ```python
+   "shl": ArithOp.SHL,       # was "shiftl": ArithOp.SHIFT_L
+   "shr": ArithOp.SHR,       # was "shiftr": ArithOp.SHIFT_R
+   "asr": ArithOp.ASR,       # was "ashiftr": ArithOp.ASHFT_R
+   ```
+
+2. Replace `free_ctx` with `free_frame` in the mnemonic map:
+   ```python
+   "free_frame": RoutingOp.FREE_FRAME,
+   ```
+
+3. Add new mnemonics:
+   ```python
+   "extract_tag": RoutingOp.EXTRACT_TAG,
+   "alloc_remote": RoutingOp.ALLOC_REMOTE,
+   ```
+
+4. Add `RoutingOp.EXTRACT_TAG` and `RoutingOp.ALLOC_REMOTE` to the MONADIC_OPS set.
+
+5. Update the `_ALL_MONADIC_VALS` set — shift ops renamed:
+   ```python
+   (ArithOp, int(ArithOp.SHL)),
+   (ArithOp, int(ArithOp.SHR)),
+   (ArithOp, int(ArithOp.ASR)),
+   ```
+
+6. Update `dfasm.lark` grammar:
+   - Rename shift mnemonics: `"shiftl"` → `"shl"`, `"shiftr"` → `"shr"`, `"ashiftr"` → `"asr"`
+   - Replace `"free_ctx"` with `"free_frame"`
+   - Remove `"change_tag"` (CHANGE_TAG is an OutputStyle, not an opcode)
+   - Add new opcodes: `| "extract_tag" | "alloc_remote"`
+
+7. Import updated enum classes (`FREE_FRAME`/`EXTRACT_TAG`/`ALLOC_REMOTE` in `RoutingOp`).
+
+**Verification:**
+Run: `python -m pytest tests/test_opcodes.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: update opcode map for 5-bit encoding, shift renames, and new routing ops`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Update asm/errors.py
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/errors.py` (add FRAME error category)
+
+**Implementation:**
+
+Add `FRAME` to the `ErrorCategory` enum:
+```python
+class ErrorCategory(Enum):
+    PARSE = "parse"
+    NAME = "name"
+    SCOPE = "scope"
+    PLACEMENT = "placement"
+    RESOURCE = "resource"
+    ARITY = "arity"
+    PORT = "port"
+    UNREACHABLE = "unreachable"
+    VALUE = "value"
+    MACRO = "macro"
+    CALL = "call"
+    FRAME = "frame"
+```
+
+**Verification:**
+Run: `python -c "from asm.errors import ErrorCategory; print(ErrorCategory.FRAME)"`
+Expected: `ErrorCategory.FRAME`
+
+**Commit:** `feat: add FRAME error category`
+
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Update asm/lower.py for act_slot rename
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/lower.py` (rename ctx_slot → act_slot in IRNode construction)
+
+**Implementation:**
+
+Mechanical rename throughout `asm/lower.py`:
+
+1. All occurrences of `ctx_slot=` in IRNode constructor calls → `act_slot=`
+2. All references to `qualified_ref_dict.get("ctx_slot")` → `qualified_ref_dict.get("act_slot")`
+3. Variable names: `ctx_slot = ...` → `act_slot = ...`
+4. All `CtxSlotRef` references → `ActSlotRef` and `CtxSlotRange` → `ActSlotRange` in imports
+5. Also update the `@system` pragma parsing: `ctx_slots = config_dict.get("ctx", 4)` changes to `frame_count = config_dict.get("frames", 8)`
+
+Note on Lark transformer methods: if `dfasm.lark` has a `ctx_slot` grammar rule, the transformer method name must match. In that case, keep the method named `ctx_slot` (because Lark requires it) but update the internal variable names and the IRNode field assignment to use `act_slot`. This is not a backward-compat shim — it is a Lark dispatch requirement. If the grammar rule is renamed to `act_slot`, rename the method freely.
+
+**Verification:**
+Run: `python -m pytest tests/test_lower.py tests/test_parser.py -v`
+Expected: Tests that cover renamed fields pass; other tests may fail if they reference removed types.
+
+**Commit:** `refactor: rename ctx_slot to act_slot in lower pass`
+
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Update asm/expand.py for FREE_FRAME and ActSlotRef
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/expand.py` (FREE_CTX → FREE_FRAME, free_ctx_nodes → free_frame_nodes, CtxSlotRef → ActSlotRef)
+- Modify: `asm/ir.py` (rename CallSite.free_ctx_nodes → free_frame_nodes if present)
+
+**Implementation:**
+
+1. In call wiring (lines ~1153-1169): change `RoutingOp.FREE_CTX` → `RoutingOp.FREE_FRAME` in IRNode construction
+2. Rename variable `free_ctx_name` → `free_frame_name` and `free_ctx_nodes` → `free_frame_nodes`
+3. Update `CallSite` field reference: `free_ctx_nodes` → `free_frame_nodes`
+   - If `CallSite` in `asm/ir.py` has a `free_ctx_nodes` field, rename it to `free_frame_nodes` directly — no alias.
+4. All `CtxSlotRef` references → `ActSlotRef` (including imports)
+5. All `ctx_slot` references in node field access → `act_slot`
+
+**Verification:**
+Run: `python -m pytest tests/test_expand.py tests/test_call_wiring.py -v`
+Expected: Tests that cover renamed fields pass; other tests may fail if they reference removed types.
+
+**Commit:** `refactor: rename FREE_CTX to FREE_FRAME and CtxSlotRef to ActSlotRef in expand pass`
+
+<!-- END_TASK_5 -->
+
+<!-- START_TASK_6 -->
+### Task 6: Update asm/place.py for frame_count and IRAM cost
+
+**Verifies:** pe-frame-redesign.AC5.8 (matchable offset warning)
+
+**Files:**
+- Modify: `asm/place.py` (update _count_iram_cost, ctx_slots → frame_count, add matchable offset tracking)
+
+**Implementation:**
+
+1. Change `_count_iram_cost()` to return 1 for all node types:
+   ```python
+   def _count_iram_cost(node: IRNode) -> int:
+       """Count IRAM slots used by a node.
+
+       In the frame model, all instructions use 1 IRAM slot.
+       Matching is handled by frame SRAM, not IRAM entries.
+       """
+       return 1
+   ```
+
+2. Replace `ctx_slots` tracking with `frames_used` tracking:
+   - `ctx_used` dict → `frames_used` dict
+   - `ctx_scopes_per_pe` → `act_scopes_per_pe`
+   - Validation: `frames_used[pe] <= system.frame_count` (instead of `ctx_used[pe] <= system.ctx_slots`)
+
+3. Add matchable offset tracking per activation:
+   - Track how many dyadic IRAM offsets each activation uses
+   - If any activation exceeds `system.matchable_offsets`, emit a warning (not an error):
+     ```python
+     from asm.errors import AssemblyError, ErrorCategory
+     # ...
+     if dyadic_offsets_used > system.matchable_offsets:
+         graph.errors.append(AssemblyError(
+             message=f"Activation on PE {pe} uses {dyadic_offsets_used} matchable offsets "
+                     f"(limit: {system.matchable_offsets})",
+             category=ErrorCategory.FRAME,
+             severity="warning",
+             loc=node.loc,
+         ))
+     ```
+
+4. Replace all `system.ctx_slots` references with `system.frame_count`.
+
+5. Update `ctx_slot` field access on nodes to `act_slot`.
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC5.8: When a PE has more dyadic offsets than `matchable_offsets`, a warning is emitted but placement succeeds
+- `_count_iram_cost()` returns 1 for both dyadic and monadic nodes
+- Placement respects `frame_count` limit (not `ctx_slots`)
+
+Test file: `tests/test_place.py` (update existing tests) and/or `tests/test_ir_frame_types.py`
+
+**Verification:**
+Run: `python -m pytest tests/test_place.py tests/test_autoplacement.py -v`
+Expected: Tests that cover frame_count and IRAM cost pass; other tests may fail.
+
+**Commit:** `feat: update placement for frame_count and uniform IRAM cost`
+
+<!-- END_TASK_6 -->
+
+<!-- START_TASK_7 -->
+### Task 7: Update assembler test files for renames
+
+**Verifies:** None (regression)
+
+**Files:**
+- Modify: various test files in `tests/` that reference ctx, ctx_slot, ctx_slots, free_ctx
+
+**Implementation:**
+
+Mechanical renames across all assembler test files:
+
+1. `node.ctx` → `node.act_id`
+2. `node.ctx_slot` → `node.act_slot`
+3. `system.ctx_slots` → `system.frame_count` (and update default values in test configs)
+4. `CtxSlotRef` → `ActSlotRef`, `CtxSlotRange` → `ActSlotRange`
+5. `free_ctx` references → `free_frame`
+6. `FREE_CTX` → `FREE_FRAME`
+7. Update any test that validates IRAM cost of 2 for dyadic → expect 1
+
+Known affected test files:
+- `tests/test_allocate.py`
+- `tests/test_place.py`
+- `tests/test_autoplacement.py`
+- `tests/test_expand.py`
+- `tests/test_call_wiring.py`
+- `tests/test_codegen.py`
+- `tests/test_lower.py`
+- `tests/test_resolve.py`
+- `tests/test_seed_const.py`
+- `tests/test_sm_graph_nodes.py`
+- `tests/test_macro_ir.py`
+- `tests/test_macro_ret_wiring.py`
+
+**Verification:**
+Run: `python -m pytest tests/test_ir_frame_types.py tests/test_opcodes.py -v`
+Expected: New IR type tests and opcode tests pass. Legacy test files may still fail — that is expected at this phase.
+
+**Commit:** `refactor: update assembler tests for ctx→act_id and frame_count renames`
+
+<!-- END_TASK_7 -->
+
+<!-- START_TASK_8 -->
+### Task 8: Update asm/serialize.py for field renames
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `asm/serialize.py` (rename ctx→act_id, ctx_slot→act_slot references)
+
+**Implementation:**
+
+The serializer reads IRNode fields and produces dfasm source text. Update it for:
+
+1. Any reference to `node.ctx` → `node.act_id`
+2. Any reference to `node.ctx_slot` → `node.act_slot`
+3. Any reference to `CtxSlotRef` → `ActSlotRef`, `CtxSlotRange` → `ActSlotRange`
+4. Handle new fields (`mode`, `fref`, `frame_layout`) — these are allocate-pass outputs and may not need serialization (the serializer operates on pre-allocate IR), but verify
+
+Also note: `asm/CLAUDE.md` and root `CLAUDE.md` reference removed types extensively (`ALUInst`, `SMInst`, `Addr`, `IRAMWriteToken`, `MatchEntry`, `ctx_slots`, `gen_counters`, `ctx_mode`, `ctx_override`). These documentation files will be updated in Phase 8 as part of final cleanup.
+
+**Verification:**
+Run: `python -c "from asm.serialize import serialize_graph; print('OK')"`
+Expected: Prints "OK" (module loads without import errors)
+
+**Commit:** `refactor: update serialize.py for ctx→act_id renames`
+
+<!-- END_TASK_8 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_05.md

···
+# PE Frame-Based Redesign — Phase 5: Assembler Core — Allocate Rewrite
+
+**Goal:** Rewrite the allocate pass for frame layout allocation, IRAM offset assignment with instruction deduplication, activation ID assignment, and mode computation.
+
+**Architecture:** The allocate pass gains four new sub-functions: `_assign_iram_offsets()` (rewritten for deduplication), `_assign_act_ids()` (replaces `_assign_context_slots()`), `_compute_frame_layouts()` (new), and `_compute_modes()` (new). Destination resolution produces `FrameDest` objects instead of `Addr`. Frame layouts are canonical per function body — all activations of the same function share the layout, enabling instruction deduplication at the IRAM level.
+
+**Tech Stack:** Python 3.12
+
+**Scope:** Phase 5 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC5: Assembler allocate produces frame layouts
+- **pe-frame-redesign.AC5.1 Success:** IRAM offsets deduplicated — identical Instruction templates on same PE share entries
+- **pe-frame-redesign.AC5.2 Success:** Frame layouts canonical per function body — all activations of same function share layout
+- **pe-frame-redesign.AC5.3 Success:** Activation IDs assigned sequentially (0-7), at most `frame_count` concurrent per PE
+- **pe-frame-redesign.AC5.4 Success:** Frame slot assignment: match operands at 0 to matchable_offsets-1, then constants (deduped), then destinations (deduped), then sinks/SM params
+- **pe-frame-redesign.AC5.5 Success:** Mode (OutputStyle + has_const + dest_count) computed from edge topology and opcode
+- **pe-frame-redesign.AC5.6 Failure:** Frame slot overflow (> frame_slots) reports error
+- **pe-frame-redesign.AC5.7 Failure:** Act_id exhaustion (>8 needed) reports error
+
+---
+
+<!-- START_SUBCOMPONENT_A (tasks 1-3) -->
+<!-- START_TASK_1 -->
+### Task 1: Rewrite _assign_iram_offsets with deduplication
+
+**Verifies:** pe-frame-redesign.AC5.1
+
+**Files:**
+- Modify: `asm/allocate.py` (rewrite `_assign_iram_offsets()`)
+
+**Implementation:**
+
+The current `_assign_iram_offsets()` assigns sequential offsets with dyadic first, monadic after. The new version adds instruction template deduplication.
+
+Two instructions on the same PE share an IRAM entry when they produce identical `Instruction` objects — same opcode, output style, has_const, dest_count, wide, and fref. Since `fref` and mode aren't computed until `_compute_frame_layouts()` and `_compute_modes()`, deduplication at IRAM assignment time is based on the subset of fields available: opcode and arity (dyadic vs monadic).
+
+Actually, per the design, deduplication happens at the **template** level — after all fields are computed. This means IRAM offset assignment should be a two-phase process:
+
+**Phase A: Assign provisional offsets** (same algorithm as current — dyadic at low offsets, monadic above).
+
+**Phase B: Deduplicate** (after frame layouts and modes are computed — called later in the allocate pipeline, or combined into a single function that does both).
+
+For this task, restructure `_assign_iram_offsets()` to:
+1. Still partition dyadic/monadic and assign sequential offsets
+2. Return the offset assignments AND enough metadata for later deduplication
+3. All instructions return IRAM cost of 1 (per Phase 4 change)
+
+The deduplication step proper happens after `_compute_modes()` and `_compute_frame_layouts()` produce the `fref` and mode fields. Add `_deduplicate_iram()` as a post-processing step:
+
+```python
+def _deduplicate_iram(
+    nodes_on_pe: dict[str, IRNode],
+    pe_id: int,
+) -> dict[str, IRNode]:
+    """Deduplicate IRAM entries for nodes that produce identical Instruction templates.
+
+    Two nodes share an IRAM offset when they have identical:
+    opcode, output (OutputStyle), has_const, dest_count, wide, fref.
+    """
+    template_to_offset: dict[tuple, int] = {}
+    updated = {}
+
+    for name, node in nodes_on_pe.items():
+        if node.seed or node.iram_offset is None:
+            updated[name] = node
+            continue
+
+        # Build template key from the fields that make an Instruction
+        mode = node.mode  # (OutputStyle, has_const, dest_count)
+        if mode is None:
+            updated[name] = node
+            continue
+
+        template_key = (
+            node.opcode,
+            mode[0],       # OutputStyle
+            mode[1],       # has_const
+            mode[2],       # dest_count
+            node.wide,
+            node.fref,
+        )
+
+        if template_key in template_to_offset:
+            # Reuse existing offset
+            updated[name] = replace(node, iram_offset=template_to_offset[template_key])
+        else:
+            template_to_offset[template_key] = node.iram_offset
+            updated[name] = node
+
+    return updated
+```
+
+This is called near the end of allocate(), after modes and frame layouts are assigned.
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC5.1: Two nodes on the same PE with identical opcode, mode, and fref share the same IRAM offset after deduplication
+- Nodes with different opcodes get different offsets
+- Nodes with same opcode but different modes get different offsets
+- Seed nodes are excluded from IRAM assignment
+
+Test file: `tests/test_allocate_frames.py` (new file)
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: rewrite IRAM offset assignment with template deduplication`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Add _assign_act_ids
+
+**Verifies:** pe-frame-redesign.AC5.3, pe-frame-redesign.AC5.7
+
+**Files:**
+- Modify: `asm/allocate.py` (add `_assign_act_ids()`, remove `_assign_context_slots()`)
+
+**Implementation:**
+
+Add `_assign_act_ids()` and remove `_assign_context_slots()`. The logic is similar but:
+- Uses 3-bit act_ids (0-7) instead of ctx_slots
+- Limit is `system.frame_count` (default 8)
+- Field set on IRNode is `act_id`
+- Uses the same scope extraction logic (`_extract_function_scope()`)
+- CallSite field reference: `free_frame_nodes`
+
+```python
+def _assign_act_ids(
+    nodes_on_pe: list[IRNode],
+    all_nodes: dict[str, IRNode],
+    frame_count: int,
+    pe_id: int,
+    call_sites: list[CallSite] | None = None,
+) -> tuple[dict[str, IRNode], list[AssemblyError]]:
+    """Assign activation IDs (0 to frame_count-1) per function scope per PE."""
+```
+
+The algorithm is identical to the removed `_assign_context_slots()` except:
+- Replace `frame_count` in validation checks (was `ctx_slots`)
+- Replace `node.act_id` in field assignments (was `node.ctx`)
+- Replace `free_frame_nodes` in CallSite field access (was `free_ctx_nodes`)
+- Error message: "activation ID exhaustion"
+- Error category: `ErrorCategory.FRAME`
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC5.3: Act_ids assigned 0, 1, 2, ... sequentially per function scope
+- pe-frame-redesign.AC5.7: When >frame_count scopes needed, error with `ErrorCategory.FRAME`
+- Single function scope gets act_id 0
+- Multiple functions on same PE get different act_ids
+- Same function across different PEs can reuse act_id 0
+
+Test file: `tests/test_allocate_frames.py` (append)
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: add _assign_act_ids, remove _assign_context_slots`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Add _compute_frame_layouts and _compute_modes
+
+**Verifies:** pe-frame-redesign.AC5.2, pe-frame-redesign.AC5.4, pe-frame-redesign.AC5.5, pe-frame-redesign.AC5.6
+
+**Files:**
+- Modify: `asm/allocate.py` (add two new functions)
+
+**Implementation:**
+
+**`_compute_modes()`** — derives OutputStyle, has_const, dest_count from edge topology and opcode:
+
+```python
+def _compute_modes(
+    nodes_on_pe: dict[str, IRNode],
+    edges_by_source: dict[str, list[IREdge]],
+) -> dict[str, IRNode]:
+    """Compute (OutputStyle, has_const, dest_count) for each node from edge topology."""
+    updated = {}
+    for name, node in nodes_on_pe.items():
+        if node.seed:
+            updated[name] = node
+            continue
+
+        out_edges = edges_by_source.get(name, [])
+        dest_count = len(out_edges)
+        has_const = node.const is not None
+
+        # Determine OutputStyle from opcode and edge topology
+        if isinstance(node.opcode, MemOp):
+            # SM instructions: mode depends on MemOp semantics
+            # WRITE, CLEAR, FREE, SET_PAGE, WRITE_IMM → no return value → SINK
+            # READ, RD_INC, RD_DEC, CMP_SW, RAW_READ, EXT → return value → INHERIT
+            _sink_ops = {MemOp.WRITE, MemOp.CLEAR, MemOp.FREE, MemOp.SET_PAGE, MemOp.WRITE_IMM}
+            if node.opcode in _sink_ops:
+                output = OutputStyle.SINK
+                dest_count = 0
+            else:
+                output = OutputStyle.INHERIT
+        elif node.opcode == RoutingOp.FREE_FRAME:
+            output = OutputStyle.SINK
+            dest_count = 0
+        elif node.opcode == RoutingOp.EXTRACT_TAG:
+            output = OutputStyle.INHERIT
+        else:
+            # Check if any outgoing edge has ctx_override=True
+            # ctx_override=True on an edge means the source node is a
+            # cross-function return — its left operand carries a packed
+            # flit 1 (from EXTRACT_TAG) that determines the destination.
+            # In the frame model, this maps to OutputStyle.CHANGE_TAG.
+            has_ctx_override = any(e.ctx_override for e in out_edges)
+            output = OutputStyle.CHANGE_TAG if has_ctx_override else OutputStyle.INHERIT
+
+        mode = (output, has_const, dest_count)
+        updated[name] = replace(node, mode=mode)
+
+    return updated
+```
+
+Note on `ctx_override` → `CHANGE_TAG` mapping: In the current codebase, `expand.py` sets `ctx_override=True` on edges that cross function boundaries (return paths from callee to caller). The old model packed the target context into the instruction's const field via `ctx_mode`. The new model uses `OutputStyle.CHANGE_TAG` instead — the PE reads a packed flit 1 from the left operand (produced by the caller's EXTRACT_TAG instruction) and uses it as the destination. The `IREdge.ctx_override` field should be renamed to `change_tag` in a later cleanup, but functionally it serves the same purpose: marking edges that need dynamic destination routing.
+
+**`_compute_frame_layouts()`** — per-activation frame slot assignment:
+
+```python
+def _compute_frame_layouts(
+    nodes_on_pe: dict[str, IRNode],
+    edges_by_source: dict[str, list[IREdge]],
+    edges_by_dest: dict[str, list[IREdge]],
+    all_nodes: dict[str, IRNode],
+    frame_slots: int,
+    pe_id: int,
+) -> tuple[dict[str, IRNode], list[AssemblyError]]:
+    """Compute frame slot layouts per activation.
+
+    Slot assignment order:
+    0 to matchable_offsets-1: match operands (one pair per dyadic instruction)
+    then: constants (deduplicated by value)
+    then: destinations (deduplicated by FrameDest identity)
+    then: sinks and SM parameters
+
+    All activations of the same function share the canonical layout.
+    """
+```
+
+Frame layout algorithm — match operands and const/dest are in **separate regions** of the frame:
+
+**Match region** (slots 0 to `matchable_offsets - 1`):
+- Dyadic instructions are placed at low IRAM offsets (0 to `matchable_offsets - 1`) by the assembler's IRAM offset assignment (Phase 4 / Task 1).
+- Match operands are stored at `frames[frame_id][token.offset]`, where `token.offset` = IRAM offset.
+- The match region is indexed by IRAM offset, NOT by `fref`.
+- Multiple dyadic instructions can share a match slot if the compiler proves their operands are never pending simultaneously (liveness-based allocation).
+- If the activation has more dyadic instructions than `matchable_offsets`, emit a warning (per AC5.8).
+
+**Const/dest region** (slots `matchable_offsets` and above):
+- Each instruction gets a contiguous `fref` group in this region, laid out per the mode table:
+  - Mode 0: `[dest]` — 1 slot
+  - Mode 1: `[const, dest]` — 2 slots
+  - Mode 2: `[dest1, dest2]` — 2 slots
+  - Mode 3: `[const, dest1, dest2]` — 3 slots
+  - Mode 4: no frame slots
+  - Mode 5: `[const]` — 1 slot
+  - Mode 6: `[sink_target]` — 1 slot (write-back)
+  - Mode 7: `[RMW_target]` — 1 slot (read-modify-write)
+- Constants are deduplicated by value — instructions sharing the same constant value can point to the same slot.
+- Destinations are deduplicated by FrameDest identity — instructions with the same target can share dest slots.
+
+Algorithm:
+1. Group nodes by act_id (same act_id = same activation)
+2. For each activation group:
+   a. Count dyadic instructions → these occupy match slots 0 to N-1 (their IRAM offsets). Warn if N > `matchable_offsets`.
+   b. Collect all constants → deduplicate by value → assign const/dest slots starting at `matchable_offsets`.
+   c. Collect all destinations (from edges) → deduplicate by FrameDest identity → assign dest slots after constants.
+   d. Collect sinks and SM params → assign remaining slots.
+   e. Set `fref` on each node to point to the base of its const/dest group.
+3. Build `FrameLayout` with `FrameSlotMap`
+4. If total slots exceed `frame_slots`: report error with `ErrorCategory.FRAME`
+
+Each node gets:
+- `fref` = base of its const/dest group in the frame (NOT the match slot)
+- `frame_layout` = the shared `FrameLayout` for its activation
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC5.2: Two activations of the same function (same set of instructions) produce identical FrameLayout objects
+- pe-frame-redesign.AC5.4: Match operands at slots 0 to matchable_offsets-1 (indexed by IRAM offset), const/dest groups at matchable_offsets and above (indexed by fref)
+- pe-frame-redesign.AC5.5: OutputStyle derived from edge count (0 edges → SINK, 1-2 edges → INHERIT), has_const from const field, dest_count from edge count
+- pe-frame-redesign.AC5.6: When total frame slots > frame_slots limit, error with `ErrorCategory.FRAME`
+- Constants with same value share a slot
+- Destinations with same FrameDest share a slot
+
+Test file: `tests/test_allocate_frames.py` (append)
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: add frame layout computation and mode derivation to allocate`
+
+<!-- END_TASK_3 -->
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_TASK_4 -->
+### Task 4: Rework _resolve_destinations for FrameDest
+
+**Verifies:** None directly (infrastructure for Phase 6 codegen)
+
+**Files:**
+- Modify: `asm/allocate.py` (update `_resolve_destinations()` to produce FrameDest)
+
+**Implementation:**
+
+The current `_resolve_destinations()` produces `Addr` objects. The new version produces `FrameDest` objects that include `target_pe`, `offset`, `act_id`, `port`, and `token_kind`.
+
+Token kind determination:
+- If destination node is dyadic: `TokenKind.DYADIC`
+- If destination node is monadic and inline: `TokenKind.INLINE`
+- Otherwise: `TokenKind.MONADIC`
+
+For now, determine token kind from the destination node's opcode and edge properties:
+- If the destination node's IRAM instruction expects a DyadToken (dyadic opcode): `TokenKind.DYADIC`
+- Otherwise: `TokenKind.MONADIC`
+
+Updated resolution for each edge:
+```python
+dest_node = all_nodes[edge.dest]
+frame_dest = FrameDest(
+    target_pe=dest_node.pe,
+    offset=dest_node.iram_offset,
+    act_id=dest_node.act_id,
+    port=edge.port,
+    token_kind=_determine_token_kind(dest_node),
+)
+resolved = ResolvedDest(name=edge.dest, addr=None, frame_dest=frame_dest)
+```
+
+Note: `ResolvedDest` may need a `frame_dest` field added, or replaced entirely. Check `asm/ir.py` for the ResolvedDest definition and add `frame_dest: Optional[FrameDest] = None`.
+
+Also assign FrameDest objects to frame slots during this step — each destination gets stored in the activation's frame layout at the appropriate dest slot offset.
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: resolve destinations as FrameDest objects with token kind`
+
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Wire new functions into allocate() main flow
+
+**Verifies:** All AC5 criteria (integration)
+
+**Files:**
+- Modify: `asm/allocate.py` (update `allocate()` to call new functions in order)
+
+**Implementation:**
+
+Update the `allocate()` main function to use the new sub-functions:
+
+```python
+def allocate(graph: IRGraph) -> IRGraph:
+    errors = list(graph.errors)
+    system = graph.system
+
+    if system is None:
+        # ... existing error handling ...
+
+    all_nodes, all_edges = collect_all_nodes_and_edges(graph)
+    edges_by_source = _build_edge_index(all_edges)
+    edges_by_dest = _build_edge_index_by_dest(all_edges)
+
+    # Validate non-commutative ops (unchanged)
+    errors.extend(_validate_noncommutative_const(all_nodes, edges_by_dest))
+
+    # Assign SM IDs (unchanged)
+    sm_updated, sm_errors = _assign_sm_ids(all_nodes, system.sm_count)
+    errors.extend(sm_errors)
+    all_nodes.update(sm_updated)
+
+    # Group nodes by PE
+    nodes_by_pe = _group_nodes_by_pe(all_nodes)
+
+    intermediate_nodes = {}
+    for pe_id, nodes_on_pe in sorted(nodes_by_pe.items()):
+        # 1. Assign IRAM offsets (provisional)
+        iram_updated, iram_errors = _assign_iram_offsets(
+            nodes_on_pe, all_nodes, system.iram_capacity, pe_id
+        )
+        errors.extend(iram_errors)
+        if iram_errors: continue
+
+        # 2. Assign activation IDs
+        act_updated, act_errors = _assign_act_ids(
+            list(iram_updated.values()), all_nodes,
+            system.frame_count, pe_id,
+            call_sites=graph.call_sites,
+        )
+        errors.extend(act_errors)
+        if act_errors: continue
+
+        # 3. Compute modes (OutputStyle, has_const, dest_count)
+        mode_updated = _compute_modes(act_updated, edges_by_source)
+
+        # 4. Compute frame layouts (assigns fref, frame_layout)
+        frame_updated, frame_errors = _compute_frame_layouts(
+            mode_updated, edges_by_source, edges_by_dest,
+            all_nodes, system.frame_slots, pe_id,
+        )
+        errors.extend(frame_errors)
+        if frame_errors: continue
+
+        # 5. Deduplicate IRAM entries
+        deduped = _deduplicate_iram(frame_updated, pe_id)
+
+        intermediate_nodes.update(deduped)
+
+    # Resolve destinations (produces FrameDest)
+    for pe_id in sorted(nodes_by_pe.keys()):
+        nodes_on_this_pe = {
+            name: node for name, node in intermediate_nodes.items()
+            if node.pe == pe_id
+        }
+        if not nodes_on_this_pe: continue
+
+        resolved, resolve_errors = _resolve_destinations(
+            nodes_on_this_pe, intermediate_nodes, edges_by_source
+        )
+        errors.extend(resolve_errors)
+        intermediate_nodes.update(resolved)
+
+    # Reconstruct graph
+    result_graph = update_graph_nodes(graph, intermediate_nodes)
+    return replace(result_graph, errors=errors)
+```
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass. `tests/test_allocate.py` may fail — that is expected and addressed in Task 6.
+
+**Commit:** `feat: wire frame-based allocation into allocate() main flow`
+
+<!-- END_TASK_5 -->
+
+<!-- START_TASK_6 -->
+### Task 6: Update existing allocate tests
+
+**Verifies:** None (regression)
+
+**Files:**
+- Modify: `tests/test_allocate.py` (update for act_id, frame_count, new fields)
+
+**Implementation:**
+
+Update existing allocate tests:
+1. `ctx` field access → `act_id`
+2. `ctx_slots` in SystemConfig → `frame_count`
+3. Tests that check context overflow → check act_id exhaustion
+4. Tests that check IRAM cost of 2 for dyadic → expect 1
+5. Add assertions for new fields: `mode`, `fref`, `frame_layout`
+6. Update `_assign_context_slots` test calls → `_assign_act_ids`
+
+**Verification:**
+Run: `python -m pytest tests/test_allocate_frames.py -v`
+Expected: All tests pass. `tests/test_allocate.py` tests that have been updated should also pass; stale tests in that file may still fail until fully converted.
+
+**Commit:** `refactor: update allocate tests for frame-based allocation`
+
+<!-- END_TASK_6 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_06.md

···
+# PE Frame-Based Redesign — Phase 6: Assembler Core — Codegen Rewrite
+
+**Goal:** Rewrite codegen to produce `Instruction` objects, frame setup token sequences, and updated `AssemblyResult`.
+
+**Architecture:** `_build_iram_for_pe()` produces `dict[int, Instruction]` from allocated IR. `generate_tokens()` produces an ordered token stream: SM init → IRAM writes (via `PELocalWriteToken`) → ALLOC (via `FrameControlToken`) → frame slot writes (via `PELocalWriteToken`) → seed tokens. `AssemblyResult` gains a `setup_tokens` field. The output style mechanism uses `OutputStyle` values derived from the allocate pass — no `ctx_mode` or `ctx_override` fields exist in the new model.
+
+**Tech Stack:** Python 3.12
+
+**Scope:** Phase 6 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC6: Assembler codegen produces frame setup tokens
+- **pe-frame-redesign.AC6.1 Success:** `AssemblyResult` includes `setup_tokens` field
+- **pe-frame-redesign.AC6.2 Success:** Token stream ordering: SM init → IRAM writes → ALLOC → frame slot writes → seed tokens
+- **pe-frame-redesign.AC6.3 Success:** IRAM write data uses `pack_instruction()`
+- **pe-frame-redesign.AC6.4 Success:** Destination frame slot writes use `pack_flit1()` with `is_dest=True`
+- **pe-frame-redesign.AC6.5 Success:** T0 bootstrap data uses `pack_token()` for packed flits
+- **pe-frame-redesign.AC6.6 Success:** Seed tokens use `act_id`, no `gen` field
+
+---
+
+<!-- START_SUBCOMPONENT_A (tasks 1-3) -->
+<!-- START_TASK_1 -->
+### Task 1: Rewrite _build_iram_for_pe for Instruction objects
+
+**Verifies:** pe-frame-redesign.AC6.3 (partial — produces Instruction objects that will be packed)
+
+**Files:**
+- Modify: `asm/codegen.py` (rewrite `_build_iram_for_pe()`)
+
+**Implementation:**
+
+Replace the existing implementation with `Instruction` construction:
+
+```python
+from cm_inst import FrameDest, Instruction, OutputStyle, TokenKind
+
+def _build_iram_for_pe(
+    nodes_on_pe: list[IRNode],
+    all_nodes: dict[str, IRNode],
+    all_edges: list[IREdge],
+) -> dict[int, Instruction]:
+    """Build IRAM entries as Instruction objects for a single PE."""
+    iram: dict[int, Instruction] = {}
+
+    for node in nodes_on_pe:
+        if node.seed or node.iram_offset is None:
+            continue
+        if node.mode is None:
+            continue
+
+        output_style, has_const, dest_count = node.mode
+
+        inst = Instruction(
+            opcode=node.opcode,
+            output=output_style,
+            has_const=has_const,
+            dest_count=dest_count,
+            wide=node.wide,
+            fref=node.fref or 0,
+        )
+
+        iram[node.iram_offset] = inst
+
+    return iram
+```
+
+This is dramatically simpler than the old version because:
+- Unified `Instruction` type — no split by instruction kind
+- Output style comes from `OutputStyle` enum — no encoding tricks
+- No `Addr` construction — replaced by FrameDest in frame slots
+- Mode fields (`output`, `has_const`, `dest_count`) already computed by allocate pass
+
+**Testing:**
+
+Tests must verify:
+- Given IRNodes with mode and fref set, produces correct Instruction objects
+- Seed nodes excluded from IRAM
+- CM vs SM type derived from isinstance(opcode, MemOp) — no stored type field
+
+Test file: `tests/test_codegen_frames.py` (new file)
+
+**Verification:**
+Run: `python -m pytest tests/test_codegen_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: rewrite _build_iram_for_pe for Instruction objects`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Add frame setup token generation
+
+**Verifies:** pe-frame-redesign.AC6.1, pe-frame-redesign.AC6.2, pe-frame-redesign.AC6.3, pe-frame-redesign.AC6.4, pe-frame-redesign.AC6.5
+
+**Files:**
+- Modify: `asm/codegen.py` (add `_generate_setup_tokens()`, update AssemblyResult)
+
+**Implementation:**
+
+1. Update `AssemblyResult` to include `setup_tokens`:
+```python
+@dataclass(frozen=True)
+class AssemblyResult:
+    pe_configs: list[PEConfig]
+    sm_configs: list[SMConfig]
+    seed_tokens: list[CMToken]
+    setup_tokens: list[Token]  # NEW — ordered setup token sequence
+```
+
+2. Add `_generate_setup_tokens()`:
+
+```python
+from encoding import pack_flit1, pack_instruction, pack_token
+from tokens import FrameControlToken, PELocalWriteToken
+
+def _generate_setup_tokens(
+    pe_configs: list[PEConfig],
+    sm_configs: list[SMConfig],
+    nodes_by_pe: dict[int, list[IRNode]],
+    all_nodes: dict[str, IRNode],
+    all_edges: list[IREdge],
+    data_defs: list[IRDataDef],
+) -> list[Token]:
+    """Generate the ordered setup token sequence for frame-based bootstrap.
+
+    Order: SM init → IRAM writes → ALLOC → frame slot writes → (seed tokens added separately)
+    """
+    tokens: list[Token] = []
+
+    # 1. SM init (WRITE ops to populate I-structure cells)
+    for data_def in sorted(data_defs, key=lambda d: (d.sm_id, d.cell_addr)):
+        tokens.append(SMToken(
+            target=data_def.sm_id,
+            addr=data_def.cell_addr,
+            op=MemOp.WRITE,
+            flags=None,
+            data=data_def.value,
+            ret=None,
+        ))
+
+    # 2. IRAM writes via PELocalWriteToken(region=0)
+    for pe_cfg in pe_configs:
+        for offset, inst in sorted(pe_cfg.iram.items()):
+            tokens.append(PELocalWriteToken(
+                target=pe_cfg.pe_id,
+                act_id=0,  # IRAM writes are activation-independent
+                region=0,
+                slot=offset,
+                data=pack_instruction(inst),
+                is_dest=False,
+            ))
+
+    # 3. ALLOC — one per activation per PE
+    for pe_id, nodes in sorted(nodes_by_pe.items()):
+        # Collect unique act_ids on this PE
+        act_ids = sorted({n.act_id for n in nodes if n.act_id is not None and not n.seed})
+        for act_id in act_ids:
+            tokens.append(FrameControlToken(
+                target=pe_id,
+                act_id=act_id,
+                op=FrameOp.ALLOC,
+                payload=0,
+            ))
+
+    # 4. Frame slot writes via PELocalWriteToken(region=1)
+    for pe_id, nodes in sorted(nodes_by_pe.items()):
+        act_ids = sorted({n.act_id for n in nodes if n.act_id is not None and not n.seed})
+        for act_id in act_ids:
+            act_nodes = [n for n in nodes if n.act_id == act_id and not n.seed]
+            if not act_nodes:
+                continue
+            # Get frame layout from first node (canonical per activation)
+            layout = act_nodes[0].frame_layout
+            if layout is None:
+                continue
+
+            # Write constants to frame slots
+            for slot_idx in layout.slot_map.const_slots:
+                # Find the const value for this slot
+                const_val = _find_const_for_slot(act_nodes, slot_idx, layout)
+                if const_val is not None:
+                    tokens.append(PELocalWriteToken(
+                        target=pe_id,
+                        act_id=act_id,
+                        region=1,
+                        slot=slot_idx,
+                        data=const_val & 0xFFFF,
+                        is_dest=False,
+                    ))
+
+            # Write destinations to frame slots
+            for slot_idx in layout.slot_map.dest_slots:
+                dest = _find_dest_for_slot(act_nodes, slot_idx, layout, all_nodes, all_edges)
+                if dest is not None:
+                    tokens.append(PELocalWriteToken(
+                        target=pe_id,
+                        act_id=act_id,
+                        region=1,
+                        slot=slot_idx,
+                        data=pack_flit1(dest),
+                        is_dest=True,  # AC6.4: signals PE to decode as FrameDest
+                    ))
+
+    return tokens
+```
+
+Helper functions `_find_const_for_slot()` and `_find_dest_for_slot()` need to map frame slot indices back to the source node/edge that populates them. The exact implementation depends on how `_compute_frame_layouts()` (Phase 5) stores the mapping.
+
+3. For T0 bootstrap data (AC6.5): when writing tokens to T0 storage, use `pack_token()`:
+```python
+# In generate_tokens() for T0 bootstrap:
+for token in bootstrap_tokens:
+    packed_flits = pack_token(token)
+    for i, flit in enumerate(packed_flits):
+        tokens.append(SMToken(
+            target=sm_id,
+            addr=tier_boundary + t0_offset + i,
+            op=MemOp.WRITE,
+            flags=None,
+            data=flit,
+            ret=None,
+        ))
+```
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC6.1: `AssemblyResult` has `setup_tokens` field
+- pe-frame-redesign.AC6.2: Token ordering is SM init → PELocalWriteToken(region=0) → FrameControlToken(ALLOC) → PELocalWriteToken(region=1) → (seeds last)
+- pe-frame-redesign.AC6.3: IRAM write PELocalWriteTokens carry `pack_instruction()` data
+- pe-frame-redesign.AC6.4: Destination slot PELocalWriteTokens have `is_dest=True` and carry `pack_flit1()` data
+- pe-frame-redesign.AC6.5: T0 data stored as packed flits via `pack_token()`
+
+Test file: `tests/test_codegen_frames.py` (append)
+
+**Verification:**
+Run: `python -m pytest tests/test_codegen_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: add frame setup token generation and updated AssemblyResult`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Update seed token generation and generate_direct
+
+**Verifies:** pe-frame-redesign.AC6.6
+
+**Files:**
+- Modify: `asm/codegen.py` (update seed tokens for act_id, update generate_direct and generate_tokens)
+
+**Implementation:**
+
+1. Update seed token construction to use `act_id` and drop `gen`:
+
+For DyadToken seeds:
+```python
+DyadToken(
+    target=dest_node.pe,
+    offset=dest_node.iram_offset,
+    act_id=dest_node.act_id,
+    data=node.const,
+    port=edge.port,
+    wide=False,
+)
+```
+
+For MonadToken seeds:
+```python
+MonadToken(
+    target=dest_node.pe,
+    offset=dest_node.iram_offset,
+    act_id=dest_node.act_id,
+    data=node.const,
+    inline=False,
+)
+```
+
+2. Update `generate_direct()`:
+   - Use new `_build_iram_for_pe()` (produces `dict[int, Instruction]`)
+   - Build PEConfig with new fields:
+     ```python
+     PEConfig(
+         pe_id=pe_id,
+         iram=iram,  # dict[int, Instruction]
+         frame_count=system.frame_count,
+         frame_slots=system.frame_slots,
+         matchable_offsets=system.matchable_offsets,
+         initial_frames=initial_frames_for_pe,  # from frame layout data
+         initial_tag_store=tag_store_for_pe,     # from act_id assignments
+         allowed_pe_routes=pe_routes,
+         allowed_sm_routes=sm_routes,
+     )
+     ```
+   - Compute `initial_frames` from frame layout data: for each act_id on PE, build frame slot value list from constants and FrameDest values
+   - Compute `initial_tag_store` from act_id → frame_id mapping (sequential: act_id 0 → frame 0, etc.)
+
+3. Update `generate_tokens()`:
+   - Use `PELocalWriteToken(region=0)` for IRAM writes
+   - Add `FrameControlToken` ALLOC sequence
+   - Add `PELocalWriteToken(region=1)` frame slot writes
+   - Ordering: SM init → IRAM writes → ALLOC → frame slot writes → seed tokens
+   - Call `_generate_setup_tokens()` and append seed_tokens
+
+**Testing:**
+
+Tests must verify:
+- pe-frame-redesign.AC6.6: Seed tokens use `act_id` field (not `ctx`), and DyadToken has no `gen` field
+- `generate_direct()` produces PEConfigs with `Instruction` IRAM and frame data
+- `generate_tokens()` ordering: SM init → IRAM → ALLOC → frame slots → seeds
+
+Test file: `tests/test_codegen_frames.py` (append)
+
+**Verification:**
+Run: `python -m pytest tests/test_codegen_frames.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: update seed tokens for act_id and wire generate_direct/generate_tokens`
+
+<!-- END_TASK_3 -->
+<!-- END_SUBCOMPONENT_A -->
+
+<!-- START_TASK_4 -->
+### Task 4: Update asm/__init__.py and existing codegen tests
+
+**Verifies:** None (regression + infrastructure)
+
+**Files:**
+- Modify: `asm/__init__.py` (update exports if needed)
+- Modify: `tests/test_codegen.py` (update for new types and field names)
+
+**Implementation:**
+
+1. `asm/__init__.py`: Ensure `AssemblyResult` with `setup_tokens` is properly exported. The `__all__` list already includes `"AssemblyResult"`.
+
+2. Update `tests/test_codegen.py`:
+   - Replace `ctx=` with `act_id=` in all token assertions
+   - Remove `gen=` from DyadToken assertions
+   - Update `PEConfig` assertions: check for `frame_count`, `frame_slots`, `matchable_offsets`
+   - Update IRAM type assertions: `Instruction` instead of `ALUInst`/`SMInst`
+   - Add assertions for `setup_tokens` field on AssemblyResult
+   - Update `generate_tokens()` assertions for new token types (PELocalWriteToken, FrameControlToken)
+
+**Verification:**
+Run: `python -m pytest tests/test_codegen_frames.py -v`
+Expected: All new frame codegen tests pass. `tests/test_codegen.py` tests that have been updated should pass; stale tests may still fail until fully converted.
+
+**Commit:** `refactor: update codegen tests for frame-based output`
+
+<!-- END_TASK_4 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_07.md

···
+# PE Frame-Based Redesign — Phase 7: Downstream Consumers — Monitor and Dfgraph
+
+**Goal:** Update monitor and dfgraph packages to consume new frame-based types, display frame state instead of matching store, and serialize new event types.
+
+**Architecture:** `PESnapshot` gains `frames`, `tag_store`, `presence`, `port_store`, `free_frames` fields. `SMSnapshot.t0_store` becomes `tuple[int, ...]`. Event serialization adds new frame events. Dfgraph updates opcode categories for FREE_FRAME and EXTRACT_TAG. All `ctx` references become `act_id`.
+
+**Tech Stack:** Python 3.12, FastAPI (monitor server), Cytoscape.js (frontend)
+
+**Scope:** Phase 7 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC7: End-to-end pipeline (partial)
+- **pe-frame-redesign.AC7.2 Success:** Monitor loads programs, displays frame state, serialises new events
+
+---
+
+<!-- START_TASK_1 -->
+### Task 1: Update monitor/snapshot.py for frame-based PE state
+
+**Verifies:** pe-frame-redesign.AC7.2 (partial — snapshot capture)
+
+**Files:**
+- Modify: `monitor/snapshot.py` (rewrite PESnapshot, update capture())
+
+**Implementation:**
+
+1. Replace PESnapshot fields:
+```python
+@dataclass(frozen=True)
+class PESnapshot:
+    pe_id: int
+    iram: dict[int, Instruction]
+    frames: tuple[tuple[FrameSlotValue, ...], ...]    # [frame_count][frame_slots]
+    tag_store: dict[int, int]                          # act_id → frame_id
+    presence: tuple[tuple[bool, ...], ...]             # [frame_count][matchable_offsets]
+    port_store: tuple[tuple[Port | None, ...], ...]   # [frame_count][matchable_offsets]
+    free_frames: tuple[int, ...]                       # available frame IDs
+    input_queue: tuple[Token, ...]
+    output_log: tuple[Token, ...]
+```
+
+2. Update `capture()` PE section:
+```python
+frames = tuple(
+    tuple(slot for slot in frame)
+    for frame in pe.frames
+)
+tag_store = dict(pe.tag_store)
+presence = tuple(
+    tuple(p for p in frame_presence)
+    for frame_presence in pe.presence
+)
+port_store = tuple(
+    tuple(p for p in frame_ports)
+    for frame_ports in pe.port_store
+)
+free_frames = tuple(pe.free_frames)
+```
+
+3. Update imports: add `Instruction`, `FrameSlotValue` from `cm_inst`, `Port` from `cm_inst`.
+
+4. Update SMSnapshot.t0_store type from `tuple[Token, ...]` to `tuple[int, ...]`.
+
+**Testing:**
+
+Tests must verify:
+- PESnapshot has frames, tag_store, presence, port_store, free_frames fields
+- PESnapshot does NOT have matching_store or gen_counters
+- capture() reads frame data correctly from live PE
+- SMSnapshot.t0_store contains ints
+
+Test file: `tests/test_snapshot.py` (update existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_snapshot.py -v`
+Expected: Updated snapshot tests pass. Tests referencing removed fields may still fail until fully converted.
+
+**Commit:** `feat: update PESnapshot for frame-based state capture`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Update monitor/graph_json.py for frame events and act_id
+
+**Verifies:** pe-frame-redesign.AC7.2 (partial — event serialization)
+
+**Files:**
+- Modify: `monitor/graph_json.py` (ctx → act_id, add new event types, PE state shows frames)
+
+**Implementation:**
+
+1. Node serialization: `"ctx": node.ctx` → `"act_id": node.act_id`
+
+2. Matched event: `"ctx": event.ctx` → `"act_id": event.act_id`, add `"frame_id": event.frame_id`
+
+3. Add new event type serialization:
+```python
+elif isinstance(event, FrameAllocated):
+    base["details"] = {
+        "act_id": event.act_id,
+        "frame_id": event.frame_id,
+    }
+elif isinstance(event, FrameFreed):
+    base["details"] = {
+        "act_id": event.act_id,
+        "frame_id": event.frame_id,
+    }
+elif isinstance(event, FrameSlotWritten):
+    base["details"] = {
+        "frame_id": event.frame_id,
+        "slot": event.slot,
+        "value": event.value,
+    }
+elif isinstance(event, TokenRejected):
+    base["details"] = {
+        "reason": event.reason,
+    }
+```
+
+4. PE state serialization: replace `matching_store` and `gen_counters` with frame data:
+```python
+pe_state = {
+    "pe_id": pe_snap.pe_id,
+    "iram": {str(k): _serialise_instruction(v) for k, v in pe_snap.iram.items()},
+    "frames": [[_serialise_slot(s) for s in frame] for frame in pe_snap.frames],
+    "tag_store": pe_snap.tag_store,
+    "free_frames": list(pe_snap.free_frames),
+    "input_queue_size": len(pe_snap.input_queue),
+}
+```
+
+5. SM state: `t0_store` serialized as list of ints (already correct format).
+
+6. Add imports for new event types.
+
+**Testing:**
+
+Tests must verify:
+- Node JSON has `act_id` key (not `ctx`)
+- Matched event JSON has `act_id` and `frame_id`
+- New events serialize correctly
+- PE state JSON has `frames`, `tag_store`, `free_frames` (not `matching_store`, `gen_counters`)
+
+Test file: `tests/test_monitor_graph_json.py` (update existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_monitor_graph_json.py -v`
+Expected: Updated serialization tests pass. Tests referencing removed fields may still fail until fully converted.
+
+**Commit:** `feat: update monitor graph JSON for frame events and act_id`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Update monitor/backend.py for setup_tokens
+
+**Verifies:** pe-frame-redesign.AC7.2 (partial — program loading)
+
+**Files:**
+- Modify: `monitor/backend.py` (inject setup_tokens before seed_tokens)
+
+**Implementation:**
+
+In `_handle_load()`, after building the topology and before injecting seed tokens, inject setup_tokens:
+
+```python
+# After system = build_topology(...)
+
+# Inject setup tokens (IRAM writes, ALLOC, frame slot writes)
+for token in result.setup_tokens:
+    system.inject(token)
+
+# Inject seed tokens
+for seed in result.seed_tokens:
+    system.inject(seed)
+```
+
+The `result` here is `AssemblyResult` which now has `setup_tokens`.
+
+Also update the PEConfig construction if backend.py creates configs directly (it may just pass through from codegen — verify).
+
+**Testing:**
+
+Tests must verify:
+- _handle_load() injects setup_tokens before seed_tokens
+- Setup tokens arrive at correct PEs
+
+Test file: `tests/test_backend.py` (update existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_backend.py -v`
+Expected: Updated backend tests pass. Tests referencing removed types may still fail.
+
+**Commit:** `feat: inject setup_tokens in monitor backend load`
+
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Update monitor/repl.py and monitor/formatting.py
+
+**Verifies:** pe-frame-redesign.AC7.2 (partial — REPL display)
+
+**Files:**
+- Modify: `monitor/repl.py` (update `pe` command display, update `send` command for act_id)
+- Modify: `monitor/formatting.py` (display frame state instead of matching store)
+
+**Implementation:**
+
+1. `monitor/repl.py`:
+   - `send` command: change `ctx` parameter to `act_id` in token construction
+   - `pe` command: display calls `format_pe_state()` which needs updating
+
+2. `monitor/formatting.py`:
+   - `format_pe_state()`: replace matching store occupancy count with frame state display:
+     ```
+     PE 0:
+       Tag store: {0: 0, 1: 1}
+       Free frames: [2, 3, 4, 5, 6, 7]
+       Frame 0: [1234, None, FrameDest(...), ...]
+       Frame 1: [5678, None, None, ...]
+     ```
+   - Remove gen_counters display
+   - Matched event formatting: `ctx=` → `act_id=`, add `frame_id=`
+
+**Testing:**
+
+Tests must verify:
+- `pe` command outputs frame state (not matching store)
+- `send` command accepts act_id parameter
+- Matched event formatting shows act_id and frame_id
+
+Test file: `tests/test_repl.py` and `tests/test_monitor_graph_json.py` (update existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_repl.py -v`
+Expected: Updated REPL tests pass. Tests referencing removed fields may still fail.
+
+**Commit:** `feat: update REPL and formatting for frame-based PE display`
+
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Update dfgraph/categories.py and dfgraph/graph_json.py
+
+**Verifies:** None (infrastructure)
+
+**Files:**
+- Modify: `dfgraph/categories.py` (FREE_CTX → FREE_FRAME, add EXTRACT_TAG)
+- Modify: `dfgraph/graph_json.py` (ctx → act_id)
+
+**Implementation:**
+
+1. `dfgraph/categories.py`:
+   - Update `_CONFIG_ROUTING_OPS` frozenset: `RoutingOp.FREE_CTX` → `RoutingOp.FREE_FRAME`
+   - Add `RoutingOp.EXTRACT_TAG` to `_CONFIG_ROUTING_OPS` (or a new category if appropriate — EXTRACT_TAG produces a value so it might be ROUTING rather than CONFIG)
+
+2. `dfgraph/graph_json.py`:
+   - Node serialization: `"ctx": node.ctx` → `"act_id": node.act_id`
+   - SM node synthesis: `"ctx": None` → `"act_id": None`
+
+**Testing:**
+
+Tests must verify:
+- `categorise(RoutingOp.FREE_FRAME)` returns CONFIG
+- `categorise(RoutingOp.EXTRACT_TAG)` returns expected category
+- Graph JSON has `act_id` key
+
+Test file: `tests/test_dfgraph_categories.py` and `tests/test_dfgraph_json.py` (update existing)
+
+**Verification:**
+Run: `python -m pytest tests/test_dfgraph_categories.py tests/test_dfgraph_json.py -v`
+Expected: All tests pass
+
+**Commit:** `feat: update dfgraph for FREE_FRAME, EXTRACT_TAG, and act_id`
+
+<!-- END_TASK_5 -->
+
+<!-- START_TASK_6 -->
+### Task 6: Run tests for updated monitor and dfgraph modules
+
+**Verifies:** None (regression)
+
+**Files:**
+- Possibly modify: various test files
+
+**Implementation:**
+
+Run the downstream consumer test suite:
+```
+python -m pytest tests/test_backend.py tests/test_snapshot.py tests/test_repl.py tests/test_monitor_graph_json.py tests/test_monitor_server.py tests/test_dfgraph_pipeline.py tests/test_dfgraph_json.py tests/test_dfgraph_server.py tests/test_dfgraph_categories.py -v
+```
+
+Focus on getting the new and updated tests working. Some tests may still reference removed types — those will be fixed in Phase 8 as part of the full suite clean pass.
+
+**Verification:**
+Run: `python -m pytest tests/ -v -k "(monitor or dfgraph or backend or snapshot or repl)"`
+Expected: New and updated monitor/dfgraph tests pass. Some legacy tests may still fail.
+
+**Commit:** `fix: resolve monitor and dfgraph test updates`
+
+<!-- END_TASK_6 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/phase_08.md

···
+# PE Frame-Based Redesign — Phase 8: Fix Remaining Broken Tests and End-to-End Verification
+
+**Goal:** Fix all tests that still reference removed or renamed types from earlier phases, verify the full pipeline works end-to-end, and get the entire test suite green.
+
+**Architecture:** Earlier phases made targeted changes without maintaining backward compatibility. Many legacy test files will be broken by the time this phase begins. Phase 8 is where those are found and fixed. The codebase itself should already be correct — this phase is about aligning tests with what the code now does.
+
+**Tech Stack:** Python 3.12
+
+**Scope:** Phase 8 of 8 from the PE frame-based redesign design plan.
+
+**Codebase verified:** 2026-03-07
+
+---
+
+## Acceptance Criteria Coverage
+
+This phase implements and tests:
+
+### pe-frame-redesign.AC7: End-to-end pipeline
+- **pe-frame-redesign.AC7.1 Success:** Existing test programs produce correct results through full pipeline (parse → ... → emulate)
+- **pe-frame-redesign.AC7.3 Success:** No backward compatibility shims remain (ALUInst, SMInst, IRAMWriteToken, MatchEntry removed)
+- **pe-frame-redesign.AC7.4 Success:** `python -m pytest tests/ -v` passes clean
+
+---
+
+<!-- START_TASK_1 -->
+### Task 1: Search for and remove remaining stale references
+
+**Verifies:** pe-frame-redesign.AC7.3 (partial)
+
+**Files:**
+- Modify: any source or test file containing stale references
+
+**Implementation:**
+
+Search the codebase for any remaining references to removed types and names. Fix or remove each one.
+
+Types and names to search for:
+- `ALUInst` — removed from cm_inst.py in Phase 1
+- `SMInst` — removed from cm_inst.py in Phase 1
+- `Addr` — removed from cm_inst.py in Phase 1
+- `IRAMWriteToken` — removed from tokens.py in Phase 1
+- `MatchEntry` — removed from emu/types.py in Phase 1
+- `FREE_CTX` — replaced by `FREE_FRAME`
+- `ctx_slots` — replaced by `frame_count`
+- `gen_counters` — removed from PEConfig
+- `CtxSlotRef` — renamed to `ActSlotRef`
+- `CtxSlotRange` — renamed to `ActSlotRange`
+- `free_ctx_nodes` — renamed to `free_frame_nodes`
+- `.ctx` on IRNode — renamed to `.act_id`
+- `.ctx_slot` on IRNode — renamed to `.act_slot`
+- `node.ctx` in codegen — renamed to `node.act_id`
+- `gen=` in DyadToken construction — field removed
+- `ArithOp.SHIFT_L` — renamed to `ArithOp.SHL`
+- `ArithOp.SHIFT_R` — renamed to `ArithOp.SHR`
+- `ArithOp.ASHFT_R` — renamed to `ArithOp.ASR`
+- `shiftl`/`shiftr`/`ashiftr` in dfasm grammar — renamed to `shl`/`shr`/`asr`
+- `ctx_override` on IREdge — rename to `change_tag` (maps to OutputStyle.CHANGE_TAG in allocate)
+
+For each reference found:
+- If in a test file: update the test to use the new name/type
+- If in a source file: this indicates an incomplete migration from an earlier phase — fix it
+
+Run grep or similar across the entire repo before and after to confirm nothing remains.
+
+**Verification:**
+Run: `python -c "import cm_inst, tokens, emu.types, asm.ir; print('imports OK')"`
+Expected: Prints "imports OK" (no import errors from stale references)
+
+**Commit:** `chore: remove all remaining stale references to legacy types`
+
+<!-- END_TASK_1 -->
+
+<!-- START_TASK_2 -->
+### Task 2: Fix remaining broken test files
+
+**Verifies:** pe-frame-redesign.AC7.4 (partial)
+
+**Files:**
+- Modify: all test files that fail due to stale type/field references
+
+**Implementation:**
+
+Run `python -m pytest tests/ -v` and collect all failures. For each failing test:
+
+1. Identify the cause — stale import, stale field access, stale constructor argument, or test helper that constructs old token types
+2. Update the test to use the new types and field names
+3. Re-run to confirm that specific test now passes
+
+Common patterns to fix:
+- `from cm_inst import ALUInst` → remove or replace with `from cm_inst import Instruction`
+- `from tokens import IRAMWriteToken` → remove or replace with `from tokens import PELocalWriteToken`
+- `DyadToken(..., ctx=x, gen=y, ...)` → `DyadToken(..., act_id=x, ...)`
+- `MonadToken(..., ctx=x, ...)` → `MonadToken(..., act_id=x, ...)`
+- `PEConfig(ctx_slots=N, offsets=M, ...)` → `PEConfig(frame_count=N, ...)`
+- `pe_snap.matching_store` → `pe_snap.frames`
+- `pe_snap.gen_counters` → removed (no replacement needed in assertions)
+- `event.ctx` on Matched events → `event.act_id`
+- `node.ctx` → `node.act_id`
+- `system.ctx_slots` → `system.frame_count`
+
+Work through the full test suite until no failures remain from stale references.
+
+**Verification:**
+Run: `python -m pytest tests/ -v --tb=no -q`
+Expected: Failure count decreasing with each fix
+
+**Commit:** `fix: update test files for frame-based types and field names`
+
+<!-- END_TASK_2 -->
+
+<!-- START_TASK_3 -->
+### Task 3: Fix remaining broken test files (continued)
+
+**Verifies:** pe-frame-redesign.AC7.4 (partial)
+
+**Files:**
+- Modify: test helper files and conftest.py if they construct old types
+
+**Implementation:**
+
+Check `tests/conftest.py` for Hypothesis strategies that generate old token types:
+- Strategies that produce `DyadToken` with `gen=` or `ctx=` fields need updating
+- Strategies that produce `IRAMWriteToken` need replacement with `PELocalWriteToken`
+- Strategies that use `ALUInst`/`SMInst` need replacement with `Instruction`
+
+Also check any shared test utility functions (helper builders used across multiple test files) for stale type usage.
+
+After updating conftest.py and helpers, re-run the full suite to catch any newly exposed failures.
+
+**Verification:**
+Run: `python -m pytest tests/ -v --tb=short -q`
+Expected: Only genuine test logic failures remain (if any), no import or AttributeError failures
+
+**Commit:** `fix: update conftest and test helpers for frame-based types`
+
+<!-- END_TASK_3 -->
+
+<!-- START_TASK_4 -->
+### Task 4: Update test_migration_cleanup.py
+
+**Verifies:** pe-frame-redesign.AC7.3
+
+**Files:**
+- Modify: `tests/test_migration_cleanup.py` (add checks for removed frame-migration types)
+
+**Implementation:**
+
+Add test cases verifying removed types are absent:
+
+```python
+def test_aluinst_removed():
+    """ALUInst should not be importable from cm_inst."""
+    with pytest.raises(ImportError):
+        from cm_inst import ALUInst
+
+def test_sminst_removed():
+    """SMInst should not be importable from cm_inst."""
+    with pytest.raises(ImportError):
+        from cm_inst import SMInst
+
+def test_addr_removed():
+    """Addr should not be importable from cm_inst."""
+    with pytest.raises(ImportError):
+        from cm_inst import Addr
+
+def test_iram_write_token_removed():
+    """IRAMWriteToken should not be importable from tokens."""
+    with pytest.raises(ImportError):
+        from tokens import IRAMWriteToken
+
+def test_match_entry_removed():
+    """MatchEntry should not be importable from emu.types."""
+    with pytest.raises(ImportError):
+        from emu.types import MatchEntry
+
+def test_free_ctx_removed():
+    """FREE_CTX should not exist as a separate value in RoutingOp."""
+    from cm_inst import RoutingOp
+    assert not hasattr(RoutingOp, 'FREE_CTX') or RoutingOp.FREE_CTX == RoutingOp.FREE_FRAME
+```
+
+Also add positive tests that new types ARE importable:
+```python
+def test_instruction_exists():
+    from cm_inst import Instruction, OutputStyle, FrameDest, FrameOp, TokenKind
+    assert Instruction is not None
+
+def test_pe_token_exists():
+    from tokens import PEToken, PELocalWriteToken, FrameControlToken
+    assert issubclass(PELocalWriteToken, PEToken)
+```
+
+**Verification:**
+Run: `python -m pytest tests/test_migration_cleanup.py -v`
+Expected: All tests pass
+
+**Commit:** `test: verify removed legacy types are absent from codebase`
+
+<!-- END_TASK_4 -->
+
+<!-- START_TASK_5 -->
+### Task 5: Update E2E tests for full pipeline
+
+**Verifies:** pe-frame-redesign.AC7.1, pe-frame-redesign.AC7.4
+
+**Files:**
+- Modify: `tests/test_e2e.py` (update run_program_direct and run_program_tokens helpers)
+- Modify: `tests/test_integration.py` (update for new types)
+
+**Implementation:**
+
+1. Update `run_program_direct()` helper:
+   - Use `assemble()` which returns `AssemblyResult` with `setup_tokens` and `seed_tokens`
+   - `PEConfig` now has `Instruction` IRAM and frame fields
+   - `build_topology()` takes new PEConfig format
+   - Inject `setup_tokens` before `seed_tokens`
+
+2. Update `run_program_tokens()` helper:
+   - Use `assemble_to_tokens()` which returns new token types
+   - Token sequence includes `PELocalWriteToken`, `FrameControlToken`
+   - Load tokens via `system.load()`
+
+3. Update all token constructor calls: `ctx=` → `act_id=`, remove `gen=`
+
+4. Update all PEConfig constructor calls: remove `ctx_slots`, `offsets`, `gen_counters`
+
+5. Verify existing test programs produce correct results:
+   - Simple add program: two values → correct sum
+   - Const program: constant injection → correct output
+   - Any branch/switch programs: correct routing
+   - SM programs: correct I-structure semantics
+
+**Testing:**
+
+The E2E tests themselves ARE the AC7.1 verification. They run the full pipeline and check results.
+
+**Verification:**
+Run: `python -m pytest tests/test_e2e.py tests/test_integration.py -v`
+Expected: All tests pass
+
+**Commit:** `test: update E2E tests for frame-based pipeline`
+
+<!-- END_TASK_5 -->
+
+<!-- START_TASK_6 -->
+### Task 6: Full test suite clean pass
+
+**Verifies:** pe-frame-redesign.AC7.4
+
+**Files:**
+- Modify: any remaining test files with stale references
+
+**Implementation:**
+
+This is the final task. Run the full test suite and fix every remaining failure:
+
+```
+python -m pytest tests/ -v
+```
+
+Work through failures one by one. At this point all failures should be:
+- Stale type references not caught in Tasks 1-3
+- Test logic that needs updating to match new behaviour
+- Any test helpers that still construct old token types
+
+After each fix, re-run the suite to confirm the fix did not introduce new failures.
+
+The suite is done when `python -m pytest tests/ -v` exits with zero failures and zero errors.
+
+**Verification:**
+Run: `python -m pytest tests/ -v`
+Expected: All tests pass with zero failures
+
+**Commit:** `chore: final cleanup — all tests pass clean`
+
+<!-- END_TASK_6 -->
+
+<!-- START_TASK_7 -->
+### Task 7: Update CLAUDE.md files
+
+**Verifies:** None (documentation)
+
+**Files:**
+- Modify: `CLAUDE.md` (root project instructions)
+- Modify: `asm/CLAUDE.md` (assembler package docs)
+
+**Implementation:**
+
+Both CLAUDE.md files extensively reference removed types and old field names. Update:
+
+1. Root `CLAUDE.md`:
+   - Token hierarchy: remove `IRAMWriteToken`, add `PELocalWriteToken` and `FrameControlToken`, rename `ctx` → `act_id`, remove `gen` from DyadToken, add PEToken base class
+   - Instruction set: replace `ALUInst`/`SMInst`/`Addr` docs with `Instruction`/`FrameDest`/`OutputStyle`/`TokenKind`
+   - PE section: replace matching_store/gen_counters with frames/tag_store/presence/port_store/free_frames, update pipeline order to IFETCH→act_id resolution→MATCH→EXECUTE→EMIT
+   - SM section: t0_store is `list[int]` not `list[Token]`
+   - Event types: add FrameAllocated, FrameFreed, FrameSlotWritten, TokenRejected; update Matched.ctx→act_id
+   - PEConfig: remove ctx_slots, offsets, gen_counters; add frame_count, frame_slots, matchable_offsets, initial_frames, initial_tag_store
+   - Module dependency graph: add encoding.py
+
+2. `asm/CLAUDE.md`:
+   - IR types: ctx→act_id, ctx_slot→act_slot, add mode/fref/wide/frame_layout fields, FrameSlotMap, FrameLayout
+   - SystemConfig: ctx_slots→frame_count, add frame_slots, matchable_offsets
+   - Allocate: describe frame layout computation, IRAM dedup, act_id assignment
+   - Codegen: describe setup_tokens, PELocalWriteToken/FrameControlToken generation
+   - ErrorCategory: add FRAME
+
+Update the `<!-- freshness: ... -->` date on both files.
+
+**Verification:**
+Manual review — ensure no references to removed types remain in either file.
+
+**Commit:** `docs: update CLAUDE.md files for frame-based architecture`
+
+<!-- END_TASK_7 -->

docs/implementation-plans/2026-03-06-pe-frame-redesign/test-requirements.md

···
+# Test Requirements -- PE Frame-Based Redesign
+
+This document maps each acceptance criterion from the PE frame-based redesign
+design plan to either an automated test or a documented human verification step.
+Every AC is accounted for. Test file paths reflect both new files introduced by
+the implementation plan and updates to existing test files.
+
+## Automated Test Coverage
+
+### AC1: Token hierarchy correctly models frame-based architecture
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC1.1 | unit | tests/test_foundation_types.py | Verify `issubclass(CMToken, PEToken)`, `issubclass(PELocalWriteToken, PEToken)`, `issubclass(FrameControlToken, PEToken)`, `issubclass(PEToken, Token)`. Verify transitive: `isinstance(DyadToken(...), PEToken)` is True. Verify `isinstance(SMToken(...), PEToken)` is False. Verify `IRAMWriteToken` does not exist in `tokens` module. |
+| AC1.2 | unit | tests/test_foundation_types.py | Verify `CMToken` constructor accepts `act_id` keyword (not `ctx`). Verify `DyadToken` constructor has no `gen` parameter (raises `TypeError` if `gen=` is passed). Verify all token types are frozen dataclasses. |
+| AC1.3 | unit | tests/test_foundation_types.py | Verify `PELocalWriteToken` has `region`, `slot`, `data`, `is_dest` fields. Construct instances with various field values and confirm frozen dataclass semantics. |
+| AC1.4 | unit | tests/test_foundation_types.py | Verify `FrameControlToken` has `act_id`, `op`, `payload` fields. Verify `op` accepts `FrameOp.ALLOC` and `FrameOp.FREE` values. |
+| AC1.5 | integration | tests/test_network_routing.py | Inject `PELocalWriteToken(target=0)`, `FrameControlToken(target=0)`, `DyadToken(target=0)`, and `SMToken(target=0)` via `System.inject()`. Verify PE-bound tokens arrive at PE 0's `input_store` and SM-bound tokens arrive at SM 0's `input_store`. Verify `build_topology()` routes all three PE-bound token types via the single `isinstance(token, PEToken)` check. |
+| AC1.6 | unit | tests/test_pe_frames.py | Inject a `DyadToken` with an `act_id` not present in the PE's `tag_store`. Verify the token is dropped (no crash, no output token). Verify a `TokenRejected` event is emitted with `reason` containing the invalid `act_id`. |
+
+### AC2: Semantic Instruction model with pack/unpack
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC2.1 | unit | tests/test_foundation_types.py | Construct `Instruction` with all field types (`opcode: ALUOp`, `output: OutputStyle`, `has_const: bool`, `dest_count: int`, `wide: bool`, `fref: int`). Verify frozen dataclass. Verify `OutputStyle`, `TokenKind`, `FrameOp` enum values. Verify `RoutingOp.EXTRACT_TAG` (value 31), `RoutingOp.FREE_FRAME` (value 29), `RoutingOp.ALLOC_REMOTE` (value 30) exist. Verify `ArithOp.SHL` (8), `ArithOp.SHR` (9), `ArithOp.ASR` (10) exist and old names (`SHIFT_L`, `SHIFT_R`, `ASHFT_R`) do not. Verify all ALUOp values fit in 5 bits. |
+| AC2.2 | unit | tests/test_encoding.py | Property-based round-trip: `unpack_instruction(pack_instruction(inst)) == inst` for all valid mode combinations (modes 0-7) x wide x opcode classes (ArithOp, LogicOp, RoutingOp, MemOp) x fref 0-63. Verify mode encoding matches design-notes bit decode table. Verify opcode encoding is identity (Python IntEnum values match hardware). `pack_flit1`/`unpack_flit1` round-trip for all token kinds (DYADIC, MONADIC, INLINE) with various target_pe, offset, act_id, port values. Edge cases: fref=0, fref=63, target_pe=0, target_pe=3, act_id=0, act_id=7. |
+| AC2.3 | unit | tests/test_foundation_types.py | Verify `isinstance(Instruction(opcode=MemOp.READ, ...).opcode, MemOp)` returns `True`. Verify `isinstance(Instruction(opcode=ArithOp.ADD, ...).opcode, MemOp)` returns `False`. No stored `type` field on `Instruction`. |
+| AC2.4 | integration | tests/test_pe_frames.py | Verify the PE processes `Instruction` objects using only semantic fields (`output`, `has_const`, `dest_count`, `wide`, `fref`). Verify no raw mode bits or pack/unpack calls in the PE's main pipeline (IFETCH/MATCH/EXECUTE/EMIT). Only CHANGE_TAG, EXTRACT_TAG, and PELocalWriteToken(region=0) use encoding boundary functions. |
+
+### AC3: Frame-based PE matching and output routing
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC3.1 | unit | tests/test_pe_frames.py | Construct PE with `frame_count=4`, `frame_slots=32`, `matchable_offsets=4`. Verify values stored on PE instance. Verify defaults (8, 64, 8) when not specified. |
+| AC3.2 | integration | tests/test_pe_frames.py | Inject a DyadToken pair targeting the same offset and act_id. Capture events via `on_event`. Verify event ordering: `TokenReceived` then `Matched` then `Executed` then `Emitted`. Verify IFETCH occurs before MATCH (instruction fetched from IRAM before matching attempted). |
+| AC3.3 | integration | tests/test_pe_frames.py | Pre-configure `tag_store` and frame with presence bits. Inject two `DyadToken`s at the same offset and act_id (one Port.L, one Port.R). Verify they match via frame SRAM and presence bits (not via `matching_store` array). Verify `Matched` event contains correct `left`, `right`, `act_id`, `offset`, `frame_id`. Verify port metadata determines left/right ordering. |
+| AC3.4 | integration | tests/test_pe_frames.py | Pre-load a `FrameDest` into a frame destination slot. Set up an `Instruction` with `OutputStyle.INHERIT`. Inject tokens to trigger execution. Verify the output token has `target`, `offset`, `act_id`, `port` matching the `FrameDest` values. |
+| AC3.5 | integration | tests/test_pe_frames.py | Set up an `Instruction` with `OutputStyle.CHANGE_TAG`. Inject a token whose left operand is a packed flit 1 value (from `pack_flit1(some_dest)`). Verify the output token's destination matches the unpacked `FrameDest` (target_pe, offset, act_id, port from the left operand, not from a frame slot). |
+| AC3.6 | integration | tests/test_pe_frames.py | Set up an `Instruction` with `OutputStyle.SINK`. Inject tokens to trigger execution. Verify the ALU result is written to `frames[frame_id][inst.fref]`. Verify no output token is emitted (`output_log` unchanged). Verify `FrameSlotWritten` event is emitted. |
+| AC3.7 | integration | tests/test_pe_frames.py | Set up an `Instruction` with `opcode=RoutingOp.EXTRACT_TAG` and `OutputStyle.INHERIT`. Inject a `MonadToken`. Verify the result is `pack_flit1(FrameDest(target_pe=pe_id, offset=token.offset, act_id=token.act_id, port=Port.L, token_kind=TokenKind.DYADIC))`. Verify the result is emitted as the data field of the output token. Verify `Executed` event shows the EXTRACT_TAG opcode. |
+| AC3.8 | integration | tests/test_pe_frames.py | Inject `FrameControlToken(op=FrameOp.ALLOC, act_id=X)`. Verify `tag_store[X]` is set to a valid `frame_id`, frame_id removed from `free_frames`, `FrameAllocated` event emitted. Inject `FrameControlToken(op=FrameOp.FREE, act_id=X)`. Verify `tag_store[X]` is removed, frame_id returned to `free_frames`, `FrameFreed` event emitted. Also test `FREE_FRAME` opcode path: set up a `FREE_FRAME` instruction in IRAM, inject a `MonadToken`, verify tag_store cleared, frame returned, `FrameFreed` event, no output token. Also test `ALLOC_REMOTE`: set up `ALLOC_REMOTE` instruction with target PE/act_id in frame constants, inject `MonadToken`, verify a `FrameControlToken(ALLOC)` is delivered to the target PE. |
+| AC3.9 | integration | tests/test_pe_frames.py | Inject `PELocalWriteToken(region=1, is_dest=True, data=pack_flit1(some_dest))`. Verify the frame slot at `token.slot` contains a `FrameDest` object (not a raw int). Verify `FrameSlotWritten` event. Also test `is_dest=False`: verify frame slot contains the raw int. |
+| AC3.10 | integration | tests/test_pe_frames.py | Inject a dyadic token pair at time T. Verify output token emitted at T+5 (dequeue 1 + IFETCH 1 + MATCH 1 + EXECUTE 1 + EMIT 1). Inject a monadic token at time T. Verify output at T+4 (dequeue 1 + IFETCH 1 + EXECUTE 1 + EMIT 1). Inject `FrameControlToken`/`PELocalWriteToken` at time T. Verify completion at T+2 (dequeue 1 + handle 1). Network delivery adds 1 additional cycle (separate process). |
+
+### AC4: T0 raw storage and EXEC
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC4.1 | unit | tests/test_sm_t0_raw.py | After SM construction, verify `t0_store` is `list[int]`. Perform a T0 WRITE operation, verify stored values are ints (not Token objects). |
+| AC4.2 | integration | tests/test_sm_t0_raw.py | Pre-load `t0_store` with packed token flits via `pack_token()` for multiple tokens (DyadToken, MonadToken, SMToken). Trigger EXEC at the starting address. Verify reconstituted tokens arrive at target PEs/SMs with correct field values. Verify `flit_count()` correctly determines packet boundaries for consecutive multi-flit packets. |
+| AC4.3 | unit | tests/test_encoding.py | Property-based round-trip: `unpack_token(pack_token(token))` produces a token with matching fields for `DyadToken`, `MonadToken`, and `SMToken`. Verify `SMToken.ret` is not preserved (round-trips as `None`). Also tested implicitly in `tests/test_sm_t0_raw.py` through EXEC end-to-end. Update `tests/test_sm_tiers.py` and `tests/test_exec_bootstrap.py` to use `pack_token()` for T0 pre-loading. |
+| AC4.4 | unit | tests/test_sm_t0_raw.py | Pre-load `t0_store` with invalid prefix bits (e.g., `[0xFFFF]`). Trigger EXEC. Verify SM stops gracefully without crash and logs a warning. Also test truncated packet: set `flit_count` to indicate 3 flits but provide only 2 ints -- verify graceful stop with warning. |
+
+### AC5: Assembler allocate produces frame layouts
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC5.1 | unit | tests/test_allocate_frames.py | Create two IR nodes on the same PE with identical opcode, mode, wide, and fref. Run `_deduplicate_iram()`. Verify both nodes share the same IRAM offset. Create nodes with different opcodes or modes and verify they get different offsets. Verify seed nodes are excluded. |
+| AC5.2 | unit | tests/test_allocate_frames.py | Create two activations of the same function body (same set of instructions). Run `_compute_frame_layouts()`. Verify both activations produce identical `FrameLayout` objects (same `FrameSlotMap`). |
+| AC5.3 | unit | tests/test_allocate_frames.py | Run `_assign_act_ids()` with multiple function scopes on a single PE. Verify act_ids assigned 0, 1, 2, ... sequentially. Verify at most `frame_count` concurrent act_ids per PE. Verify same function on different PEs can reuse act_id 0. |
+| AC5.4 | unit | tests/test_allocate_frames.py | Run `_compute_frame_layouts()` on an activation with dyadic and monadic nodes, constants, and multiple output edges. Verify match operand slots at 0 to `matchable_offsets-1` (indexed by IRAM offset). Verify constants (deduplicated by value) at `matchable_offsets` and above. Verify destinations (deduplicated by FrameDest identity) after constants. Verify sinks/SM params after destinations. |
+| AC5.5 | unit | tests/test_allocate_frames.py | Run `_compute_modes()` on nodes with varying edge topologies. Verify: 0 outgoing edges + FREE_FRAME opcode produces `(OutputStyle.SINK, *, 0)`. 1 outgoing edge produces `(OutputStyle.INHERIT, *, 1)`. 2 outgoing edges produces `(OutputStyle.INHERIT, *, 2)`. Edge with `ctx_override=True` produces `OutputStyle.CHANGE_TAG`. Verify `has_const` derived from `node.const is not None`. Verify SM sink ops (WRITE, CLEAR, etc.) produce `OutputStyle.SINK`. |
+| AC5.6 | unit | tests/test_allocate_frames.py | Create an activation requiring more frame slots than `frame_slots` limit. Verify `_compute_frame_layouts()` reports an error with `ErrorCategory.FRAME`. |
+| AC5.7 | unit | tests/test_allocate_frames.py | Create a PE requiring more than `frame_count` concurrent activations. Verify `_assign_act_ids()` reports an error with `ErrorCategory.FRAME` and message containing "activation ID exhaustion". |
+| AC5.8 | unit | tests/test_allocate_frames.py | Create an activation with more dyadic IRAM offsets than `matchable_offsets`. Verify a warning is emitted with `ErrorCategory.FRAME` and `severity="warning"`. Verify placement still succeeds (not an error). Also tested in `tests/test_place.py` (update existing `_count_iram_cost` tests to expect cost=1 for all node types). |
+
+### AC6: Assembler codegen produces frame setup tokens
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC6.1 | unit | tests/test_codegen_frames.py | Verify `AssemblyResult` dataclass has a `setup_tokens` field of type `list[Token]`. |
+| AC6.2 | integration | tests/test_codegen_frames.py | Run `generate_tokens()` on a simple program. Inspect the output token list. Verify ordering: all `SMToken` writes first, then `PELocalWriteToken(region=0)` IRAM writes, then `FrameControlToken(op=ALLOC)`, then `PELocalWriteToken(region=1)` frame slot writes, then seed `DyadToken`/`MonadToken` last. |
+| AC6.3 | unit | tests/test_codegen_frames.py | Run `_build_iram_for_pe()` on allocated IR nodes. Verify IRAM entries are `Instruction` objects. Verify IRAM write `PELocalWriteToken` data field equals `pack_instruction(inst)` for each entry. Verify CM vs SM type derived from `isinstance(opcode, MemOp)`. |
+| AC6.4 | unit | tests/test_codegen_frames.py | Inspect destination frame slot write tokens in setup sequence. Verify each has `is_dest=True` and `data == pack_flit1(expected_frame_dest)`. |
+| AC6.5 | integration | tests/test_codegen_frames.py | For a program with T0 bootstrap data, verify T0 writes use `pack_token()` to produce packed flit sequences. Verify the written ints can be round-tripped back via `unpack_token()`. |
+| AC6.6 | unit | tests/test_codegen_frames.py | Verify seed tokens use `act_id` field. Verify `DyadToken` seeds have no `gen` field. Verify seed `MonadToken`s use `act_id`. Update `tests/test_codegen.py` for `act_id` rename and `gen` removal. |
+
+### AC7: End-to-end pipeline
+
+| AC | Test Type | Test File | Description |
+|---|---|---|---|
+| AC7.1 | e2e | tests/test_e2e.py | Run existing test programs through the full pipeline (parse, lower, expand, resolve, place, allocate, codegen, build_topology, inject setup_tokens + seed_tokens, run SimPy). Verify correct results for: simple add, constant injection, branch/switch routing, SM I-structure read/write. Update `run_program_direct()` and `run_program_tokens()` helpers for new types. |
+| AC7.1 | e2e | tests/test_integration.py | Update integration tests for new token types, field names, and PEConfig format. Verify programs produce correct outputs through the new frame-based pipeline. |
+| AC7.2 | integration | tests/test_backend.py | Verify `_handle_load()` injects `setup_tokens` before `seed_tokens`. Verify monitor loads programs and returns `GraphLoaded` with valid snapshot containing frame state. |
+| AC7.2 | integration | tests/test_snapshot.py | Verify `PESnapshot` has `frames`, `tag_store`, `presence`, `port_store`, `free_frames`. Verify `PESnapshot` does NOT have `matching_store` or `gen_counters`. Verify `capture()` reads frame data from live PE. Verify `SMSnapshot.t0_store` contains ints. |
+| AC7.2 | integration | tests/test_monitor_graph_json.py | Verify node JSON has `act_id` key (not `ctx`). Verify `Matched` event JSON has `act_id` and `frame_id`. Verify new event types (`FrameAllocated`, `FrameFreed`, `FrameSlotWritten`, `TokenRejected`) serialize correctly. Verify PE state JSON has `frames`, `tag_store`, `free_frames`. |
+| AC7.2 | integration | tests/test_repl.py | Verify `pe` command displays frame state (not matching store). Verify `send` command accepts `act_id` parameter. |
+| AC7.3 | unit | tests/test_migration_cleanup.py | Verify `ALUInst`, `SMInst`, `Addr` not importable from `cm_inst`. Verify `IRAMWriteToken` not importable from `tokens`. Verify `MatchEntry` not importable from `emu.types`. Verify `RoutingOp.FREE_CTX` does not exist (or is the same as `FREE_FRAME`). Verify positive: `Instruction`, `OutputStyle`, `FrameDest`, `PEToken`, `PELocalWriteToken`, `FrameControlToken` all importable. |
+| AC7.4 | e2e | tests/ (full suite) | `python -m pytest tests/ -v` passes with zero failures and zero errors. This is the final gate criterion verified in Phase 8 Task 6. |
+
+## Additional Test Files Updated (not new)
+
+These existing test files require updates for renamed fields and removed types.
+They do not map to specific ACs but are necessary for AC7.4 (full suite green):
+
+| Test File | Changes Required |
+|---|---|
+| tests/conftest.py | Update Hypothesis strategies: `ctx` to `act_id`, remove `gen`, add `PELocalWriteToken` and `FrameControlToken` strategies |
+| tests/test_alu.py | Rename shift op references (`SHIFT_L` to `SHL`, etc.), `FREE_CTX` to `FREE_FRAME`, add `EXTRACT_TAG`/`ALLOC_REMOTE` as no-op fallback cases |
+| tests/test_pe.py | Rename to use new PE constructor params, `act_id`, frame-based matching. May be superseded by `test_pe_frames.py`. |
+| tests/test_pe_events.py | Update for `act_id`, `Instruction` IRAM, frame-based PE constructor, new event fields |
+| tests/test_cycle_timing.py | Update PE construction and token fields; timing values unchanged (5/4/1 cycles) |
+| tests/test_sm_events.py | Update token constructor calls (`act_id`, no `gen`) |
+| tests/test_sm_tiers.py | Update T0 tests to use `pack_token()` for pre-loading, int retrieval |
+| tests/test_exec_bootstrap.py | Pre-load T0 with packed flits via `pack_token()` instead of Token objects |
+| tests/test_network_events.py | Update token types and field names |
+| tests/test_network.py | Update `PEConfig` construction, token fields |
+| tests/test_allocate.py | `ctx` to `act_id`, `ctx_slots` to `frame_count`, IRAM cost=1 for all nodes |
+| tests/test_place.py | `ctx_slots` to `frame_count`, IRAM cost=1, matchable offset warning |
+| tests/test_autoplacement.py | `ctx_slots` to `frame_count` |
+| tests/test_codegen.py | `ctx` to `act_id`, `gen` removal, `Instruction` IRAM, `PEConfig` new fields |
+| tests/test_lower.py | `ctx_slot` to `act_slot` |
+| tests/test_expand.py | `CtxSlotRef` to `ActSlotRef`, `FREE_CTX` to `FREE_FRAME` |
+| tests/test_call_wiring.py | `free_ctx_nodes` to `free_frame_nodes`, `FREE_CTX` to `FREE_FRAME` |
+| tests/test_serialize.py | `ctx` to `act_id`, `ctx_slot` to `act_slot` |
+| tests/test_seed_const.py | `ctx` to `act_id`, `gen` removal |
+| tests/test_sm_graph_nodes.py | Token field renames |
+| tests/test_macro_ir.py | `ctx_slot` to `act_slot` |
+| tests/test_macro_ret_wiring.py | `ctx_slot` to `act_slot`, `FREE_CTX` to `FREE_FRAME` |
+| tests/test_opcodes.py | Shift mnemonic renames, `free_ctx` to `free_frame`, add `extract_tag`/`alloc_remote` |
+| tests/test_dfgraph_categories.py | `FREE_CTX` to `FREE_FRAME`, add `EXTRACT_TAG` |
+| tests/test_dfgraph_json.py | `ctx` to `act_id` |
+| tests/test_monitor_server.py | Token field renames, new event types in WebSocket protocol |
+
+## Human Verification
+
+| AC | Justification | Verification Approach |
+|---|---|---|
+| AC2.4 | "Emulator PE never touches raw mode bits -- only semantic fields" is an architectural invariant about code structure, not runtime behavior. An automated test can verify that the PE does not import pack/unpack for its main pipeline, but confirming the *absence* of bit-level manipulation throughout the PE is a code review concern. | Code review of `emu/pe.py` after Phase 2. Verify: (1) no raw integer bit masking/shifting on instruction fields in `_process_token()`, `_match_frame()`, `_do_emit_new()`, `_emit_inherit()`, or `_emit_sink()`; (2) `pack_flit1`/`unpack_flit1` calls appear only in `_emit_change_tag()` (CHANGE_TAG path), EXTRACT_TAG handler, and `_handle_local_write()` (PELocalWriteToken region=0 decode); (3) `Instruction` fields accessed by name (`inst.output`, `inst.has_const`, `inst.fref`) rather than by bit extraction. A supplementary automated test in `tests/test_pe_frames.py` can use `inspect.getsource()` to grep for bit operations as a heuristic check. |
+| AC7.2 (REPL display) | The REPL `pe` command display of frame state is a human-facing text formatting concern. Automated tests verify the data is present, but the visual layout (indentation, column alignment, readability) requires human judgment. | Run `python -m monitor` with a loaded program, execute `pe 0`, visually confirm: tag store mapping displayed, free frames listed, frame slot contents shown per frame, no references to "matching store" or "gen counters". |
+| AC7.2 (WebSocket events) | While JSON serialization of new event types is tested automatically, verifying the monitor web UI correctly renders frame state and new events in the browser requires a running frontend. | Start `python -m monitor --web`, load a program, step through execution in the browser. Verify: frame state panel shows frames/tag_store/free_frames, event log shows FrameAllocated/FrameFreed/FrameSlotWritten/TokenRejected events with correct fields, no rendering errors in the console. |
+| Phase 8 CLAUDE.md updates | Documentation accuracy cannot be verified by automated tests. The root `CLAUDE.md` and `asm/CLAUDE.md` must be manually reviewed to ensure all references to removed types, old field names, and old pipeline descriptions have been updated. | Review both files against the final codebase state. Check: (1) token hierarchy section matches new PEToken-based hierarchy; (2) instruction set section describes Instruction/FrameDest/OutputStyle not ALUInst/SMInst/Addr; (3) PE section describes frames/tag_store not matching_store/gen_counters; (4) PEConfig section lists frame_count/frame_slots/matchable_offsets not ctx_slots/offsets; (5) event types section includes all four new events; (6) freshness date updated. |
+
+## Rationalization Against Implementation Decisions
+
+The following implementation decisions from the phase plans affect test strategy:
+
+1. **Phase 1 removes old types immediately** (no backward-compat shims). This means
+   many existing tests break at Phase 1 and are not fixed until Phase 8. Test files
+   created in Phases 1-7 (`test_foundation_types.py`, `test_encoding.py`,
+   `test_pe_frames.py`, `test_sm_t0_raw.py`, `test_network_routing.py`,
+   `test_allocate_frames.py`, `test_codegen_frames.py`) are self-contained and pass
+   within their phase. The "full suite green" criterion (AC7.4) is only achievable
+   after Phase 8.
+
+2. **Enum value renumbering** (Task 1 of Phase 1) to match 5-bit hardware encoding
+   changes integer values of existing enums. Tests using `frozenset` membership on
+   enum objects are unaffected (membership is by identity). Tests comparing raw
+   integer values of enum members need updating.
+
+3. **IRAM deduplication is a post-processing step** (Phase 5 Task 1). The
+   `_deduplicate_iram()` function runs after `_compute_modes()` and
+   `_compute_frame_layouts()` produce `fref` and mode fields. AC5.1 tests must
+   set up fully-computed nodes (with mode and fref) before calling dedup.
+
+4. **Match slot indexing** uses `token.offset % matchable_offsets` (Phase 2 Task 2),
+   not a direct frame slot index. Tests for AC3.3 must set up IRAM offsets and
+   inject tokens at those offsets, not at arbitrary slot indices.
+
+5. **CHANGE_TAG uses the left operand** (not the ALU result) as the destination
+   descriptor (Phase 2 Task 2). Tests for AC3.5 must inject tokens where the left
+   data field contains a packed flit 1, and verify the destination is derived from
+   that left operand.
+
+6. **SMToken.ret is NOT preserved** through pack/unpack round-trip (Phase 1 Task 4).
+   Tests for AC4.3 must verify SMToken round-trips with `ret=None`. This is by
+   design -- SM return routes are stored as FrameDest in frame slots in the new model.
+
+7. **ctx_override on IREdge maps to OutputStyle.CHANGE_TAG** (Phase 5 Task 3). The
+   field is not renamed in Phase 5 but is scheduled for rename to `change_tag` in
+   Phase 8 cleanup. Tests for AC5.5 must use the `ctx_override` field name when
+   testing CHANGE_TAG mode derivation.

tests/conftest.py

···
 from hypothesis import strategies as st
 from lark import Lark
 
-from cm_inst import ArithOp, LogicOp, MemOp, Port, RoutingOp
-from tokens import CMToken, DyadToken, MonadToken, SMToken
+from cm_inst import ArithOp, FrameOp, LogicOp, MemOp, Port, RoutingOp
+from tokens import CMToken, DyadToken, FrameControlToken, MonadToken, PELocalWriteToken, SMToken
 
 GRAMMAR_PATH = Path(__file__).parent.parent / "dfasm.lark"
 
···
 
 arith_dyadic_ops = st.sampled_from([ArithOp.ADD, ArithOp.SUB])
 arith_monadic_ops = st.sampled_from([ArithOp.INC, ArithOp.DEC])
-shift_ops = st.sampled_from([ArithOp.SHIFT_L, ArithOp.SHIFT_R, ArithOp.ASHFT_R])
+shift_ops = st.sampled_from([ArithOp.SHL, ArithOp.SHR, ArithOp.ASR])
 logic_dyadic_ops = st.sampled_from([LogicOp.AND, LogicOp.OR, LogicOp.XOR])
 comparison_ops = st.sampled_from([LogicOp.EQ, LogicOp.LT, LogicOp.LTE, LogicOp.GT, LogicOp.GTE])
 branch_ops = st.sampled_from([RoutingOp.BREQ, RoutingOp.BRGT, RoutingOp.BRGE])
···
 
 
 @st.composite
-def dyad_token(draw, target: int = 0, offset: int | None = None, ctx: int | None = None, gen: int | None = None) -> DyadToken:
+def dyad_token(draw, target: int = 0, offset: int | None = None, act_id: int | None = None) -> DyadToken:
     return DyadToken(
         target=target,
         offset=draw(st.integers(min_value=0, max_value=63)) if offset is None else offset,
-        ctx=draw(st.integers(min_value=0, max_value=3)) if ctx is None else ctx,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
         data=draw(uint16),
         port=draw(st.sampled_from(list(Port))),
-        gen=draw(st.integers(min_value=0, max_value=3)) if gen is None else gen,
         wide=False,
     )
 
 
 @st.composite
-def monad_token(draw, target: int = 0, offset: int | None = None, ctx: int | None = None) -> MonadToken:
+def monad_token(draw, target: int = 0, offset: int | None = None, act_id: int | None = None) -> MonadToken:
     return MonadToken(
         target=target,
         offset=draw(st.integers(min_value=0, max_value=63)) if offset is None else offset,
-        ctx=draw(st.integers(min_value=0, max_value=3)) if ctx is None else ctx,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
         data=draw(uint16),
         inline=False,
     )
···
     _addr = draw(st.integers(min_value=0, max_value=255)) if addr is None else addr
     _op = draw(sm_all_ops) if op is None else op
     _data = draw(uint16) if data is None else data
-    ret = CMToken(target=0, offset=0, ctx=0, data=0)
+    ret = CMToken(target=0, offset=0, act_id=0, data=0)
     return SMToken(
         target=0,
         addr=_addr,
···
     return CMToken(
         target=target,
         offset=draw(st.integers(min_value=0, max_value=63)),
-        ctx=draw(st.integers(min_value=0, max_value=3)),
+        act_id=draw(st.integers(min_value=0, max_value=7)),
         data=0,
+    )
+
+
[e-mail]
+def pe_local_write_token(draw, target: int = 0, act_id: int | None = None) -> PELocalWriteToken:
+    return PELocalWriteToken(
+        target=target,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        region=draw(st.integers(min_value=0, max_value=1)),
+        slot=draw(st.integers(min_value=0, max_value=63)),
+        data=draw(uint16),
+        is_dest=draw(st.booleans()),
+    )
+
+
[e-mail]
+def frame_control_token(draw, target: int = 0, act_id: int | None = None) -> FrameControlToken:
+    return FrameControlToken(
+        target=target,
+        act_id=draw(st.integers(min_value=0, max_value=7)) if act_id is None else act_id,
+        op=draw(st.sampled_from(list(FrameOp))),
+        payload=draw(uint16),
     )
 
 

tests/test_foundation_types.py

···
+"""Tests for Phase 1 foundation types: cm_inst.py, tokens.py, and conftest.py updates.
+
+Verifies:
+- pe-frame-redesign.AC2.1: Instruction dataclass and field types
+- pe-frame-redesign.AC2.3: CM vs SM type derived from isinstance(opcode, MemOp)
+- pe-frame-redesign.AC1.1: PEToken inheritance hierarchy
+- pe-frame-redesign.AC1.2: act_id rename and gen removal
+- pe-frame-redesign.AC1.3: PELocalWriteToken fields
+- pe-frame-redesign.AC1.4: FrameControlToken fields
+"""
+
+import pytest
+from hypothesis import given
+
+from cm_inst import (
+    ArithOp, FrameDest, FrameOp, FrameSlotValue, Instruction, LogicOp,
+    MemOp, OutputStyle, Port, RoutingOp, TokenKind, is_monadic_alu,
+)
+from tests.conftest import (
+    dyad_token, frame_control_token, monad_token, pe_local_write_token,
+)
+from tokens import (
+    CMToken, DyadToken, FrameControlToken, MonadToken, PELocalWriteToken,
+    PEToken, SMToken, Token,
+)
+
+
+# ============================================================================
+# Task 1: New types in cm_inst.py
+# ============================================================================
+
+class TestInstructionType:
+    """AC2.1: Instruction dataclass with all field types."""
+
+    def test_instruction_construction(self):
+        """Instruction can be constructed with all field types."""
+        inst = Instruction(
+            opcode=ArithOp.ADD,
+            output=OutputStyle.INHERIT,
+            has_const=False,
+            dest_count=2,
+            wide=False,
+            fref=0,
+        )
+        assert inst.opcode == ArithOp.ADD
+        assert inst.output == OutputStyle.INHERIT
+        assert inst.has_const is False
+        assert inst.dest_count == 2
+        assert inst.wide is False
+        assert inst.fref == 0
+
+    def test_instruction_frozen(self):
+        """Instruction is a frozen dataclass."""
+        inst = Instruction(
+            opcode=ArithOp.ADD,
+            output=OutputStyle.INHERIT,
+            has_const=False,
+            dest_count=2,
+            wide=False,
+            fref=0,
+        )
+        with pytest.raises(AttributeError):
+            inst.fref = 1  # type: ignore
+
+    def test_instruction_with_mem_op(self):
+        """Instruction can accept MemOp opcodes."""
+        inst = Instruction(
+            opcode=MemOp.READ,
+            output=OutputStyle.INHERIT,
+            has_const=False,
+            dest_count=1,
+            wide=False,
+            fref=0,
+        )
+        assert isinstance(inst.opcode, MemOp)
+
+    def test_instruction_with_routing_op(self):
+        """Instruction can accept RoutingOp opcodes."""
+        inst = Instruction(
+            opcode=RoutingOp.BREQ,
+            output=OutputStyle.INHERIT,
+            has_const=True,
+            dest_count=1,
+            wide=True,
+            fref=63,
+        )
+        assert inst.opcode == RoutingOp.BREQ
+        assert inst.has_const is True
+        assert inst.wide is True
+        assert inst.fref == 63
+
+
+class TestInstructionSemantics:
+    """AC2.3: CM vs SM type derived from isinstance(opcode, MemOp)."""
+
+    def test_cm_type_from_alu_opcode(self):
+        """CM instruction can be identified by ALUOp opcode."""
+        inst = Instruction(
+            opcode=ArithOp.ADD,
+            output=OutputStyle.INHERIT,
+            has_const=False,
+            dest_count=2,
+            wide=False,
+            fref=0,
+        )
+        # CM type: opcode is NOT MemOp
+        assert not isinstance(inst.opcode, MemOp)
+
+    def test_sm_type_from_memop_opcode(self):
+        """SM instruction can be identified by MemOp opcode."""
+        inst = Instruction(
+            opcode=MemOp.READ,
+            output=OutputStyle.INHERIT,
+            has_const=False,
+            dest_count=1,
+            wide=False,
+            fref=0,
+        )
+        # SM type: opcode IS MemOp
+        assert isinstance(inst.opcode, MemOp)
+
+
+class TestOutputStyle:
+    """OutputStyle enum with correct values."""
+
+    def test_output_style_values(self):
+        """OutputStyle enum has correct values."""
+        assert OutputStyle.INHERIT.value == 0
+        assert OutputStyle.CHANGE_TAG.value == 1
+        assert OutputStyle.SINK.value == 2
+
+    def test_output_style_instances(self):
+        """Can construct Instructions with all OutputStyle values."""
+        for style in OutputStyle:
+            inst = Instruction(
+                opcode=ArithOp.ADD,
+                output=style,
+                has_const=False,
+                dest_count=1,
+                wide=False,
+                fref=0,
+            )
+            assert inst.output == style
+
+
+class TestTokenKind:
+    """TokenKind enum with correct values."""
+
+    def test_token_kind_values(self):
+        """TokenKind enum has correct values."""
+        assert TokenKind.DYADIC.value == 0
+        assert TokenKind.MONADIC.value == 1
+        assert TokenKind.INLINE.value == 2
+
+
+class TestFrameOp:
+    """FrameOp enum with correct values."""
+
+    def test_frame_op_values(self):
+        """FrameOp enum has correct values."""
+        assert FrameOp.ALLOC.value == 0
+        assert FrameOp.FREE.value == 1
+
+
+class TestFrameDest:
+    """FrameDest dataclass with correct fields."""
+
+    def test_frame_dest_construction(self):
+        """FrameDest can be constructed with all fields."""
+        dest = FrameDest(
+            target_pe=1,
+            offset=16,
+            act_id=3,
+            port=Port.L,
+            token_kind=TokenKind.DYADIC,
+        )
+        assert dest.target_pe == 1
+        assert dest.offset == 16
+        assert dest.act_id == 3
+        assert dest.port == Port.L
+        assert dest.token_kind == TokenKind.DYADIC
+
+    def test_frame_dest_frozen(self):
+        """FrameDest is a frozen dataclass."""
+        dest = FrameDest(
+            target_pe=1,
+            offset=16,
+            act_id=3,
+            port=Port.L,
+            token_kind=TokenKind.DYADIC,
+        )
+        with pytest.raises(AttributeError):
+            dest.offset = 20  # type: ignore
+
+
+class TestFrameSlotValue:
+    """FrameSlotValue type alias covers all valid types."""
+
+    def test_frame_slot_value_int(self):
+        """FrameSlotValue can be an int."""
+        val: FrameSlotValue = 42
+        assert isinstance(val, int)
+
+    def test_frame_slot_value_frame_dest(self):
+        """FrameSlotValue can be a FrameDest."""
+        dest = FrameDest(
+            target_pe=1,
+            offset=16,
+            act_id=3,
+            port=Port.L,
+            token_kind=TokenKind.DYADIC,
+        )
+        val: FrameSlotValue = dest
+        assert isinstance(val, FrameDest)
+
+    def test_frame_slot_value_none(self):
+        """FrameSlotValue can be None."""
+        val: FrameSlotValue = None
+        assert val is None
+
+
+class TestOpcodeRenumbering:
+    """Opcodes renumbered to match 5-bit hardware encoding."""
+
+    def test_arith_op_numbering(self):
+        """ArithOp values match 5-bit hardware encoding."""
+        assert ArithOp.ADD == 0b00000
+        assert ArithOp.SUB == 0b00001
+        assert ArithOp.INC == 0b00010
+        assert ArithOp.DEC == 0b00011
+        assert ArithOp.SHL == 0b01000  # 8
+        assert ArithOp.SHR == 0b01001  # 9
+        assert ArithOp.ASR == 0b01010  # 10
+
+    def test_logic_op_numbering(self):
+        """LogicOp values match 5-bit hardware encoding."""
+        assert LogicOp.AND == 0b00100  # 4
+        assert LogicOp.OR == 0b00101   # 5
+        assert LogicOp.XOR == 0b00110  # 6
+        assert LogicOp.NOT == 0b00111  # 7
+        assert LogicOp.EQ == 0b01011   # 11
+        assert LogicOp.LT == 0b01100   # 12
+        assert LogicOp.LTE == 0b01101  # 13
+        assert LogicOp.GT == 0b01110   # 14
+        assert LogicOp.GTE == 0b01111  # 15
+
+    def test_routing_op_numbering(self):
+        """RoutingOp values match 5-bit hardware encoding."""
+        assert RoutingOp.BREQ == 0b10000  # 16
+        assert RoutingOp.BRGT == 0b10001  # 17
+        assert RoutingOp.BRGE == 0b10010  # 18
+        assert RoutingOp.BROF == 0b10011  # 19
+        assert RoutingOp.SWEQ == 0b10100  # 20
+        assert RoutingOp.SWGT == 0b10101  # 21
+        assert RoutingOp.SWGE == 0b10110  # 22
+        assert RoutingOp.SWOF == 0b10111  # 23
+        assert RoutingOp.GATE == 0b11000  # 24
+        assert RoutingOp.SEL == 0b11001   # 25
+        assert RoutingOp.MRGE == 0b11010  # 26
+        assert RoutingOp.PASS == 0b11011  # 27
+        assert RoutingOp.CONST == 0b11100 # 28
+        assert RoutingOp.FREE_FRAME == 0b11101  # 29
+        assert RoutingOp.ALLOC_REMOTE == 0b11110 # 30
+        assert RoutingOp.EXTRACT_TAG == 0b11111  # 31
+
+    def test_all_opcodes_fit_5_bits(self):
+        """All ALU and MemOp opcodes fit in 5 bits (0-31)."""
+        for op in ArithOp:
+            assert 0 <= op <= 31
+        for op in LogicOp:
+            assert 0 <= op <= 31
+        for op in RoutingOp:
+            assert 0 <= op <= 31
+        for op in MemOp:
+            assert 0 <= op <= 31
+
+
+class TestOpcodeChanges:
+    """Removed/renamed opcodes are no longer available."""
+
+    def test_old_shift_names_gone(self):
+        """Old shift opcode names (SHIFT_L, SHIFT_R, ASHFT_R) don't exist."""
+        with pytest.raises(AttributeError):
+            ArithOp.SHIFT_L  # type: ignore
+        with pytest.raises(AttributeError):
+            ArithOp.SHIFT_R  # type: ignore
+        with pytest.raises(AttributeError):
+            ArithOp.ASHFT_R  # type: ignore
+
+    def test_new_shift_names_exist(self):
+        """New shift opcode names (SHL, SHR, ASR) exist."""
+        assert ArithOp.SHL == 8
+        assert ArithOp.SHR == 9
+        assert ArithOp.ASR == 10
+
+    def test_free_ctx_gone(self):
+        """FREE_CTX doesn't exist (renamed to FREE_FRAME)."""
+        with pytest.raises(AttributeError):
+            RoutingOp.FREE_CTX  # type: ignore
+
+    def test_free_frame_exists(self):
+        """FREE_FRAME exists (was FREE_CTX)."""
+        assert RoutingOp.FREE_FRAME == 29
+
+    def test_alloc_remote_exists(self):
+        """ALLOC_REMOTE opcode exists."""
+        assert RoutingOp.ALLOC_REMOTE == 30
+
+    def test_extract_tag_exists(self):
+        """EXTRACT_TAG opcode exists."""
+        assert RoutingOp.EXTRACT_TAG == 31
+
+
+class TestMonadicOps:
+    """_MONADIC_*_OPS sets updated for new opcode names."""
+
+    def test_shift_ops_monadic(self):
+        """SHL, SHR, ASR are monadic."""
+        assert is_monadic_alu(ArithOp.SHL)
+        assert is_monadic_alu(ArithOp.SHR)
+        assert is_monadic_alu(ArithOp.ASR)
+
+    def test_free_frame_monadic(self):
+        """FREE_FRAME is monadic."""
+        assert is_monadic_alu(RoutingOp.FREE_FRAME)
+
+    def test_alloc_remote_monadic(self):
+        """ALLOC_REMOTE is monadic."""
+        assert is_monadic_alu(RoutingOp.ALLOC_REMOTE)
+
+    def test_extract_tag_monadic(self):
+        """EXTRACT_TAG is monadic."""
+        assert is_monadic_alu(RoutingOp.EXTRACT_TAG)
+
+
+# ============================================================================
+# Task 2: Token hierarchy
+# ============================================================================
+
+class TestTokenHierarchy:
+    """AC1.1: PEToken base class and inheritance structure."""
+
+    def test_petoken_is_token(self):
+        """PEToken inherits from Token."""
+        assert issubclass(PEToken, Token)
+
+    def test_cmtoken_is_petoken(self):
+        """CMToken inherits from PEToken."""
+        assert issubclass(CMToken, PEToken)
+
+    def test_dyadtoken_is_cmtoken(self):
+        """DyadToken inherits from CMToken."""
+        assert issubclass(DyadToken, CMToken)
+
+    def test_monadtoken_is_cmtoken(self):
+        """MonadToken inherits from CMToken."""
+        assert issubclass(MonadToken, CMToken)
+
+    def test_pe_local_write_is_petoken(self):
+        """PELocalWriteToken inherits from PEToken."""
+        assert issubclass(PELocalWriteToken, PEToken)
+
+    def test_frame_control_is_petoken(self):
+        """FrameControlToken inherits from PEToken."""
+        assert issubclass(FrameControlToken, PEToken)
+
+    def test_smtoken_is_token(self):
+        """SMToken inherits from Token but NOT PEToken."""
+        assert issubclass(SMToken, Token)
+        assert not issubclass(SMToken, PEToken)
+
+    def test_dyadtoken_instanceof_petoken(self):
+        """DyadToken instances are PEToken (transitive)."""
+        token = DyadToken(
+            target=0,
+            offset=0,
+            act_id=0,
+            data=0,
+            port=Port.L,
+            wide=False,
+        )
+        assert isinstance(token, PEToken)
+        assert isinstance(token, CMToken)
+        assert isinstance(token, DyadToken)
+        assert isinstance(token, Token)
+
+    def test_smtoken_not_instanceof_petoken(self):
+        """SMToken instances are NOT PEToken."""
+        token = SMToken(
+            target=0,
+            addr=0,
+            op=MemOp.READ,
+            flags=None,
+            data=None,
+            ret=None,
+        )
+        assert isinstance(token, Token)
+        assert not isinstance(token, PEToken)
+
+
+class TestCMTokenFields:
+    """AC1.2: CMToken uses act_id (not ctx), DyadToken has no gen."""
+
+    def test_cmtoken_has_act_id(self):
+        """CMToken accepts act_id parameter."""
+        token = CMToken(
+            target=0,
+            offset=16,
+            act_id=3,
+            data=100,
+        )
+        assert token.act_id == 3
+
+    def test_cmtoken_no_ctx(self):
+        """CMToken doesn't accept ctx parameter."""
+        with pytest.raises(TypeError):
+            CMToken(
+                target=0,
+                offset=16,
+                ctx=3,  # type: ignore
+                data=100,
+            )
+
+    def test_dyadtoken_no_gen(self):
+        """DyadToken doesn't have gen parameter."""
+        with pytest.raises(TypeError):
+            DyadToken(
+                target=0,
+                offset=16,
+                act_id=3,
+                data=100,
+                port=Port.L,
+                gen=0,  # type: ignore
+                wide=False,
+            )
+
+    def test_dyadtoken_fields(self):
+        """DyadToken has correct fields."""
+        token = DyadToken(
+            target=0,
+            offset=16,
+            act_id=3,
+            data=100,
+            port=Port.R,
+            wide=True,
+        )
+        assert token.target == 0
+        assert token.offset == 16
+        assert token.act_id == 3
+        assert token.data == 100
+        assert token.port == Port.R
+        assert token.wide is True
+
+
+class TestPELocalWriteToken:
+    """AC1.3: PELocalWriteToken has region, slot, data, is_dest fields."""
+
+    def test_pe_local_write_fields(self):
+        """PELocalWriteToken has all required fields."""
+        token = PELocalWriteToken(
+            target=1,
+            act_id=2,
+            region=0,
+            slot=32,
+            data=500,
+            is_dest=True,
+        )
+        assert token.target == 1
+        assert token.act_id == 2
+        assert token.region == 0
+        assert token.slot == 32
+        assert token.data == 500
+        assert token.is_dest is True
+
+    def test_pe_local_write_frozen(self):
+        """PELocalWriteToken is frozen."""
+        token = PELocalWriteToken(
+            target=1,
+            act_id=2,
+            region=0,
+            slot=32,
+            data=500,
+            is_dest=True,
+        )
+        with pytest.raises(AttributeError):
+            token.slot = 40  # type: ignore
+
+
+class TestFrameControlToken:
+    """AC1.4: FrameControlToken has act_id, op, payload fields."""
+
+    def test_frame_control_fields(self):
+        """FrameControlToken has all required fields."""
+        token = FrameControlToken(
+            target=1,
+            act_id=3,
+            op=FrameOp.ALLOC,
+            payload=1000,
+        )
+        assert token.target == 1
+        assert token.act_id == 3
+        assert token.op == FrameOp.ALLOC
+        assert token.payload == 1000
+
+    def test_frame_control_frozen(self):
+        """FrameControlToken is frozen."""
+        token = FrameControlToken(
+            target=1,
+            act_id=3,
+            op=FrameOp.FREE,
+            payload=1000,
+        )
+        with pytest.raises(AttributeError):
+            token.op = FrameOp.ALLOC  # type: ignore
+
+
+class TestIRAMWriteTokenRemoved:
+    """IRAMWriteToken type removed from tokens.py."""
+
+    def test_iramwrite_token_does_not_exist(self):
+        """IRAMWriteToken is no longer available in tokens module."""
+        with pytest.raises(ImportError):
+            from tokens import IRAMWriteToken  # type: ignore
+
+
+# ============================================================================
+# Task 3: Hypothesis Strategies
+# ============================================================================
+
+class TestDyadTokenStrategy:
+    """dyad_token strategy uses act_id (not ctx), no gen."""
+
+    @given(dyad_token())
+    def test_dyad_token_strategy_generates_valid_tokens(self, token):
+        """dyad_token strategy generates valid DyadToken instances."""
+        assert isinstance(token, DyadToken)
+        assert hasattr(token, "act_id")
+        assert 0 <= token.act_id <= 7
+        assert not hasattr(token, "gen")
+
+    @given(dyad_token(act_id=5))
+    def test_dyad_token_strategy_respects_act_id(self, token):
+        """dyad_token strategy respects act_id parameter."""
+        assert token.act_id == 5
+
+
+class TestMonadTokenStrategy:
+    """monad_token strategy uses act_id (not ctx)."""
+
+    @given(monad_token())
+    def test_monad_token_strategy_generates_valid_tokens(self, token):
+        """monad_token strategy generates valid MonadToken instances."""
+        assert isinstance(token, MonadToken)
+        assert hasattr(token, "act_id")
+        assert 0 <= token.act_id <= 7
+
+    @given(monad_token(act_id=3))
+    def test_monad_token_strategy_respects_act_id(self, token):
+        """monad_token strategy respects act_id parameter."""
+        assert token.act_id == 3
+
+
+class TestPELocalWriteTokenStrategy:
+    """pe_local_write_token strategy generates valid tokens."""
+
+    @given(pe_local_write_token())
+    def test_pe_local_write_token_strategy_valid(self, token):
+        """pe_local_write_token strategy generates valid tokens."""
+        assert isinstance(token, PELocalWriteToken)
+        assert 0 <= token.act_id <= 7
+        assert 0 <= token.region <= 1
+        assert 0 <= token.slot <= 63
+
+    @given(pe_local_write_token(act_id=4))
+    def test_pe_local_write_token_strategy_respects_act_id(self, token):
+        """pe_local_write_token strategy respects act_id."""
+        assert token.act_id == 4
+
+
+class TestFrameControlTokenStrategy:
+    """frame_control_token strategy generates valid tokens."""
+
+    @given(frame_control_token())
+    def test_frame_control_token_strategy_valid(self, token):
+        """frame_control_token strategy generates valid tokens."""
+        assert isinstance(token, FrameControlToken)
+        assert 0 <= token.act_id <= 7
+        assert isinstance(token.op, FrameOp)
+
+    @given(frame_control_token(act_id=2))
+    def test_frame_control_token_strategy_respects_act_id(self, token):
+        """frame_control_token strategy respects act_id."""
+        assert token.act_id == 2

tokens.py

···
 from dataclasses import dataclass
 from typing import Optional
 
-from cm_inst import ALUInst, MemOp, Port, SMInst
+from cm_inst import FrameOp, MemOp, Port
 
 
 @dataclass(frozen=True)
-class Token(object):
+class Token:
     target: int
 
 
 @dataclass(frozen=True)
-class CMToken(Token):
+class PEToken(Token):
+    pass
+
+
+@dataclass(frozen=True)
+class CMToken(PEToken):
     offset: int
-    ctx: int
+    act_id: int
     data: int
 
 
 @dataclass(frozen=True)
 class DyadToken(CMToken):
     port: Port
-    gen: int
     wide: bool
 
 
···
 
 
 @dataclass(frozen=True)
-class IRAMWriteToken(CMToken):
-    instructions: tuple[ALUInst | SMInst, ...]
+class PELocalWriteToken(PEToken):
+    act_id: int
+    region: int
+    slot: int
+    data: int
+    is_dest: bool
+
+
+@dataclass(frozen=True)
+class FrameControlToken(PEToken):
+    act_id: int
+    op: FrameOp
+    payload: int
 
 
 @dataclass(frozen=True)