docs: fix CLAUDE.md inaccuracies from PE frame-based redesign

CLAUDE.md

···
 
 ## Project Structure
 
-- `cm_inst.py` — Instruction set definitions (Port, MemOp, ALUOp hierarchy, Instruction, FrameDest, OutputStyle, TokenKind)
-- `tokens.py` — Token type hierarchy (Token -> CMToken -> DyadToken/MonadToken/PELocalWriteToken/FrameControlToken; SMToken). Imports ISA enums from cm_inst.
+- `cm_inst.py` — Instruction set definitions (Port, MemOp, ALUOp hierarchy, Instruction, FrameDest, OutputStyle, TokenKind, FrameOp, FrameSlotValue)
+- `tokens.py` — Token type hierarchy (Token -> PEToken -> CMToken -> DyadToken/MonadToken; PEToken -> PELocalWriteToken/FrameControlToken; Token -> SMToken). Imports ISA enums from cm_inst.
+- `encoding.py` — Pack/unpack boundary between semantic types and 16-bit hardware words (instruction encoding, flit1 routing words)
 - `sm_mod.py` — Structure Memory cell model (Presence enum, SMCell dataclass with `is_wide` metadata flag)
 - `dfasm.lark` — Lark grammar for dfasm graph assembly language
 - `emu/` — Behavioural emulator package (SimPy-based discrete event simulation)
   - `emu/events.py` — Simulation event types: `SimEvent` union (TokenReceived, Matched, Executed, Emitted, IRAMWritten, FrameSlotWritten, FrameAllocated, FrameFreed, TokenRejected, CellWritten, DeferredRead, DeferredSatisfied, ResultSent) and `EventCallback` type alias
-  - `emu/types.py` — Config and internal types (PEConfig, SMConfig, DeferredRead, FrameSlotValue). PEConfig/SMConfig accept `on_event: EventCallback | None` for simulation observability.
+  - `emu/types.py` — Config and internal types (PEConfig, SMConfig, DeferredRead). PEConfig/SMConfig accept `on_event: EventCallback | None` for simulation observability.
   - `emu/alu.py` — Pure-function ALU: `execute(op, left, right, const) -> (result, bool_out)`
   - `emu/pe.py` — ProcessingElement: matching store, IRAM fetch, output routing, event emission via `on_event` callback
   - `emu/sm.py` — StructureMemory: I-structure semantics with deferred reads, event emission via `on_event` callback
···
   - `tests/test_sm_tiers.py` — T0/T1 memory tier and EXEC bootstrap tests
   - `tests/test_exec_bootstrap.py` — EXEC opcode acceptance criteria tests
   - `tests/test_migration_cleanup.py` — Verifies removed types (SysToken, CfgOp, etc.) are absent from codebase
-  - `tests/test_pe_events.py` — PE event emission tests (TokenReceived, Matched, Executed, Emitted, IRAMWritten)
+  - `tests/test_pe_events.py` — PE event emission tests (TokenReceived, Matched, Executed, Emitted, IRAMWritten, FrameAllocated, FrameFreed, FrameSlotWritten, TokenRejected)
+  - `tests/test_pe_frames.py` — Frame-based PE matching, routing, and lifecycle tests
   - `tests/test_sm_events.py` — SM event emission tests (CellWritten, DeferredRead, DeferredSatisfied, ResultSent)
-  - `tests/test_cycle_timing.py` — Cycle-accurate timing verification tests (PE pipeline stages, SM operation timing, network delivery latency, parallel execution)
+  - `tests/test_cycle_timing.py` — Cycle-accurate timing verification tests
   - `tests/test_network_events.py` — Network-level event propagation tests
+  - `tests/test_network_routing.py` — Network routing and connectivity tests
+  - `tests/test_foundation_types.py` — Foundation type (Instruction, FrameDest, encoding) tests
+  - `tests/test_encoding.py` — Pack/unpack encoding tests for instructions and flit1 words
+  - `tests/test_ir_frame_types.py` — IR frame-related type tests
+  - `tests/test_allocate_frames.py` — Frame layout allocation tests
+  - `tests/test_codegen_frames.py` — Frame-based code generation tests
+  - `tests/test_sm_t0_raw.py` — SM T0 raw storage tests
   - `tests/test_backend.py` — SimulationBackend command/result protocol tests
   - `tests/test_snapshot.py` — StateSnapshot capture tests
   - `tests/test_repl.py` — MonitorREPL command tests
···
 
 All tokens inherit from `Token(target: int)`. The hierarchy:
 
-- `CMToken(Token)` -- adds `act_id`, `data` (frozen dataclass, base for data-carrying tokens)
-  - `DyadToken(CMToken)` -- adds `port: Port`, `gen: int` (dyadic operand requiring match)
-  - `MonadToken(CMToken)` -- monadic operand (no match required)
-  - `PELocalWriteToken(CMToken)` -- adds `offset: int`, `values: list[int]` (writes IRAM directly)
-  - `FrameControlToken(CMToken)` -- frame lifecycle control (no data)
+- `PEToken(Token)` -- base for all PE-targeted tokens (used for routing in network.py)
+  - `CMToken(PEToken)` -- adds `offset: int`, `act_id: int`, `data: int` (frozen dataclass, base for data-carrying tokens)
+    - `DyadToken(CMToken)` -- adds `port: Port` (dyadic operand requiring match)
+    - `MonadToken(CMToken)` -- adds `inline: bool` (monadic operand, no match required)
+  - `PELocalWriteToken(PEToken)` -- adds `act_id`, `region`, `slot`, `data`, `is_dest` (writes frame slots directly)
+  - `FrameControlToken(PEToken)` -- adds `act_id`, `op: FrameOp`, `payload: int` (frame alloc/free)
 - `SMToken(Token)` -- `addr: int`, `op: MemOp`, `flags`, `data`, `ret: Optional[CMToken]`
 
 ### Instruction Set (cm_inst.py)
 
 - `ALUOp(IntEnum)` base with subclasses: `ArithOp`, `LogicOp`, `RoutingOp`
-- `MemOp(IntEnum)` -- read/write/atomic ops; includes WRITE, READ, FREE, CLEAR, EXEC, SET_PAGE, WRITE_IMM for T0 tier control
-- `Instruction(op, has_const: bool, fref: int)` -- unified instruction type for both ALU and memory ops, stored in PE IRAM
+- `MemOp(IntEnum)` -- read/write/atomic ops (READ, WRITE, EXEC, ALLOC, FREE, EXT, CLEAR, RD_INC, RD_DEC, CMP_SW, RAW_READ, SET_PAGE, WRITE_IMM)
+- `Instruction(opcode, output: OutputStyle, has_const, dest_count, wide, fref)` -- unified instruction type for both ALU and memory ops, stored in PE IRAM
 - `FrameDest(target_pe: int, offset: int, act_id: int, port: Port, token_kind: TokenKind)` -- destination address resolved from frame slot
+- `FrameSlotValue = int | FrameDest | None` -- type alias for frame slot contents
 - `OutputStyle` enum -- INHERIT, CHANGE_TAG, SINK for output routing decisions
-- `TokenKind` enum -- DYADIC, MONADIC for token kind classification
+- `TokenKind` enum -- DYADIC, MONADIC, INLINE for token kind classification
+- `FrameOp(IntEnum)` -- ALLOC, FREE for frame lifecycle control tokens
 - `is_monadic_alu(op: ALUOp) -> bool` -- canonical source of truth for monadic ALU op classification (used by `emu/pe.py` and `asm/opcodes.py`)
 
 ### ALU (emu/alu.py)
···
 
 **Token Processing Pipeline:**
 - Side paths (FrameControlToken, PELocalWriteToken): 1 cycle
-- Dyadic CMToken: 5 cycles (dequeue + MATCH + IFETCH + EXECUTE + EMIT)
+- Dyadic CMToken: 5 cycles (dequeue + IFETCH + MATCH + EXECUTE + EMIT)
 - Monadic CMToken: 4 cycles (dequeue + IFETCH + EXECUTE + EMIT)
 
 **Matching Logic:**
···
 - If slot occupied: retrieve partner data and port, clear presence bit, fire instruction with both operands
 - Port ordering: partner with Port.L goes to left operand; Port.R to right operand
 
-**Output Routing** (determined by `Instruction.mode`):
+**Output Routing** (determined by `Instruction.output`):
 - `OutputStyle.INHERIT` -- routes to destinations specified in frame slots
 - `OutputStyle.CHANGE_TAG` -- routes with different act_id tag (context switch)
 - `OutputStyle.SINK` -- writes result to frame slot, emits no token
 
 **Frame Initialization:**
-- PE constructor loads initial_frames from PEConfig (dict or list format)
-- Dict format: {frame_id: {slot_idx: int_value}} where int_value is unpacked via unpack_flit1() to FrameDest
+- PE constructor loads initial_frames from PEConfig: `dict[int, dict[int, FrameSlotValue] | list[FrameSlotValue]]`
+- Dict value format: `{slot_idx: value}` where int values are unpacked via `unpack_flit1()` to FrameDest
+- List value format: `[slot0, slot1, ...]` raw values assigned by index
 - Handles both codegen-produced packed integers and test-produced FrameDest objects
 
 **Output logging:**
 - `PE.output_log: list` records every token emitted (for testing and tracing)
 
 **PELocalWriteToken handling:**
-- Writes values directly to IRAM at specified offset (1 cycle)
+- Writes data to frame slot at specified region/slot within the act_id's frame (1 cycle)
 
 ### Structure Memory (emu/sm.py)
 
···
 - If `PEConfig.allowed_pe_routes` or `allowed_sm_routes` is set, `build_topology` restricts routes at construction time
 
 **System API:**
-- `System.inject(token: Token)` -- route token by type: SMToken → target SM, CMToken → target PE (IRAMWriteToken routes to PE automatically as CMToken subclass) (direct append, bypasses FIFO)
+- `System.inject(token: Token)` -- route token by type: SMToken → target SM, PEToken → target PE (direct append, bypasses FIFO)
 - `System.send(token: Token)` -- same routing as inject() but yields `env.timeout(1)` for 1-cycle delivery latency then `store.put()` (SimPy generator, respects FIFO backpressure)
 - `System.load(tokens: list[Token])` -- spawns SimPy process that calls send() for each token in order
 
-**PEConfig extensions (emu/types.py):**
+**PEConfig (emu/types.py):**
+- `pe_id: int`, `iram: dict[int, Instruction] | None`, `frame_count: int = 8`, `frame_slots: int = 64`, `matchable_offsets: int = 8`
+- `initial_frames: Optional[dict[int, list[FrameSlotValue]]]` -- pre-loaded frame data
+- `initial_tag_store: Optional[dict[int, int]]` -- pre-loaded act_id -> frame_id mappings
 - `allowed_pe_routes: Optional[set[int]]` -- if set, restrict PE route_table to these PE IDs
 - `allowed_sm_routes: Optional[set[int]]` -- if set, restrict PE sm_routes to these SM IDs
-- `on_event: EventCallback | None` -- if set, PE fires `SimEvent` for every token receive, match, execute, emit, and IRAM write
+- `on_event: EventCallback | None` -- if set, PE fires `SimEvent` for every token receive, match, execute, emit, frame alloc/free, slot write, and rejection
 
 **SMConfig (emu/types.py):**
 - `sm_id: int`, `cell_count: int = 512`, `initial_cells: Optional[dict]`, `tier_boundary: int = 256`
···
 
 **Event types:**
 - `TokenReceived(time, component, token)` -- PE/SM received a token
-- `Matched(time, component, left, right, ctx, offset)` -- PE matched a dyadic pair
+- `Matched(time, component, left, right, act_id, offset, frame_id)` -- PE matched a dyadic pair
 - `Executed(time, component, op, result, bool_out)` -- PE executed an ALU instruction
 - `Emitted(time, component, token)` -- PE emitted an output token
 - `IRAMWritten(time, component, offset, count)` -- PE wrote instructions to IRAM
+- `FrameAllocated(time, component, act_id, frame_id)` -- PE allocated a frame
+- `FrameFreed(time, component, act_id, frame_id)` -- PE freed a frame
+- `FrameSlotWritten(time, component, frame_id, slot, value)` -- PE wrote to a frame slot
+- `TokenRejected(time, component, token, reason)` -- PE rejected a token (e.g., act_id not in tag store)
 - `CellWritten(time, component, addr, old_pres, new_pres)` -- SM cell presence changed
 - `DeferredRead(time, component, addr)` -- SM registered a deferred read
 - `DeferredSatisfied(time, component, addr, data)` -- SM satisfied a deferred read
 - `ResultSent(time, component, token)` -- SM sent a result token back
 
-**Union type:** `SimEvent = TokenReceived | Matched | Executed | Emitted | IRAMWritten | CellWritten | DeferredRead | DeferredSatisfied | ResultSent`
+**Union type:** `SimEvent = TokenReceived | Matched | Executed | Emitted | IRAMWritten | FrameAllocated | FrameFreed | FrameSlotWritten | TokenRejected | CellWritten | DeferredRead | DeferredSatisfied | ResultSent`
 
 **Callback type:** `EventCallback = Callable[[SimEvent], None]`
 

monitor/CLAUDE.md

···
 # OR1 Monitor (monitor/)
 
-Last verified: 2026-02-26
+Last verified: 2026-03-07
 
 ## Purpose
 
···
 
 ## Dependencies
 
-- **Uses**: `cm_inst` (MemOp, Port), `tokens` (Token types), `sm_mod` (Presence), `emu/` (events, types, network), `asm/` (run_pipeline, codegen, ir), `dfgraph/categories` (opcode categorisation for graph JSON)
+- **Uses**: `cm_inst` (MemOp, Port, Instruction, FrameSlotValue), `tokens` (Token types), `sm_mod` (Presence), `emu/` (events, types, network), `asm/` (run_pipeline, codegen, ir), `dfgraph/categories` (opcode categorisation for graph JSON)
 - **Used by**: CLI entry point (`python -m monitor`), test suite
 - **Boundary**: `cm_inst`, `tokens`, `sm_mod`, `emu/`, and `asm/` must NEVER import from `monitor/`
 
···
 - `__init__.py` -- Public API exports
 - `backend.py` -- `SimulationBackend` class with thread lifecycle and command dispatch
 - `commands.py` -- All command and result frozen dataclasses, `SimCommand` union type
-- `snapshot.py` -- `StateSnapshot`, `PESnapshot`, `SMSnapshot`, `SMCellSnapshot`, `capture()`
+- `snapshot.py` -- `StateSnapshot`, `PESnapshot` (frame-based: frames, tag_store, presence, port_store, free_frames), `SMSnapshot`, `SMCellSnapshot`, `capture()`
 - `graph_json.py` -- JSON serialization with execution overlay (extends dfgraph patterns)
 - `server.py` -- `create_app(backend)` FastAPI factory, `ConnectionManager`, WebSocket handler
 - `repl.py` -- `MonitorREPL(cmd.Cmd)` interactive CLI
···
 - The `formatting.NO_COLOUR` global flag must be set before calling format functions (used by tests to get predictable output)
 - Frontend requires `npm install && node build.mjs` in `monitor/frontend/` to produce `dist/bundle.js`
 
-<!-- freshness: 2026-02-26 -->
+<!-- freshness: 2026-03-07 -->