docs: add token format migration design plan

Completed brainstorming session. Design includes:
- 1-bit SM/CM token split replacing old 2-bit type field
- IRAMWriteToken replacing SysToken/CfgToken hierarchy
- SM T0/T1 memory tier split with shared T0 storage
- EXEC opcode for bootstrap and bulk token injection
- 5 implementation phases

CLAUDE.md

···
 
 ## Architecture Contracts
 
+> **Note:** The design documents in `design-notes/` have been updated to
+> reflect the 1-bit SM/CM token split (eliminating SysToken/type-11),
+> IO as memory-mapped SM, bootstrap via SM00 EXEC, and variable 3/5 SM
+> opcode encoding. The emulator and assembler code below still uses the
+> old token hierarchy (SysToken, CfgToken, IOToken). An implementation
+> update is pending. See `design-notes/sm-and-token-format-discussion.md`
+> for the design rationale.
+
 ### Token Hierarchy (tokens.py)
 
 All tokens inherit from `Token(target: int)`. The hierarchy:

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

···
 
 Cycle 1 — trigger token (not-taken side):
   destination: bool_out ? dest2 : dest1
-  format:      ALWAYS inline monadic (type=01, inline=1), regardless
+  format:      ALWAYS monadic inline (prefix 011+10), regardless
                of what the destination's dest_type field says
   data:        none (1-flit token)
   semantics:   controlled by the not-taken destination's not_taken_op field:
···
 ### Token Packing Mux
 
 The packing mux assembles flit 1 (and flit 2 if needed) from the
-destination fields and data. The dest_type selector (2 bits) determines
-the flit layout.
+destination fields and data. The dest_type selector determines the flit
+layout based on the prefix encoding.
 
 ```
-Flit 1 assembly — all four compute token formats:
+Flit 1 assembly — CM token formats by prefix:
 
-  Common:
-    bits [15:14] = type        derived from dest_type
-    bits [13:12] = dest_PE     from IRAM dest field
-    bit  [11]    = mode_flag   derived from dest_type (width or inline bit)
+  Dyadic wide (prefix 00):
+    [0][0][PE:2][offset:5][ctx:4][port:1][gen:2]
 
-  Format-dependent (bits [10:0]):
+  Monadic normal (prefix 010):
+    [0][1][0][PE:2][offset:7][ctx:4]
 
-    Dyadic narrow (type=00, W=0):
-      [offset:5][ctx:4][spare:2]
+  Dyadic narrow (prefix 011+00):
+    [0][1][1][PE:2][00][offset:5][ctx:4]
 
-    Dyadic wide (type=00, W=1):
-      [offset:4][ctx:4][port:1][gen:2]
-
-    Monadic normal (type=01, I=0):
-      [offset:7][ctx:4]
-
-    Monadic inline (type=01, I=1):
-      [offset:4][ctx:4][spare:3]
+  Monadic inline (prefix 011+10):
+    [0][1][1][PE:2][10][offset:4][ctx:4][spare:1]
 
 Flit 2 assembly — format-dependent:
 
-    Dyadic narrow:  [data:8][port:1][gen:2][spare:5]
     Dyadic wide:    [data:16]
     Monadic normal: [data:16]
+    Dyadic narrow:  [data:8][port:1][gen:2][spare:5]
     Inline:         (no flit 2 emitted)
 ```
 
···
 selecting which source bits connect to which flit positions, controlled
 by the dest_type field. Estimate: 4-6 TTL chips.
 
-For SWITCH cycle 1 (not-taken trigger), the mux is forced to inline
-monadic format regardless of the destination's stated dest_type. This
-override is a single AND gate on the dest_type control lines during
-the EMIT_SECOND state when in SWITCH mode.
+For SWITCH cycle 1 (not-taken trigger), the mux is forced to monadic
+inline format (prefix 011+10) regardless of the destination's stated
+dest_type. This override is a single AND gate on the format control lines
+during the EMIT_SECOND state when in SWITCH mode.
 
 ### Source of ctx and gen in Output Tokens
 

design-notes/architecture-overview.md

···
 - `pe-design.md` — PE pipeline, matching store, instruction memory, context slots
 - `sm-design.md` — structure memory interface, operations, banking, address space
 - `network-and-communication.md` — interconnect, routing, clocking, handshaking
-- `io-and-bootstrap.md` — I/O subsystem, bootstrap sequence, type-11 protocol
+- `io-and-bootstrap.md` — IO as memory-mapped SM, bootstrap via SM00 EXEC
 - `design-alternatives.md` — rejected/deferred approaches with rationale
 
 ## Project Goals
···
 This decouples token width from instruction width, and means IRAM width is
 completely independent of bus width.
 
-### Type Field Semantics
+### Top-Level Discriminator: 1-Bit SM/CM Split
+
+```
+BIT[15] = 1:  SM TOKEN — destination is an SM bank. carries a memory
+              operation request (read, write, atomic RMW, bulk ops, etc.).
+BIT[15] = 0:  CM TOKEN — destination is a CM (PE). carries operand data
+              for compute instructions, or IRAM write commands.
+```
+
+IO is memory-mapped into SM address space (typically SM00 at v0). IRAM
+writes are a CM misc-bucket subtype. Bootstrap uses EXEC on SM00, reading
+pre-formed tokens from ROM. Debug/trace can use a reserved SM address
+range or a spare misc-bucket subtype.
+
+### CM Token Prefix Encoding
 
 ```
-Type 00 — DYADIC: destination is a CM. token carries operand for a dyadic
-          (two-input) instruction. requires matching store lookup.
-Type 01 — MONADIC: destination is a CM. token carries operand for a monadic
-          (single-input) instruction. bypasses matching store.
-Type 10 — STRUCTURE: destination is an SM bank. carries a memory operation
-          request (read, write, atomic RMW, etc.).
-Type 11 — SYSTEM: destination is the I/O subsystem, OR carries an extended/
-          config operation. subtype field discriminates:
-          11 + 00: I/O operation (routed to I/O controller)
-          11 + 01: extended address / config write (e.g., remote instruction
-                   memory write, routing table config)
-          11 + 10: reserved (future: debug/trace, DMA)
-          11 + 11: reserved
+BIT[15:14] = 00:  DYADIC WIDE — hot path. 2 flits, 16-bit data.
+                  offset:5 = 32 dyadic slots per context.
+BIT[15:13] = 010: MONADIC NORMAL — 2 flits, 16-bit data.
+                  offset:7 = 128 IRAM slots.
+BIT[15:13] = 011: MISC BUCKET — infrequent CM formats.
+                  sub:2 discriminates:
+                  011+00: DYADIC NARROW (2 flits, 8-bit data)
+                  011+01: IRAM WRITE (2-3 flits, instruction loading)
+                  011+10: MONADIC INLINE (1 flit, trigger only)
+                  011+11: SPARE (reserved)
+```
+
+Two bits determine the fast-path pipeline: bit[15] splits SM/CM (one gate),
+bit[14] splits dyadic-wide from everything else (one gate). The PE can
+start matching store SRAM read the instant flit 1 is latched for dyadic-wide
+tokens. The misc bucket is three gates deep but nothing there is
+latency-critical.
+
+### SM Token Format
+
 ```
+BIT[15] = 1:  SM TOKEN
+  flit 1: [1][SM_id:2][op:variable][addr:variable]              = 16 bits
+  flit 2: [data:16] or [return_routing:16]
 
-Types 00/01 hit CMs only. Type 10 hits SM banks only. Type 11 can hit the
-I/O controller, target PEs (for config writes), or future system
-infrastructure depending on subtype.
+  Variable-width opcode: common ops (READ, WRITE, ALLOC, FREE, CLEAR, EXT)
+  get 3-bit opcode + 10-bit addr (1024 cells). Rare/special ops (atomics,
+  EXEC, SET_PAGE, etc.) get 5-bit opcode + 8-bit payload. One decode gate
+  on op[2:1] discriminates the two tiers. See `sm-design.md` for the full
+  opcode table.
+```
 
-### Flit-Based Packet Formats (Preliminary)
+SM tokens are always bit[15]=1. The network routes them to the SM identified
+by SM_id. IO is memory-mapped into SM address space (typically SM00 at v0).
 
-Standard tokens are 2 flits (32 bits logical). Extended operations
-(type-11) may be 3-4 flits. The number of flits is determined by the
-type/subtype field in flit 1 — routing nodes and receivers can predict
-packet length from the first flit alone.
+### Flit-Based Packet Formats
 
 ```
-Standard compute token (types 00/01, 2 flits):
-  flit 1: [type:2][PE_id:2][...12 bits: addr, ctx, port, gen...]  = 16 bits
+Dyadic wide (prefix 00, 2 flits):
+  flit 1: [0][0][PE:2][offset:5][ctx:4][port:1][gen:2]            = 16 bits
   flit 2: [data:16]                                                = 16 bits
 
-  The 12 bits after type + PE_id encode instruction address, context slot,
-  port (L/R), and generation counter. Exact allocation TBD — key tradeoffs:
-  - Wider instr_addr vs wider ctx_slot vs gen bits
-  - IRAM will be small (hundreds of entries), so a smaller instr_addr
-    field is reasonable
-  - Generation counter is only needed for dyadic tokens (type 00);
-    monadic tokens (type 01) can repurpose those bits
-  - Multi-flit extended compute tokens (3 flits) provide an escape hatch
-    for wider addressing at the cost of one extra flit cycle
+Monadic normal (prefix 010, 2 flits):
+  flit 1: [0][1][0][PE:2][offset:7][ctx:4]                        = 16 bits
+  flit 2: [data:16]                                                = 16 bits
 
-Structure token (type 10, 2 flits):
-  flit 1: [type:2][SM_id:2][operation:3][addr:9]                  = 16 bits
-  flit 2: [data:16] (or return routing for READ operations)        = 16 bits
+Dyadic narrow (prefix 011+00, 2 flits):
+  flit 1: [0][1][1][PE:2][00][offset:5][ctx:4]                    = 16 bits
+  flit 2: [data:8][port:1][gen:2][spare:5]                         = 16 bits
 
-System/extended token (type 11, 3+ flits):
-  flit 1: [type:2][subtype:2][routing:12]                          = 16 bits
-  flit 2: [payload / extended addr]                                = 16 bits
-  flit 3: [payload / data]                                         = 16 bits
-  (flit 4 if needed for full instruction word writes, etc.)
+IRAM write (prefix 011+01, 2-3 flits):
+  flit 1: [0][1][1][PE:2][01][iram_addr:7][flags:2]               = 16 bits
+  flit 2: [instruction_word_low:16]                                = 16 bits
+  (flit 3: [instruction_word_high:8][spare:8] if needed)
+
+Monadic inline (prefix 011+10, 1 flit):
+  flit 1: [0][1][1][PE:2][10][offset:4][ctx:4][spare:1]           = 16 bits
+
+SM standard (prefix 1, 2 flits):
+  flit 1: [1][SM_id:2][op:3-5][addr:8-10]                         = 16 bits
+  flit 2: [data:16] or [return_routing:16]                         = 16 bits
 ```
 
+See `bus-architecture-and-width-decoupling.md` for detailed field analysis
+and `sm-design.md` for SM opcode encoding.
+
 ### Variable-Length Token Summary
 
-| Token Type | Flits | Total Bits | Contents |
-|------------|-------|------------|----------|
-| Standard compute (monadic/dyadic) | 2 | 32 | addr + ctx + port + 16-bit data |
-| Structure operation | 2 | 32 | SM addr + op + 16-bit data or ret routing |
-| System / I/O | 3 | 48 | routing + subtype + payload |
-| Config write (IRAM load) | 3-4 | 48-64 | target PE + IRAM addr + instr word |
-| Extended data (32-bit value) | 3 | 48 | addr + ctx + 32-bit data |
+| Token Type | Prefix | Flits | Data | Offset | Ctx | Port | Gen |
+|------------|--------|-------|------|--------|-----|------|-----|
+| Dyadic wide | 00 | 2 | 16-bit | 5 (32) | 4 | 1 | 2 |
+| Monadic normal | 010 | 2 | 16-bit | 7 (128) | 4 | — | — |
+| Dyadic narrow | 011+00 | 2 | 8-bit | 5 (32) | 4 | 1 | 2 |
+| IRAM write | 011+01 | 2-3 | instr word | 7 (128) | — | — | — |
+| Monadic inline | 011+10 | 1 | none | 4 (16) | 4 | — | — |
+| SM standard | 1 | 2 | 16-bit | 8-10 | — | — | — |
 
 ### Key Design Rationale
 
 - **Opcodes don't travel**: tokens carry destination addresses, not opcodes.
   IRAM is fetched PE-locally after matching. Instruction width is completely
   independent of bus width.
-- **16-bit data in all standard tokens**: every standard compute token
-  carries a full 16-bit data word in flit 2, regardless of monadic/dyadic
-  type. The old 14-bit dyadic data limitation is eliminated.
-- **Flit 1 is self-describing**: type + PE_id (or SM_id) enable routing
-  after receiving just one flit. Routing nodes inspect flit 1 only;
-  subsequent flits follow the same path.
-- **Variable-length is the escape hatch**: the common case (2 flits) is
-  fast. Extended operations and wider addressing pay extra flits only
-  when needed.
+- **1-bit top-level split**: bit[15] discriminates SM from CM traffic. One
+  gate. The network routes on bit[15] + the 2-bit destination ID (PE_id or
+  SM_id). Everything below that is endpoint-decoded.
+- **Hot path decode is shallow**: dyadic wide (the dominant format) is
+  identified by two bits (bit[15]=0, bit[14]=0). The PE can begin matching
+  store SRAM read immediately on flit 1 latch.
+- **IRAM writes are CM-local**: the PE manages its own instruction memory
+  via the misc-bucket IRAM write format. No separate system token type.
 - **Generation counter only on dyadic tokens**: prevents ABA problem when
-  context slots are reused. Monadic and structure tokens don't need it.
+  context slots are reused. Monadic and SM tokens don't need it.
 - **Width domains are independent**: bus width (16-bit), token format
   (variable flit count), IRAM width (32-48 bits), and PE pipeline width
   (wider, decomposed) are each sized for their own constraints. See
···
 - Instruction memory (IM / IRAM): stores dataflow program (function bodies)
   - Width decoupled from bus: 32-48 bits, sized for opcode + destination
     encoding (see `bus-architecture-and-width-decoupling.md`)
-  - **Runtime-writable** via type-11 config packets from the network
+  - **Runtime-writable** via IRAM write tokens (prefix `011+01`)
   - Write from network stalls the pipeline (acceptable for config operations)
   - Enables runtime reprogramming and eliminates need for separate config bus
 - Operand memory (OM) / matching store: buffers arriving operands, performs
   matching. Entries are 16-bit data + 1-bit presence per slot.
-- Receives tokens from CN (types 00/01) and DN (SM results repackaged as
-  type 00/01), produces tokens to CN and AN
+- Receives CM tokens (bit[15]=0) from CN and DN (SM results repackaged as
+  CM tokens), produces tokens to CN and AN
 - Contains the bump allocator, throttle, and generation counter logic
 - Each PE has a unique ID, set via EEPROM (instruction decoder doubles as
   ID store) or DIP switches during prototyping
 - See `pe-design.md` for pipeline details
 
-### SM (Structure Memory) — data storage and structure operations
+### SM (Structure Memory) — data storage, structure operations, and IO
 - Banked data memory (cells) for arrays, lists, heap data
 - Embedded functional units for structure operations (read, write, atomic
-  RMW, etc.)
-- Receives operation requests via AN (type 10), returns results via DN
-  (repackaged as type 00/01 tokens)
+  RMW, bulk ops via EXEC/ITERATE/COPY_RANGE)
+- Receives operation requests via AN (bit[15]=1 tokens), returns results
+  via DN (repackaged as CM tokens)
 - Operates asynchronously from CMs — split-phase memory access
-- Pure data storage — no I/O mapping (I/O lives in the type-11 subsystem)
-- See `sm-design.md` for interface and banking details
+- **IO is memory-mapped into SM address space.** An SM (typically SM00 at
+  v0) maps IO devices into its address range. I-structure semantics provide
+  natural interrupt-free IO: a READ from an IO device that has no data
+  defers until data arrives.
+- **SM00 has bootstrap responsibility:** wired to the system reset signal,
+  it calls EXEC on a predetermined ROM address to load the system. At
+  runtime, SM00 behaves as a standard SM; only the reset-vector wiring is
+  special. See `sm-design.md` for details.
+- **Memory tiers:** SM address space supports regions with different
+  semantics — tier 0 (raw, no presence bits), tier 1 (I-structure), and
+  tier 2 (wide/bulk with is_wide tag). Tier selection is by address range.
+- See `sm-design.md` for interface, banking, and tier details
 
-### I/O Controller — peripheral interface
-- Fixed-function device on the network, NOT a full PE
-- Receives type-11 subtype-00 packets, interprets as I/O commands
-- Returns results as type 00/01 tokens to the requesting CM
-- Can spontaneously emit tokens (unsolicited I/O: UART RX, interrupt
-  equivalent) — the only network participant that generates tokens
-  without receiving one first
-- Also handles type-11 subtype-01 during bootstrap (reading from UART/flash,
-  formatting config writes to load programs into PEs)
-- See `io-and-bootstrap.md` for design details
-
-### Three Logical Interconnects (shared physical bus for v0)
+### Two Logical Interconnects (shared physical bus for v0)
 
 ```
-CN (Communication Network): CM <-> CM, types 00/01
-AN (Arbitration Network):   CM  -> SM, type 10
-DN (Distribution Network):  SM  -> CM, type 10 results repackaged as 00/01
-System channel:             any <-> I/O controller, type 11
+CN (Communication Network): CM <-> CM, bit[15]=0
+AN (Arbitration Network):   CM  -> SM, bit[15]=1
+DN (Distribution Network):  SM  -> CM, SM results repackaged as bit[15]=0
 ```
 
-For v0 (4 PEs + 1-2 SMs + I/O controller), all traffic shares a single
-physical 16-bit bus with type-based routing. Routing nodes inspect flit 1
-(type field + destination ID) and forward the entire multi-flit packet to
-the appropriate destination. Multiple packets can be in flight
+For v0 (4 PEs + 2-4 SMs), all traffic shares a single physical 16-bit bus
+with bit[15]-based routing. Routing nodes inspect flit 1 (bit[15] +
+destination ID in bits[14:13] or [13:12]) and forward the entire multi-flit
+packet to the appropriate destination. Multiple packets can be in flight
 simultaneously if the bus is pipelined with latches at each stage.
 
 The AN/DN can be split onto separate physical paths later if SM access
-contention becomes a bottleneck. The type-field-based routing means this
+contention becomes a bottleneck. The bit[15]-based routing means this
 is a topology change, not a protocol change — no module interfaces need
 to change.
 
···
 |-----------|------------|
 | 4x PE logic | 20-32K |
 | Routing network (4 PEs) | 2-3K |
-| I/O controller | ~1-2K |
+| SM bootstrap/EXEC sequencer | ~1-2K |
 | **Total logic** | **~25-35K** |
 | SRAM chips (instruction mem, matching stores, token queues) | 8-16 chips |
 
-Bootstrap is handled by the I/O controller via type-11 config writes,
-or by an external microcontroller during early prototyping. No dedicated
-bootstrap hardware in the architecture.
+Bootstrap is handled by SM00's EXEC sequencer reading pre-formed tokens
+from ROM, or by an external microcontroller during early prototyping.
 
 ## IPC / Performance Expectations
 
···
 - With 4 PEs and single-cycle matching (common case), peak is 4 ops/clock
 - Realistic sustained throughput depends on:
   - Network crossing frequency (adds routing latency)
-  - Hash path hits vs direct index (matching latency)
+  - Direct index matching latency (single-cycle common case)
   - Available parallelism in the program
   - Network contention (shared bus at v0 scale)
 - Parallel workloads (matrix multiply, FFT): near peak
···
 - Test with microcontroller injecting tokens, verify matching + execution
 
 ### Phase 2: CM + SM pair
-- Connect via shared bus with type routing
-- Load a program using microcontroller (external, via type-11 config writes
+- Connect via shared bus with bit[15]-based routing
+- Load a program using microcontroller (external, via IRAM write tokens
   or direct SRAM programming)
 - Execute a dataflow graph that uses structure memory
 - First real program: fibonacci, small FFT, or similar
···
 - Demonstrate actual parallel execution speedup
 
 ### Phase 4: System
-- Expand to 4 CMs + 1-2 SMs
-- I/O controller (type-11 subsystem) with UART
-- Bootstrap via I/O controller reading from flash/serial
-- ISR support (compiler-assigned PE with interrupt token injection from
-  I/O controller)
+- Expand to 4 CMs + 2-4 SMs
+- SM00 bootstrap via EXEC from ROM
+- IO memory-mapped into SM00 address space (UART, etc.)
+- ISR equivalent via I-structure semantics: READ from IO device defers
+  until data arrives, triggering the receiving node in the dataflow graph
 - Performance benchmarking vs period-equivalent CPUs
 
 ## Open Questions / Next Steps
 
-1. **SM internal design** — banking scheme, operation set,
-   interface protocol (partially specified, see `sm-design.md`)
+1. **SM internal design** — banking scheme, bulk op sequencer, tier
+   boundary configuration, wide pointer cell format (partially specified,
+   see `sm-design.md`)
 2. **Context slot count per CM** — 4 bits = 16 slots vs 5 bits = 32 slots;
-   drives flit-1 bit allocation tradeoffs
-3. **Flit-1 bit allocation** — how to divide the 12 available bits (after
-   type + PE_id) among instr_addr, ctx_slot, port, and gen. Smaller
-   instr_addr is reasonable given small IRAM; gen bits only needed for
-   dyadic. Multi-flit extended tokens provide escape hatch for wider
-   addressing. See `bus-architecture-and-width-decoupling.md` open questions.
-4. **Instruction encoding** — operation set, format, IRAM width (32 or 48
+   the new dyadic wide format gives 5-bit offset with 4-bit ctx. See
+   `bus-architecture-and-width-decoupling.md` for field allocation analysis.
+3. **Instruction encoding** — operation set, format, IRAM width (32 or 48
    bits). Decoupled from bus width, driven by opcode + destination fields.
    > **Partially resolved:** the emulator and assembler use Python IntEnum
    > values as opcode placeholders. These do NOT represent final hardware
    > bit encodings — a hardware encoding pass is still needed. The 5-bit
    > opcode table in `alu-and-output-design.md` is a preliminary draft.
-5. **I/O controller internal design** — state machine, UART bridge,
-   unsolicited token generation, flit-based I/O token format
-6. ~~**Compiler / assembler**~~ — **Partially Resolved.** The `asm/` package
+4. **IO address space allocation** — which SM_id is reserved for IO? How
+   much of SM00's address space is mapped to IO vs general-purpose storage?
+   SM00 is special only at boot for now; further specialisation deferred
+   until profiling shows the standard opcodes are insufficient.
+5. ~~**Compiler / assembler**~~ — **Partially Resolved.** The `asm/` package
    implements a 6-stage assembler pipeline (parse → lower → resolve →
    place → allocate → codegen). Produces PEConfig/SMConfig + seed tokens
    or a bootstrap token stream. See `assembler-architecture.md` for architecture.

design-notes/bus-architecture-and-width-decoupling.md

···
 enabling routing nodes to make forwarding decisions after receiving only
 the first flit.
 
-Tokens are 1-2 flits for compute traffic, 2 flits for structure operations,
-and 3-4 flits for system/config operations. The number of flits is
-determined by the type field (and, for compute tokens, the subtype/mode
-bits) in flit 1 — routing nodes and receivers can predict packet length
-from the first flit alone.
+Tokens are 1-2 flits for compute traffic, 2 flits for SM operations, and
+2-3 flits for IRAM writes. The number of flits is determined by the prefix
+bits in flit 1 — routing nodes and receivers can predict packet length from
+the first flit alone.
 
 ### Impact on Throughput
 
···
   destination, no instruction metadata.
 - **IRAM width is completely independent of bus width.** Instruction words
   are fetched from PE-local SRAM, never serialised onto the external bus
-  (except during program loading via type-11 config writes, which is a
+  (except during program loading via IRAM write tokens, which is a
   slow-path operation).
 - **The opcode is an implementation detail of the PE.** It gets loaded
   into IRAM during program initialisation and sits there until replaced.
···
 
 Loading a program means:
 
-1. Write IRAM entries via type-11 config packets (opcode + destinations
-   per slot, multi-flit — 3 or 4 flits depending on instruction width)
+1. Write IRAM entries via IRAM write tokens (prefix 011+01), 2-3 flits
+   depending on instruction width
 2. Inject initial tokens (constants, inputs) via I/O
 3. The graph executes itself
 
-Replacing instructions at runtime is a type-11 config write to the target
-PE's IRAM. See **IRAM Valid-Bit Protection** below for safe swap protocol.
+Replacing instructions at runtime is an IRAM write token to the target
+PE. See **IRAM Valid-Bit Protection** below for safe swap protocol.
 
 ---
 
-## Flit-1 Bit Allocation: Routing vs PE Decode
+## Flit-1 Bit Allocation: Routing vs Endpoint Decode
 
 Flit 1 is 16 bits. The hard routing requirement is minimal:
 
-**Network routing nodes** inspect only `type:2` + `PE_id:2` (or `SM_id:2`
-for structure tokens). These 4 bits determine where the flit goes. The
-remaining 12 bits are opaque payload — the network forwards them blindly.
+**Network routing nodes** inspect only `bit[15]` (SM/CM split) plus the
+2-bit destination ID. These 3 bits determine where the flit goes. The
+remaining bits are opaque payload — the network forwards them blindly.
 
-**The destination PE** decodes the full 16 bits to determine token format,
-how many further flits to clock in, and how to begin pipeline work.
+**The destination endpoint** (PE or SM) decodes the full 16 bits to
+determine token format, how many further flits to clock in, and how to
+begin processing.
 
 ### Routing Field
 
 ```
-Flit 1 bits [15:14] — type:2
-  0x = compute token → route to CM identified by PE_id in bits [13:12]
-  10 = structure     → route to SM identified by SM_id in bits [13:12]
-  11 = system        → route by subtype in bits [13:12]
+Flit 1 bit [15] — SM/CM discriminator:
+  0 = CM token → route to PE identified by PE_id
+  1 = SM token → route to SM identified by SM_id
+
+For CM tokens (bit[15]=0):
+  bits [13:12] = PE_id for dyadic wide (prefix 00)
+  bits [12:11] = PE_id for monadic normal and misc bucket (prefix 01x)
 
-Flit 1 bits [13:12] — destination ID:2
-  For types 0x: PE_id (0-3, expandable via hierarchical routing)
-  For type 10:  SM_id (0-3)
-  For type 11:  subtype (I/O, config, reserved, reserved)
+For SM tokens (bit[15]=1):
+  bits [14:13] = SM_id (0-3)
 ```
 
-Everything below bit 12 is destination-decoded, not network-decoded.
+Everything below the destination ID is endpoint-decoded, not
+network-decoded. The routing node's job is to extract the destination ID
+from the appropriate bit position based on bit[15].
 
 ---
 
-## Compute Token Formats (types 00 and 01)
-
-The type field's LSB distinguishes dyadic (00) from monadic (01). Both
-route identically (network only looks at the MSB to see `0x` = compute).
-The PE decodes type[0] to determine matching behaviour and flit-2 layout.
+## CM Token Formats (bit[15]=0)
 
-Bit [11] is a **mode flag** whose interpretation depends on the type:
-
-- For dyadic (00): **width flag** — selects 8-bit or 16-bit data mode
-- For monadic (01): **inline flag** — selects 1-flit or 2-flit format
-
-This gives four compute token formats from the 2-bit type + 1-bit mode:
+The prefix encoding uses variable-length bit patterns to give the hot path
+(dyadic wide) the shallowest decode and the most generous field allocation.
 
-### Format 1: Dyadic Narrow (type=00, width=0) — 2 flits, 8-bit data
+### Dyadic Wide (prefix 00) — 2 flits, 16-bit data, HOT PATH
 
 ```
-Flit 1: [type:2=00][PE:2][W:1=0][offset:5][ctx:4][spare:2]        = 16 bits
-Flit 2: [data:8][port:1][gen:2][spare:5]                           = 16 bits
+Flit 1: [0][0][PE:2][offset:5][ctx:4][port:1][gen:2]              = 16 bits
+Flit 2: [data:16]                                                  = 16 bits
 ```
 
-8-bit data mode. Port and generation counter ride in flit 2 alongside the
-narrow data word, freeing flit 1 for a wider offset field and 2 spare bits.
+The dominant token format. Port and gen live in flit 1 alongside routing.
 
 - **offset:5** → 32 dyadic instruction slots per context (matching store
   address = `[ctx:4][offset:5]` = 9 bits = 512 cells)
 - **ctx:4** → 16 concurrent activations per PE
-- **port:1** → L/R operand discriminator (in flit 2)
-- **gen:2** → generation counter for ABA protection (in flit 2)
-- **spare:2** (flit 1) — reserved for future use (epoch, extended
-  addressing flag, multicast, etc.)
-- **spare:5** (flit 2) — reserved. candidates: extended context bits,
-  fragment tag, priority, debug flags
+- **port:1** → L/R operand discriminator
+- **gen:2** → generation counter for ABA protection
+- Full 16-bit data in flit 2
 
-The PE begins the matching store SRAM read on `[ctx:4][offset:5]` as soon
-as flit 1 is latched (bus cycle 0). Port and gen arrive in flit 2 (bus
-cycle 1) and are available by the time the SRAM read completes.
+The PE begins the matching store SRAM read on `[ctx:4][offset:5]` the
+instant flit 1 is latched. Decode: bit[15]=0 AND bit[14]=0 — two gates.
 
-### Format 2: Dyadic Wide (type=00, width=1) — 2 flits, 16-bit data
+### Monadic Normal (prefix 010) — 2 flits, 16-bit data
 
 ```
-Flit 1: [type:2=00][PE:2][W:1=1][offset:4][ctx:4][port:1][gen:2]  = 16 bits
+Flit 1: [0][1][0][PE:2][offset:7][ctx:4]                          = 16 bits
 Flit 2: [data:16]                                                  = 16 bits
 ```
 
-16-bit data mode. Port and gen must live in flit 1, consuming bits that
-reduce the offset field.
+Standard monadic token. No matching store access — the arriving token IS
+the sole input. No port, no gen needed.
 
-- **offset:4** → 16 dyadic instruction slots per context (matching store
-  address = `[ctx:4][offset:4]` = 8 bits = 256 cells)
+- **offset:7** → 128 IRAM entries addressable by monadic tokens
 - **ctx:4** → 16 concurrent activations
 - Full 16-bit data in flit 2
 
-Tighter than narrow mode — 16 dyadic entries per chunk vs 32. Adequate
-for most function fragments given instruction deduplication (see above).
-Programs needing more dyadic instructions per chunk split across PEs.
+Decode adds one more gate at bit[13].
+
+### Misc Bucket (prefix 011) — infrequent formats
+
+The 2-bit sub field after the 011 prefix discriminates four formats:
 
-### Format 3: Monadic Normal (type=01, inline=0) — 2 flits, 16-bit data
+**Dyadic Narrow (sub=00) — 2 flits, 8-bit data:**
 
 ```
-Flit 1: [type:2=01][PE:2][I:1=0][offset:7][ctx:4]                 = 16 bits
-Flit 2: [data:16]                                                  = 16 bits
+Flit 1: [0][1][1][PE:2][00][offset:5][ctx:4]                      = 16 bits
+Flit 2: [data:8][port:1][gen:2][spare:5]                           = 16 bits
 ```
 
-Standard monadic token. No matching store access (monadic instructions
-have one input — the arriving token IS the input). No port, no gen needed.
+8-bit data mode. Port and gen ride in flit 2 alongside the narrow data,
+freeing flit 1 for a wider offset field.
 
-- **offset:7** → 128 IRAM entries addressable by monadic tokens
-- **ctx:4** → 16 concurrent activations (same context slot space)
-- Full 16-bit data in flit 2
+- **offset:5** → 32 dyadic slots per context (same as dyadic wide)
+- **spare:5** (flit 2) — reserved: extended context, fragment tag, etc.
 
-The 7-bit offset gives monadic tokens access to the full IRAM address
-space (128 entries). Dyadic instructions occupy the low offsets (0-15 or
-0-31 depending on width mode); monadic instructions can be placed anywhere
-in 0-127. The compiler controls layout.
+**IRAM Write (sub=01) — 2-3 flits, instruction loading:**
+
+```
+Flit 1: [0][1][1][PE:2][01][iram_addr:7][flags:2]                 = 16 bits
+Flit 2: [instruction_word_low:16]                                  = 16 bits
+(Flit 3: [instruction_word_high:8][spare:8] if IRAM > 16 bits)
+```
+
+Loads instruction words into PE IRAM. No ctx/port/gen needed — the PE
+manages its own instruction memory. 7-bit address = 128 IRAM slots, full
+coverage. The 2-bit flags field can signal 2-flit vs 3-flit mode and
+other load control (e.g., page valid-bit set/clear).
 
-### Format 4: Monadic Inline (type=01, inline=1) — 1 flit, no data
+**Monadic Inline (sub=10) — 1 flit, trigger only:**
 
 ```
-Flit 1: [type:2=01][PE:2][I:1=1][offset:4][ctx:4][spare:3]        = 16 bits
+Flit 1: [0][1][1][PE:2][10][offset:4][ctx:4][spare:1]             = 16 bits
 No flit 2.
 ```
 
-Single-flit token. Carries no data payload — it is a **trigger**. The
+Single-flit token. Carries no data payload — it is a trigger. The
 instruction's IRAM word supplies any needed constant via its immediate
-field. The token's purpose is to signal "this input is ready" to fire a
-monadic instruction.
+field.
 
-- **offset:4** → 16 IRAM entries addressable by inline monadic tokens
-- **ctx:4** → 16 concurrent activations
-- **spare:3** — reserved. candidates: small immediate (0-7), flags,
-  extended context, priority
+- **offset:4** → 16 IRAM entries addressable by inline tokens
+- **spare:1** — reserved
 
 Use cases: synchronisation signals, barrier tokens, loop iteration
-triggers, boolean control flow edges where the value is implicit in the
-graph structure. These are common in dataflow programs and currently cost
-2 bus cycles to deliver what is effectively 0-1 bits of useful data.
-Inline monadic halves the bus cost.
+triggers, SWITCH not-taken triggers.
+
+**Spare (sub=11) — reserved:**
+
+Candidates: extended monadic with wider offset, broadcast/multicast,
+debug/trace injection.
+
+### Monadic Offset Relative Addressing
+
+Dyadic instructions pack into the lowest IRAM offsets (0-31). Monadic
+tokens never target those slots. Making monadic offsets **relative to the
+dyadic ceiling** avoids wasting encodings:
+
+```
+dyadic ceiling = 32 → monadic base = 32
+  7-bit relative offset → addresses 32-159 (128 monadic slots)
+```
+
+Hardware cost: since the dyadic ceiling is a power of 2 (32), the base
+can be OR'd onto the high address bits. One gate plus a config bit.
+
+SC blocks need contiguous IRAM space that does not respect the
+dyadic-below-monadic packing rule. The compiler packs SC blocks into a
+separate IRAM region, addressed via a base register set on entering SC
+mode.
 
-The PE knows to expect no flit 2 because `type=01, inline=1` is decoded
-on flit 1 arrival. The bus is free for the next token immediately.
+### CM Token Summary
 
-### Compute Token Summary
+| Format | Prefix | Flits | Data | Offset | Ctx | Port | Gen |
+|--------|--------|-------|------|--------|-----|------|-----|
+| Dyadic wide | 00 | 2 | 16-bit | 5 (32) | 4 | flit1 | flit1 |
+| Monadic normal | 010 | 2 | 16-bit | 7 (128) | 4 | — | — |
+| Dyadic narrow | 011+00 | 2 | 8-bit | 5 (32) | 4 | flit2 | flit2 |
+| IRAM write | 011+01 | 2-3 | instr word | 7 (128) | — | — | — |
+| Monadic inline | 011+10 | 1 | none | 4 (16) | 4 | — | — |
+| (spare) | 011+11 | ? | ? | ? | ? | ? | ? |
 
-| Format | Type | Mode | Flits | Data | Offset | Ctx | Port | Gen |
-|--------|------|------|-------|------|--------|-----|------|-----|
-| Dyadic narrow | 00 | W=0 | 2 | 8-bit | 5 (32) | 4 | flit2 | flit2 |
-| Dyadic wide | 00 | W=1 | 2 | 16-bit | 4 (16) | 4 | flit1 | flit1 |
-| Monadic normal | 01 | I=0 | 2 | 16-bit | 7 (128) | 4 | — | — |
-| Monadic inline | 01 | I=1 | 1 | none | 4 (16) | 4 | — | — |
+### Hot Path Decode Summary
 
-All four formats share `[type:2][PE:2]` at the top and `[ctx:4]` in the
-same bit position, simplifying PE input decode. The mode flag at bit [11]
-tells the PE everything it needs to know about flit count and field layout.
+- bit[15] splits SM/CM: one gate
+- bit[14] splits dyadic-wide from everything else: one gate
+- bit[13] splits monadic normal from misc bucket: one more gate
+- the misc bucket is three gates deep, but nothing there is
+  latency-critical
 
 ### Spare Bits and Future Use
 
 The spare bits are explicitly reserved, not accidentally unused:
 
-- **Dyadic narrow flit 1, spare:2** — future candidates: IRAM page epoch
-  (for identity checking beyond the valid-bit gate), extended addressing
-  flag (signals a 3-flit token with wider address in flit 3), or multicast.
 - **Dyadic narrow flit 2, spare:5** — future candidates: extended context
   (up to 9 bits total ctx), fragment tag, debug/trace ID, priority level.
-- **Monadic inline spare:3** — future candidates: small immediate value
-  (0-7 for booleans, enum tags, iteration counters), extended context bits,
-  or an "extended interpretation" flag that changes the meaning of the
-  remaining bits for special-purpose tokens.
+- **Monadic inline spare:1** — future candidate: extended context bit or
+  flag for extended interpretation.
+- **Misc bucket sub=11** — entire format reserved for future use.
 
 The spare bits provide escape hatches for architectural evolution without
 changing the base format. v0 should treat them as must-be-zero on
···
 
 ---
 
-## Structure Token Format (type 10) — unchanged
+## SM Token Format (bit[15]=1)
 
 ```
-Structure token (2 flits):
-  flit 1: [type:2=10][SM_id:2][operation:3][addr:9]               = 16 bits
-  flit 2: [data:16] (WRITE) or [return routing:16] (READ variants) = 16 bits
+SM token (2 flits, standard):
+  flit 1: [1][SM_id:2][op:3-5][addr:8-10]                         = 16 bits
+  flit 2: [data:16] or [return_routing:16]                         = 16 bits
 ```
 
-See `sm-design.md` for operation set, extended addressing, and CAS handling.
+15 bits available after the SM discriminator. SM_id (2 bits) selects one of
+4 SMs. The remaining 13 bits are split between opcode and address using
+variable-width encoding:
 
-3-flit extended addressing mode for wide address spaces:
 ```
-  flit 1: [type:2=10][SM_id:2][op:3][flags:9]                     = 16 bits
-  flit 2: [extended_addr:16]                                       = 16 bits
-  flit 3: [data:16] or [return routing:16]                         = 16 bits
+op[2:1] != 11:  3-bit opcode, 10-bit addr (1024 cells)
+  READ, WRITE, ALLOC, FREE, CLEAR, EXT
+
+op[2:1] == 11:  extends to 5-bit opcode, 8-bit payload (256 cells or inline data)
+  READ_INC, READ_DEC, CAS, RAW_READ, EXEC, SET_PAGE, WRITE_IMM, (spare)
 ```
 
----
+One decode gate on op[2:1] discriminates the two tiers.
 
-## System Token Format (type 11) — 3+ flits
+See `sm-design.md` for the full opcode table, extended addressing, and
+CAS handling.
 
-```
-System/extended token (3+ flits):
-  flit 1: [type:2=11][subtype:2][routing:12]                       = 16 bits
-  flit 2: [payload / extended addr]                                = 16 bits
-  flit 3: [payload / data]                                         = 16 bits
-  (flit 4 if needed for full instruction word writes, etc.)
+**Return routing in flit 2:** for READ and other result-producing ops,
+flit 2 carries a **pre-formed CM token template**. The SM's result
+formatter latches the template, prepends it as flit 1, and appends the
+read data as flit 2. No bit-shuffling — the requesting CM does all the
+format work upfront. This means SM results can land directly in a matching
+store slot as one operand of a dyadic instruction without an intermediate
+forwarding step.
 
-Subtypes:
-  11 + 00: I/O operation (routed to I/O controller)
-  11 + 01: config write (IRAM load, routing table, etc.)
-  11 + 10: reserved (debug/trace, DMA)
-  11 + 11: reserved
-```
-
-Config writes (subtype 01) include IRAM loading. The target PE recognises
-its own address in the routing field and activates the instruction bus for
-writing. This shares the same input FIFO as compute tokens — see IRAM
-Valid-Bit Protection below.
+**IO is memory-mapped SM:** IO devices are mapped into SM address space
+(typically SM00 at v0). IO operations use the standard SM token format.
+I-structure semantics provide natural interrupt-free IO — a READ from an
+IO device that has no data defers until data arrives.
 
 ---
 
 ## Variable-Length Token Summary
 
-| Token Type | Flits | Total Bits | Contents |
-|------------|-------|------------|----------|
-| Monadic inline (trigger) | 1 | 16 | addr + ctx only, no data |
-| Dyadic narrow (8-bit data) | 2 | 32 | addr + ctx + 8-bit data + port + gen |
-| Dyadic wide (16-bit data) | 2 | 32 | addr + ctx + port + gen + 16-bit data |
-| Monadic normal (16-bit data) | 2 | 32 | addr + ctx + 16-bit data |
-| Structure operation | 2 | 32 | SM addr + op + 16-bit data or ret routing |
-| Structure extended addr | 3 | 48 | SM addr + op + wide addr + data |
-| System / I/O | 3 | 48 | routing + subtype + payload |
-| Config write (IRAM load) | 3-4 | 48-64 | target PE + IRAM addr + instruction word |
+| Token Type | Prefix | Flits | Total Bits | Contents |
+|------------|--------|-------|------------|----------|
+| Dyadic wide | 00 | 2 | 32 | offset + ctx + port + gen + 16-bit data |
+| Monadic normal | 010 | 2 | 32 | offset + ctx + 16-bit data |
+| Dyadic narrow | 011+00 | 2 | 32 | offset + ctx + 8-bit data + port + gen |
+| IRAM write | 011+01 | 2-3 | 32-48 | iram_addr + instruction word |
+| Monadic inline | 011+10 | 1 | 16 | offset + ctx only, no data |
+| SM standard | 1 | 2 | 32 | SM_id + op + addr + 16-bit data or ret routing |
 
 The common case is 2 flits. Inline monadic (1 flit) is the fast path for
-control-flow tokens. System and config operations pay 3-4 flits but are
-infrequent during execution.
+control-flow tokens. IRAM writes pay 2-3 flits but are infrequent during
+execution.
 
 ---
 
···
 
 ### The Problem
 
-IRAM is written via type-11 config packets that share the PE's input FIFO
+IRAM is written via IRAM write tokens (prefix 011+01) that share the PE's input FIFO
 with compute tokens. When IRAM contents are replaced at runtime (swapping
 function fragments in and out), tokens in flight may target IRAM addresses
 that have been or are being overwritten. Because tokens do not carry
···
 sequence is naturally ordered:
 
 ```
-1. Loader sends drain signal (implementation TBD — could be a type-11
-   "quiesce" subop, or the PE back-pressures via handshake/ready signal)
+1. Loader sends drain signal (implementation TBD — could be an IRAM write
+   "quiesce" flag, or the PE back-pressures via handshake/ready signal)
 2. PE processes remaining compute tokens in FIFO (natural drain)
-3. Type-11 ld_inst config write arrives in FIFO:
+3. IRAM write token (prefix 011+01) arrives in FIFO:
    a. PE clears valid bit for target page
    b. PE writes instruction word to IRAM at specified address
    c. If more ld_inst packets follow (burst), keep writing
-4. Load-complete marker arrives (type-11 subop or last-write flag):
+4. Load-complete marker arrives (IRAM write with load-complete flag):
    a. PE sets valid bit for target page
    b. PE resumes accepting compute tokens for that page
 ```
···
 is after the load completes. Rejected tokens are therefore late arrivals
 from the old epoch — work that is being abandoned.
 
+**Presence-bit optimisation:** the matching store's presence bitmap can
+be checked before step 1 to determine if any tokens are pending for the
+target page. If all presence bits for slots in that page are clear, the
+drain step can be skipped entirely — no tokens are waiting for those
+instructions. This enables targeted IRAM replacement without stalling
+the entire PE. See `sm-design.md` "Presence-Bit Guided IRAM Writes".
+
 ### Rejection Policy
 
 **v0: discard silently + diagnostic.** Late-arriving tokens targeting an
···
 No token format changes, no NAK generation, no recirculation. If the flag
 lights up, something is wrong with the drain timing.
 
-**Future: NAK response.** The PE could form a type-11 NAK token from the
+**Future: NAK response.** The PE could form a NAK token from the
 rejected compute token and emit it to a coordinator. The output serialiser
 already exists (stage 4 forms tokens); a bypass path from stage 2 to the
 output would enable this. Estimated cost: a mux and some control logic,
···
 - Width: 2-3 parallel 8-bit SRAM chips for 16-48 bit instruction words,
   all addressed by the same address lines
 - Read in one pipeline stage (instruction fetch, after matching completes)
-- Written only during program loading (type-11 config) with valid-bit
+- Written only during program loading (IRAM write tokens) with valid-bit
   protection
 
 Because IRAM read is a single pipeline stage using parallel SRAM chips,
···
 ## Matching Store: Addressing and Layout
 
 The matching store is indexed by `[ctx_slot : offset]` where both fields
-come from flit 1. The offset width depends on the token's width mode:
+come from flit 1. Both dyadic formats now have 5-bit offset:
 
 | Token format | ctx bits | offset bits | Match store cells | SRAM address bits |
 |--------------|----------|-------------|-------------------|-------------------|
-| Dyadic narrow (W=0) | 4 | 5 | 512 | 9 |
-| Dyadic wide (W=1) | 4 | 4 | 256 | 8 |
+| Dyadic wide (prefix 00) | 4 | 5 | 512 | 9 |
+| Dyadic narrow (prefix 011+00) | 4 | 5 | 512 | 9 |
 
-Both configurations fit in a single SRAM chip. If the PE only supports
-one width mode (configuration-time choice), the matching store address
-generation is just wire concatenation with the unused address line tied
-low. If both modes are supported simultaneously, the W bit from flit 1
-gates the top address line.
+Both formats address the same 512-cell matching store. Address generation
+is simple wire concatenation: `[ctx:4][offset:5]`.
 
 ### Entry Format
 
···
   [presence:1][data:8 or 16] = 9 or 17 bits per entry
 ```
 
-**8-bit data mode:** matching store entries are 8-bit data + presence.
-Physically: one 8-bit-wide SRAM chip for data, separate presence bitmap
-in a register file. 512 entries x 8 bits = 512 bytes = one standard SRAM.
-
-**16-bit data mode:** matching store entries are 16-bit data + presence.
-Physically: one 16-bit-wide SRAM (or two 8-bit SRAMs) for data, separate
-presence bitmap. 256 entries x 16 bits = 512 bytes = one standard SRAM.
-
-Both modes use the same physical SRAM capacity. The tradeoff is data
-width vs entry count, controlled by token format.
+Matching store entries are 16-bit data + presence. Physically: one
+16-bit-wide SRAM (or two 8-bit SRAMs) for data, separate presence bitmap.
+512 entries x 16 bits = 1024 bytes.
 
 Metadata (presence bitmap, port indicators, generation counters) stored
 separately in dedicated fast-access registers:
···
    for control logic, 16-bit PE for arithmetic). Hardwired is simpler.
 4. **Inline monadic spare bits** — small immediate (0-7) vs reserved?
    Immediate is useful for boolean/enum signals but adds decode logic.
-5. **SM result token width** — does SM always return 16-bit (wide) results?
-   Or can it return 8-bit (narrow) based on the request? Affects return
-   routing format in SM request tokens.
+5. **SM result token format** — SM results use the pre-formed token template
+   from the request's flit 2 as their flit 1. The template can encode any
+   CM format whose routing fits in 16 bits (dyadic wide, monadic normal,
+   monadic inline). SM does not parse the template.
 6. **Network handling of 1-flit packets** — routing nodes need to know
    packet length from flit 1 to avoid waiting for a flit 2 that won't
-   come. The `type=01, bit[11]=1` decode is straightforward but must be
+   come. The `prefix=011, sub=10` (monadic inline) decode must be
    implemented in every routing node, not just destination PEs.
 7. **Valid-bit page granularity** — 4 pages of 32 entries, or 8 pages of
    16? Finer granularity allows partial IRAM updates without invalidating
    unrelated code, at the cost of more valid-bit storage (still trivial).
-8. **Drain protocol specifics** — quiesce via type-11 subop, or via
+8. **Drain protocol specifics** — quiesce via IRAM write flags, or via
    handshake backpressure, or both? Needs to be defined before IRAM
    swap can be implemented.

design-notes/historical-plausibility.md

···
+# Historical Plausibility: A Dataflow Microcomputer circa 1979–1984
+
+Research notes on transistor budgets, memory technology, and the
+counterfactual case for a multi-PE dataflow system built with
+period-appropriate technology.
+
+---
+
+## 1. Contemporary Processor Reference Points
+
+| Chip | Year | Transistors | Process | On-chip storage | Notes |
+|------|------|------------|---------|----------------|-------|
+| MOS 6502 | 1975 | ~3,510 (logic only) | 8 µm NMOS | A, X, Y internal regs only | Minimal transistor budget |
+| Z80 | 1976 | ~8,500 | 4 µm NMOS | ~20 registers (two banks + specials) | |
+| TMS9900 | 1976 | ~8,000 est. | NMOS | 3 internal regs; **16 GP regs in external RAM** | Minicomputer heritage |
+| Am2901 | 1975 | ~1,000 | Bipolar (TTL/ECL) | 16 × 4-bit register file | Bit-slice, 16 MHz |
+| Intel 8086 | 1978 | ~29,000 | 3.2 µm NMOS | 14 registers; large microcode ROM | |
+| Motorola 68000 | 1979 | ~68,000 | 3.5 µm NMOS | 8 data + 7 addr regs (32-bit) | Clean 32-bit ISA |
+| Intel 80286 | 1982 | ~134,000 | 1.5 µm | No cache | |
+| ARM1 | 1985 | ~25,000 | 3 µm CMOS | 25 × 32-bit registers | RISC; 50 mm² die |
+| Motorola 68020 | 1984 | ~190,000 | 2 µm CMOS | **256-byte instruction cache** | First µP with on-chip cache |
+| INMOS T414 | 1985 | ~200,000* | 1.5 µm CMOS | **2 KB on-chip SRAM** | Transputer; 4 serial links |
+| INMOS T800 | 1987 | ~250,000+ | CMOS | **4 KB on-chip SRAM** + FPU | |
+| EM-4 (EMC-R) | 1990 | ~45,788 gates | 1.5 µm CMOS | 1.31 MB SRAM per PE | 80-PE prototype built |
+
+\*The T414's ~200K figure likely includes SRAM cell transistors. The logic
+core was probably 50–80K transistors, with on-chip SRAM accounting for a
+large fraction of the total.
+
+**Our PE target: ~3–5K transistors of logic + external SRAM chips.**
+
+This places each PE squarely in 6502-to-Z80 territory for logic
+complexity. The PE is not a complete general-purpose processor — it
+trades away the program counter, complex instruction decoder, microcode
+ROM, and sequential control flow machinery in exchange for matching
+store logic and token handling.
+
+---
+
+## 2. The TMS9900 Precedent
+
+The TMS9900 (1976) is the strongest historical precedent for the
+external-storage PE model. It had only 3 internal registers (PC, WP, SR)
+and accessed its 16 "general purpose registers" through external SRAM via
+a workspace pointer. Every register access was a memory access.
+
+At 3 MHz with ~300 ns SRAM, register accesses were single-cycle. The
+penalty was real — a register-to-register ADD took 14 clock cycles due to
+multiple memory round-trips — but the design worked, and context-switch
+speed was unmatched (change one pointer, entire register set swaps).
+
+Our PE has the same structural relationship to its SRAM: matching store,
+instruction memory, and context slots all live in external SRAM, accessed
+via direct address concatenation. The key difference is that our PE
+doesn't need multiple memory round-trips per instruction — a token
+arrives, we index into the matching store (one SRAM access), check the
+occupied bit, and if matched, fetch the instruction (one SRAM access) and
+execute. Arguably *fewer* memory accesses per useful operation than the
+TMS9900.
+
+The TMS9900 also demonstrates that the "registers in external memory"
+approach was commercially viable and accepted by the market in the
+mid-1970s. The 40-pin implementations (TMS9995 etc.) later included
+128–256 bytes of fast on-chip RAM for registers, validating the
+evolutionary path from external to on-chip storage.
+
+---
+
+## 3. SRAM Technology and Access Times
+
+### Available Parts by Year
+
+| Part | Organisation | Access Time | Approx. Availability |
+|------|-------------|------------|---------------------|
+| Intel 2102 | 1K × 1 | 500–850 ns | 1972 |
+| Intel 2114 | 1K × 4 | 200–450 ns | ~1977 |
+| Intel 2147 | 4K × 1 | 55–70 ns | 1979 (bipolar, expensive) |
+| HM6116 | 2K × 8 | 120–200 ns | ~1981 |
+| HM6264 | 8K × 8 | 70–200 ns | ~1983–84 |
+| HM62256 | 32K × 8 | 70–150 ns | mid-1980s |
+
+### Clock Speed vs SRAM Access
+
+| Clock | Period | Single-cycle SRAM needed | Available by |
+|-------|--------|-------------------------|-------------|
+| 4 MHz | 250 ns | 250 ns (2114 comfortably) | 1977 |
+| 5 MHz | 200 ns | 200 ns (2114, tight) | 1978 |
+| 8 MHz | 125 ns | 125 ns (6116 fast grades) | 1982 |
+| 10 MHz | 100 ns | 100 ns (6264 fast grades) | 1984 |
+
+At 5 MHz with 200 ns 2114s, single-cycle *read or write* is achievable.
+Single-cycle read-modify-write (required for matching store) is not —
+the 2114 is single-ported and 200 ns access fills the entire clock
+period. This constrains matching store pipeline throughput to one
+operation per 2 clock cycles in the 1979 scenario. See the companion
+document on pipelining for approaches to mitigating this.
+
+By 1981–82 with 150 ns 6116 parts at 5 MHz, a half-clock
+read/write split becomes feasible (100 ns per half-cycle, with margin).
+By 1984 with fast 6264 parts, 10 MHz pipelined operation is practical.
+
+### The 74LS670 Register File
+
+The SN74LS670 (4 × 4 register file with 3-state outputs) provides a
+critical capability: **true simultaneous read and write to different
+addresses**, with:
+
+- Read access time: ~20–24 ns typical
+- Write time: ~27 ns typical
+- Separate read and write address/enable inputs (dual-ported)
+- 16-pin DIP, ~98 gate equivalents, ~125 mW
+
+This part was available in the LS family by the late 1970s (the LS
+subfamily was comprehensively available by 1977–78). At $2–4 per chip in
+volume, it's affordable for targeted use in pipeline bypass logic and
+small register files.
+
+The 670's 4-bit word width is an exact match for per-entry matching
+store metadata (1 occupied bit + 1 port bit + 2 generation counter
+bits), making it ideal for a write-through metadata cache. See the
+companion pipelining document for the full design.
+
+---
+
+## 4. Per-PE Chip Count Analysis (1979 Scenario)
+
+### Configuration: 8 context slots × 32 entries = 256 cells
+
+Using 2114 (1K × 4) SRAM for bulk storage and 74LS670 for fast-path
+and register file functions.
+
+**Matching store data (16-bit operand values):**
+256 entries × 16 bits = 512 bytes.
+4 × 2114 in parallel (each contributes 4 bits of the 16-bit word,
+using 256 of 1024 available locations).
+
+**Matching store metadata:**
+Handled by shared 670-based cache / SC register file.
+See pipelining companion document.
+
+**Instruction RAM (128 entries × 24-bit):**
+128 × 24 bits = 384 bytes.
+4 × 2114 (using 128 of 1024 locations × 4 bits each, paralleled for
+width). Alternatively 6 × 2114 for 24-bit width without bit waste,
+depending on encoding.
+
+**Shared metadata cache / SC register file / predicate register:**
+8 × 74LS670 (see companion document).
+
+**ALU + control logic:**
+~15–20 TTL chips (adder, logic unit, comparators, muxes, shifter,
+EEPROM decoder, pipeline state machine, bus serialiser/deserialiser).
+
+**Per-PE total: ~31–36 chips (1979 parts)**
+
+### 4-PE System Total
+
+| Subsystem | Chips |
+|-----------|-------|
+| 4 × PE logic + SRAM | 124–144 |
+| Interconnect (shared bus, arbitration) | ~10–15 |
+| SM (structure memory, 4–8 banks) | ~20–40 |
+| I/O + bootstrap | ~15–25 |
+| **System total** | **~170–225 chips** |
+
+This is comparable to a late-1970s minicomputer CPU board, or roughly
+two S-100 boards' worth of components. Well within the engineering
+capability and cost envelope of a minicomputer product.
+
+---
+
+## 5. The 68000 Comparison
+
+The 68000 (1979) is the most apt contemporary comparison:
+
+- **Instruction width**: 68000 uses 16-bit instruction words encoding a
+  32-bit ISA. Our IRAM uses ~24-bit instruction words encoding dataflow
+  operations. Comparable.
+- **Data path**: 68000 has 16-bit external bus, 32-bit internal paths.
+  Our design has 16-bit external bus, wider internal pipeline registers
+  (~64–68 bits). Structurally similar.
+- **Logic budget**: 68000 uses ~68,000 transistors, of which a huge
+  fraction is microcode ROM for complex instruction decode. Our 4-PE
+  system at ~3–5K logic transistors each = 12–20K transistors of PE
+  logic. With interconnect and I/O, maybe 25–35K total. Roughly half a
+  68000 in logic, or about one-third when counting the 68000's internal
+  register file transistors.
+- **SRAM dependency**: 68000 has on-chip registers (expensive in
+  transistors). Our design uses external SRAM (cheap in silicon, more
+  board space). The TMS9900 proved this trade-off was commercially
+  viable three years earlier.
+
+At 1979's 3.5 µm NMOS process, 25K transistors of logic fits in
+~15–25 mm² of die area. The 68000 die was ~44 mm². A single-die
+integration of 4 PEs (logic only, SRAM external) would be significantly
+smaller and cheaper than a 68000.
+
+---
+
+## 6. The Transputer Comparison (1985)
+
+The INMOS T414 transputer (1985) is the closest historical analogue to
+what we're proposing, but approached from a different direction:
+
+| | T414 Transputer | Our 4-PE Design |
+|---|---|---|
+| Architecture | Single complex PE | 4 simple PEs |
+| Parallelism model | CSP message passing (explicit) | Dataflow (implicit) |
+| On-chip storage | 2 KB SRAM | External SRAM |
+| Transistors | ~200,000 | ~25–35K logic |
+| Process | 1.5 µm CMOS | 3.5 µm NMOS (1979 target) |
+| Inter-PE communication | Serial links (20 Mbit/s) | Shared bus or dedicated links |
+| Programming model | occam (explicit distribution) | Compiler-managed graph |
+
+The Transputer took the "one big smart PE with built-in message passing"
+path. Our architecture takes the "many small dumb PEs with implicit
+synchronisation" path. The Transputer's 200K transistors could fund
+~40–60 of our PEs in raw logic. Even accounting for SRAM overhead,
+an integrated version at Transputer-class process technology could pack
+8–16 PEs on a die, which is qualitatively different from a single
+Transputer — you're getting genuine fine-grained parallelism rather than
+coarse-grained task parallelism.
+
+---
+
+## 7. Why Multi-Processor Microcomputers Didn't Happen (And Why Dataflow Changes This)
+
+### The Historical Blockers
+
+1. **Cache coherence**: von Neumann processors sharing memory need
+   coherence protocols. These are complex and were not well understood
+   until the mid-1980s.
+
+2. **Software parallelism**: writing parallel software for shared-memory
+   von Neumann machines was (and remains) brutally difficult. The
+   installed base of sequential FORTRAN and C code was enormous.
+
+3. **Instruction set compatibility**: the IBM 360 lesson — ISA
+   compatibility wins markets. A parallel machine that can't run
+   existing binaries starts with zero software.
+
+4. **Single-thread performance**: for inherently sequential code, one
+   big fast core beats multiple small slow cores. In 1979, most
+   programs were deeply sequential.
+
+### What Dataflow Changes
+
+- **No cache coherence needed**: each PE has its own local IRAM and
+  matching store. Data moves as tokens. There is no shared mutable
+  state at the PE level (SM handles shared data with its own
+  synchronisation protocol via I-structure semantics).
+
+- **Implicit parallelism**: the compiler decomposes the program into a
+  dataflow graph. Parallelism is inherent in the graph structure. The
+  hardware handles synchronisation through token matching. No
+  programmer effort required beyond writing the source code.
+
+- **Software compatibility via compiler**: an LLVM backend targeting the
+  dataflow ISA could compile standard C/Rust. The gap between LLVM's
+  SSA-form IR and a dataflow graph is much smaller than the gap
+  between 1979-era C compilers and dataflow assembly.
+
+- **Latency tolerance**: the PE processes whatever tokens are ready.
+  If one token is waiting on a slow SM access, the PE works on other
+  tokens. This is inherent in the execution model — no special
+  hardware needed.
+
+### The Remaining Hard Problem: Compiler Technology
+
+The biggest genuine blocker in 1979 was compiler technology. Dataflow
+compilers need to partition programs into graphs, assign nodes to PEs,
+manage context slots, and schedule token routes. In 1979, compilers
+could barely optimise sequential code. By the mid-1980s, the Manchester
+and Monsoon teams had working dataflow compilers, but these were
+research efforts, not production tools.
+
+Today, this is a solvable problem. LLVM already performs sophisticated
+dependency analysis, loop vectorisation, and graph-based intermediate
+representations. A dataflow backend is substantial but not unreasonable.
+
+---
+
+## 8. The "Road Not Taken" Argument
+
+Modern out-of-order superscalar processors are, at their core, dataflow
+engines trapped inside a von Neumann straitjacket:
+
+- **Register renaming** creates unique names for each value — this is
+  exactly what tagged tokens do in a dataflow machine.
+- **Reservation stations** (Tomasulo, 1967) are matching stores: an
+  instruction waits for its operands to arrive, then fires.
+- **The reorder buffer** exists solely to reconstruct sequential
+  semantics from what is internally dataflow execution. It is the
+  tax paid for pretending to be von Neumann.
+- **Branch prediction** attempts to speculate about the dataflow graph's
+  structure, because the sequential ISA doesn't encode it. A dataflow
+  graph has no branches to predict — conditional execution is a SWITCH
+  node that routes tokens deterministically.
+- **Out-of-order execution** discovers at runtime the parallelism that
+  was always present in the program but obscured by the sequential
+  instruction stream. A dataflow compiler encodes this parallelism
+  explicitly.
+
+A modern high-performance core dedicates ~80–90% of its transistor
+budget to the cache hierarchy and the OoO/speculation engine. The
+actual ALU is a tiny fraction of the die. A dataflow PE is almost
+entirely ALU and matching, because the execution model eliminates the
+need for the translation layer.
+
+As the memory wall has worsened (DRAM latency ~100–300 cycles on modern
+systems vs 1–2 cycles in 1979), the overhead of the von Neumann
+translation layer has grown proportionally. The dataflow model's
+inherent latency tolerance — process whatever token is ready — becomes
+more valuable as memory gets relatively slower.
+
+This suggests that a dataflow architecture, while perhaps premature in
+1979 due to compiler limitations, might actually age *better* than
+von Neumann as the memory wall gets worse. The matching store never
+misses. The data arrives when it arrives. The PE does useful work in the
+meantime. No cache hierarchy needed in the PE pipeline — just fast
+local SRAM for matching and instruction storage, with SM handling the
+shared data.
+
+---
+
+## 9. Scaling Considerations for Integration
+
+### 1979–1982: Discrete Logic (Prototype / Low-Volume Minicomputer)
+
+- 4 PEs on 1–2 large PCBs
+- ~170–225 TTL + SRAM chips total
+- 5 MHz clock, 2-cycle matching store access
+- Shared bus interconnect
+- Competitive with a 68000 on parallel workloads
+
+### 1983–1985: Single-Chip PE (1.5–2 µm CMOS)
+
+- PE logic on-chip (~3–5K transistors)
+- Matching store metadata on-chip (670-equivalent register file)
+- Bulk SRAM external
+- 4–8 PEs per board with external SRAM
+- 8–10 MHz, single-cycle matching via half-clock or on-chip dual-port
+
+### 1986–1988: Multi-PE Chip (1–1.5 µm CMOS)
+
+- 4–8 PE cores on one die with shared on-chip SRAM
+- Wide parallel local interconnect between adjacent PEs (~1 cycle hop)
+- External SM SRAM
+- 15–20 MHz
+- Competitive with Transputer systems at lower per-chip cost
+
+### Modern: Many-PE Tile (Sub-100 nm)
+
+- 64–256+ PEs per die with on-chip SRAM hierarchy
+- Network-on-chip interconnect
+- I-structure SM cache with simplified coherence protocol
+  (write-once semantics reduce coherence to fill notifications)
+- 1+ GHz
+- LLVM-based compiler toolchain
+
+---
+
+## 10. Open Questions
+
+1. **SM cache architecture for modern integration**: does the
+   I-structure write-once semantics enable a dramatically simpler
+   coherence protocol than MESI? What does the cache hierarchy look
+   like for SM in a many-PE chip?
+
+2. **Compiler partitioning strategy**: how does matching store size
+   (context slots × entries) interact with compiler code generation?
+   What's the minimum matching store that supports "most" programs
+   without excessive function splitting?
+
+3. **Sequential performance floor**: what is the minimum acceptable
+   single-thread performance for a dataflow PE, and how does the
+   strongly connected block mechanism close the gap with conventional
+   cores? See companion pipelining document.
+
+4. **Network topology at scale**: at what PE count does the shared bus
+   become inadequate, and what's the right topology for 16–64 PEs?
+   Ring, mesh, omega network, or hierarchical?

design-notes/io-and-bootstrap.md

···
 # Dynamic Dataflow CPU — I/O & Bootstrap
 
-Covers the type-11 subsystem: I/O controller design, peripheral interface,
-bootstrap sequence, and the path from microcontroller-assisted bring-up to
-self-hosted boot.
+Covers IO as memory-mapped SM, the bootstrap sequence via SM00 EXEC, and
+the path from microcontroller-assisted bring-up to self-hosted boot.
+
+See `architecture-overview.md` for module taxonomy and token format.
+See `sm-design.md` for SM interface protocol, EXEC operation, and SM00
+bootstrap details.
+See `bus-architecture-and-width-decoupling.md` for bus width rationale
+and IRAM write token format.
+
+## IO Model: Memory-Mapped SM
 
-See `architecture-overview.md` for type-11 packet semantics.
-See `network-and-communication.md` for how the I/O controller connects to
-the bus. See `bus-architecture-and-width-decoupling.md` for bus width
-rationale and flit structure.
+IO devices are mapped into SM address space. There is no separate IO
+controller or dedicated IO token type — IO operations use standard SM
+tokens (bit[15]=1).
 
-## Type 11 Subtypes
+### How It Works
 
-Type 11 is the "system management" channel. the 2-bit subtype field
-immediately after the type field discriminates traffic classes:
+An SM (typically SM00 at v0) maps IO devices into a reserved address
+range. From the CM's perspective, reading from a UART is identical to
+reading from any other SM cell:
 
 ```
-11 + 00: I/O operation — routed to the I/O controller
-11 + 01: Extended address / config write — target PE instruction memory,
-         routing table, or other config registers
-11 + 10: Reserved (future: debug/trace, DMA, performance counters)
-11 + 11: Reserved
+READ from IO-mapped address:
+  1. CM sends SM READ token to SM00, IO-mapped address range
+  2. If IO device has data: cell is FULL, SM returns result immediately
+  3. If IO device has no data: cell is EMPTY, SM defers read
+  4. When IO device receives data: cell transitions to FULL,
+     deferred read is satisfied, result token emitted
+
+WRITE to IO-mapped address:
+  1. CM sends SM WRITE token to SM00, IO-mapped address range
+  2. SM forwards write data to the IO device
 ```
 
-All type-11 traffic is low frequency relative to types 00/01/10. it is
-acceptable for decode and handling to take extra cycles.
+I-structure semantics provide natural interrupt-free IO. The CM does not
+poll or busy-wait — it issues a READ, and the result arrives when data is
+available. This is the dataflow-native interrupt model: external events
+are just writes to SM cells that satisfy deferred reads.
 
-## I/O Controller
+### IO Address Mapping
 
-### What It Is
+IO devices occupy a contiguous range within SM00's address space. The
+mapping is configured at bootstrap (or hardwired for v0):
 
-A fixed-function device on the network (not a PE): it has no matching
-store, instruction memory, or ALU. it receives type-11 subtype-00
-packets, interprets them as I/O commands, and responds.
+```
+Example SM00 address map:
+  0x000 - 0x0FF:  IO devices (tier 0, raw memory semantics)
+  0x100 - 0x1FF:  Bootstrap ROM (tier 0, read-only)
+  0x200 - 0x3FF:  General-purpose I-structure cells (tier 1)
+```
 
-it is also the only network participant that can **spontaneously generate
-tokens** without first receiving one. this is how external events (UART
-RX, sensor interrupts, timer ticks) enter the dataflow graph.
+Within the IO range, specific addresses map to device registers:
 
-### Token Format for I/O (subtype 00, 3-flit)
+```
+Example IO register map (v0, UART only):
+  0x000:  UART TX data (write)
+  0x001:  UART RX data (read, defers if no byte available)
+  0x002:  UART status (read, raw — no deferral)
+  0x003:  UART config (write)
+```
 
-I/O operations use type-11 3-flit tokens. flit 1 carries type + subtype +
-routing, flits 2-3 carry the I/O command and data/return routing.
+### Unsolicited Events (Interrupt Equivalent)
 
-```
-I/O Request (CM -> I/O controller, 3 flits):
-  flit 1: [type:2=11][subtype:2=00][device:3][register:4][R/W:1][pad:4]
-                                                                   = 16 bits
-  flit 2: [data:16] (for writes) or [return routing:16] (for reads)
-                                                                   = 16 bits
-  flit 3: [extended payload / additional return routing / pad]     = 16 bits
+When an external event occurs (e.g., UART receives a byte), the IO
+hardware writes the data into the corresponding SM cell. If a deferred
+read is pending on that cell, the SM satisfies it immediately — the
+requesting CM receives a result token with the data. No interrupt
+controller, no vector table, no mode switch.
 
-I/O Response (I/O controller -> CM):
-  Repackaged as a standard 2-flit type 00 or 01 token addressed to the
-  requesting CM, using return routing from the request.
-```
+If no deferred read is pending, the data sits in the cell (FULL state)
+until a CM reads it. This is natural flow control: the IO device produces,
+the CM consumes, with I-structure semantics as the synchronisation
+primitive.
 
-**Open question**: return routing for I/O reads. options:
-- (a) I/O read requests carry return routing in flit 2 (same pattern as
-  SM READ requests — data field is unused on reads). flit 3 provides
-  additional space if needed.
-- (b) I/O controller has a preconfigured "return to" address per device
-  (simpler requests, but less flexible)
-- (c) I/O controller always returns to a fixed "I/O result handler" node
-  in a designated PE (simplest, but rigid)
-
-option (a) is most consistent with how SM works. likely the right call.
-the extra flit (3 vs SM's 2) gives more room for return routing and
-I/O command fields.
+Implications:
+- IO devices are **write sources** into SM cells
+- Backpressure: if the CM hasn't issued a READ, the IO device can still
+  write (cell becomes FULL). Subsequent writes before a READ overwrite —
+  the SM cell is a 1-deep buffer. For deeper buffering, the IO hardware
+  can use a range of cells as a circular buffer.
+- The SM does not spontaneously generate tokens — it only satisfies
+  pending deferred reads. The IO device's write *triggers* the deferred
+  read satisfaction, which is when the result token is emitted.
 
 ### Hardware
 
+IO hardware sits on SM00's internal data bus alongside the SRAM banks.
+The address decoder routes IO-range addresses to IO device registers
+instead of SRAM:
+
 ```
-16-bit Bus
+SM00 Internal Bus
        |
-       v
-  [Input Deserialiser]
-    (reassemble 3+ flits into logical token)
-       |
-       v
-  [Input FIFO]
-       |
-       v
-  [Subtype Check] -- not subtype 00? --> discard or forward
-       |
-       v
-  [Device/Register Decode] --- EEPROM or small logic
+  [Address Decoder]
        |
-       +---> [UART chip (6850/16550/etc.)]
-       |         - TX data register
-       |         - RX data register
-       |         - Status register
-       |         - Baud/config registers
+       +---> addr < 0x100? --> [IO Device Registers]
+       |                           |
+       |                           +---> [UART chip (6850/16550/etc.)]
+       |                           +---> [future: SPI, GPIO, timer]
        |
-       +---> [future: SPI, GPIO, timer, etc.]
-       |
-       v
-  [Result Formatter] --- constructs 2-flit type 00/01 return token
-       |
-       v
-  [Output Serialiser]
-    (split token into 16-bit flits)
-       |
-       v
-  [Output FIFO]
-       |
-       v
-  16-bit Bus (token injected as type 00/01)
+       +---> addr >= 0x100? --> [SRAM Banks] (normal SM operation)
 ```
 
-Estimated hardware: ~15-25 TTL chips + UART chip. comparable to the
-microsequencer it replaces, but architecturally integrated.
-
-### Unsolicited Token Generation (Interrupt Equivalent)
-
-When an external event occurs (e.g., UART receives a byte), the I/O
-controller generates a token and injects it onto the network. from the
-receiving CM's perspective, data just arrived — exactly like any other
-token. no interrupt hardware needed on the CM side.
-
-The destination for unsolicited tokens is preconfigured: either hardcoded
-in the I/O controller's EEPROM, or set at bootstrap via a type-11 config
-write to the I/O controller itself. "when UART RX fires, send the byte
-to PE 2, offset 0x10, context slot 3, port 0."
-
-This is the **dataflow-native interrupt model**: external events are
-token sources. they feed into the dataflow graph at designated entry
-points. the receiving PE doesn't need to do anything special — it just
-sees a token arrive and processes it like any other.
-
-Implications:
-- the I/O controller is a **source node** in the dataflow graph
-- it breaks the invariant that "tokens are only produced in response to
-  other tokens" — external reality leaks in here
-- the network must accept tokens from the I/O controller even when no
-  request was sent (the I/O controller's output FIFO can fill independently)
-- if the destination PE's input FIFO is full, backpressure propagates
-  to the I/O controller. UART RX bytes could be lost if the system can't
-  keep up. the I/O controller should have a small internal buffer
-  (or the UART chip's built-in FIFO handles this).
-
-## Config Writes (subtype 01)
+The IO device registers behave like SM cells from the SM controller's
+perspective: they have presence state, support READ/WRITE, and can
+satisfy deferred reads. The difference is that the data source is an
+external device rather than SRAM.
 
-### Purpose
+Estimated additional hardware for IO: ~8-12 TTL chips (address decode,
+IO device interface, presence state for IO cells) + UART chip.
 
-Type-11 subtype-01 packets write to PE instruction memory, routing tables,
-or other configuration state. they are the mechanism for:
+---
 
-1. Bootstrap program loading
-2. Runtime reprogramming (future)
-3. Routing table configuration
+## IRAM Writes
 
-### Packet Format (3-4 flits)
+IRAM writes use CM misc-bucket tokens (prefix 011+01). They are addressed
+to a specific PE and carry instruction word data. See
+`bus-architecture-and-width-decoupling.md` for the IRAM write token format
+and valid-bit protection protocol.
 
-Config writes are inherently multi-flit: they must carry a target PE,
-IRAM address, and an instruction word that is 32-48 bits wide (decoupled
-from bus width). A 48-bit instruction word requires 3 data flits plus
-the routing flit.
+IRAM writes can originate from:
+- An external microcontroller (development/prototyping)
+- SM00's EXEC sequencer during bootstrap (reading pre-formed IRAM write
+  tokens from ROM)
+- A CM running a loader program (runtime code loading)
 
-```
-Config Write (IRAM load, 3-4 flits):
-  flit 1: [type:2=11][subtype:2=01][target_PE:2][flags:2][addr:8]  = 16 bits
-  flit 2: [instruction_word_hi:16]                                  = 16 bits
-  flit 3: [instruction_word_lo:16]                                  = 16 bits
-  flit 4: [instruction_word_ext:16] (if IRAM > 32 bits)            = 16 bits
+The network routes IRAM writes like any other CM token — bit[15]=0, PE_id
+in the appropriate flit 1 position. The target PE recognises the 011+01
+prefix and routes the token to the instruction memory write port.
 
-Routing table config write (3 flits):
-  flit 1: [type:2=11][subtype:2=01][target_node:4][config_type:8]  = 16 bits
-  flit 2: [table_entry / prefix data]                              = 16 bits
-  flit 3: [routing data]                                           = 16 bits
-```
+---
 
-The exact bit allocation depends on IRAM width (see
-`bus-architecture-and-width-decoupling.md`). 48-bit IRAM = 4 flits per
-config write; 32-bit IRAM = 3 flits. Config writes are rare (bootstrap
-and hot-patching only), so the extra flits are acceptable.
+## Bootstrap Sequence
 
-### Routing
+### Self-Hosted Bootstrap (via SM00 EXEC)
 
-Config writes are addressed to a specific PE by the target_PE field. the
-routing network delivers them like any other token — type 11 is inspected
-by routing nodes only to the extent of "this is not type 00/01/10, forward
-toward the target." the target PE recognises the subtype-01 packet and
-routes it to the instruction memory write port (see `pe-design.md`).
+On system reset:
 
-Routing tables themselves can be written via config writes. the target is
-a routing node, not a PE. routing nodes need a small amount of config
-write handling: recognise "this config write is for me" (based on node ID)
-and update the local prefix table. during bootstrap, routing nodes are in
-default mode (fixed-address routing), so config writes reach them reliably
-without needing configured routing.
+1. SM00 is wired to the reset signal
+2. SM00's sequencer triggers EXEC on a predetermined ROM base address
+3. The ROM region contains pre-formed tokens stored as 2-cell entries:
+   - IRAM write tokens (prefix 011+01) to load PE instruction memories
+   - Seed tokens (dyadic wide, monadic normal) to start execution
+4. SM00 reads each 2-cell entry and emits it as a 2-flit token on the bus
+5. PEs receive IRAM writes and load their instruction memories
+6. Seed tokens fire and execution begins
 
-## Bootstrap Sequence
+The program image in ROM is a flat sequence of pre-formed token pairs.
+The compiler outputs this format directly — each entry is (flit 1, flit 2)
+as stored in two consecutive SM cells. SM00's EXEC sequencer is just an
+address counter with a limit comparator; it does not interpret the tokens
+it emits.
 
 ### Development / Early Prototyping
 
 For Phase 0-2, an external microcontroller (RP2040, Arduino) acts as the
-bootstrap source. it is NOT part of the architecture — it's a test fixture.
+bootstrap source. It is NOT part of the architecture — it is a test
+fixture.
 
 The microcontroller:
-1. Formats type-11 subtype-01 multi-flit packets (config writes: 3-4
-   flits per instruction word depending on IRAM width)
+1. Formats IRAM write tokens (prefix 011+01, 2-3 flits per instruction)
 2. Injects flits into the 16-bit bus (via a dedicated injection port or
    by bit-banging the bus interface)
 3. Writes instruction words to each PE's instruction memory
-4. Optionally writes routing table entries to routing nodes
-5. Optionally writes initial SM contents via 2-flit type-10 packets
-6. Injects seed token(s) — 2-flit type 00/01 packets that kick off
-   execution
-7. Releases the bus (goes high-impedance or disconnects)
+4. Optionally writes initial SM contents via SM tokens (bit[15]=1)
+5. Injects seed tokens to start execution
+6. Releases the bus (goes high-impedance or disconnects)
 
-This lets PE and SM hardware be tested without any of the I/O controller
-or bootstrap logic existing. the microcontroller is the bootstrap, the
-debug interface, and the test harness all in one.
+This lets PE and SM hardware be tested without bootstrap ROM or EXEC
+sequencer existing. The microcontroller is the bootstrap, the debug
+interface, and the test harness all in one.
 
-### Self-Hosted Bootstrap (Phase 4+)
+### Routing During Bootstrap
 
-The I/O controller replaces the microcontroller as the bootstrap source:
-
-1. On reset, the I/O controller enters bootstrap mode
-2. It reads program data from a connected flash/EEPROM (via SPI or
-   parallel interface) or receives it over UART from an external host
-3. It formats config write packets (type-11 subtype-01) and injects them
-   onto the network
-4. Each PE receives config writes and loads its instruction memory
-5. Routing tables are configured via config writes to routing nodes
-6. I/O controller injects seed token(s) to start execution
-7. I/O controller transitions to normal mode (handling I/O requests)
-
-The I/O controller's bootstrap logic is a state machine, likely driven
-by a small ROM or EEPROM. it doesn't need to be a general-purpose
-processor — it just sequences reads from storage and formats them as
-config writes.
-
-### Chicken-and-Egg: Routing During Bootstrap
-
-During bootstrap, routing tables are not yet configured. the network uses
+During bootstrap, routing tables are not yet configured. The network uses
 fixed-address default routing (see `network-and-communication.md`):
 
 - Each PE has a unique ID (EEPROM / DIP switches)
-- Routing nodes forward by PE_id without consulting tables
+- Routing nodes forward by destination ID without consulting tables
 - At v0 scale (shared bus), this is trivially true — everything sees
   everything
-- At larger scale, default routing must be sufficient to reach all PEs
-  from the bootstrap source. this constrains the physical topology
-  (bootstrap source must be topologically reachable from all PEs via
-  default forwarding).
-
-The I/O controller's own ID and the default routing path to it are
-hardwired or EEPROM-configured. it doesn't depend on routing tables.
+- SM00's tokens reach all PEs via default routing since SM00 is on the
+  shared bus
 
 ### Seed Token Injection
 
-After program loading, the I/O controller (or microcontroller) injects
-one or more seed tokens to start execution. these are normal type 00/01
-tokens addressed to the entry point(s) of the loaded program.
+The bootstrap ROM includes seed tokens after the IRAM write tokens. These
+are standard CM tokens addressed to the entry point(s) of the loaded
+program. SM00's EXEC sequencer emits them in order after the IRAM writes —
+no special handling needed.
 
 For a simple program with one entry point: one seed token to one PE.
 For a program with multiple independent entry points (e.g., main program
-+ I/O handler): multiple seed tokens to different PEs.
++ IO handler): multiple seed tokens to different PEs.
 
-The seed tokens are part of the program image — the compiler specifies
-"to start this program, inject these tokens." the bootstrap loader reads
-them from the program image and injects them after loading is complete.
+---
 
 ## Layering Summary
 
-The I/O and bootstrap design is explicitly layered for incremental
-development:
-
-| Phase | Bootstrap Source | I/O | Network Config |
+| Phase | Bootstrap Source | IO | Network Config |
 |-------|-----------------|-----|----------------|
 | 0-1 | Microcontroller (external) | None | Direct SRAM programming |
-| 2 | Microcontroller via type-11 | None | Config writes on bus |
-| 3 | Microcontroller via type-11 | Polling via SM (optional) | Config writes |
-| 4 | I/O controller (self-hosted) | I/O controller (type 11) | Config writes from I/O controller |
+| 2 | Microcontroller via IRAM writes | None | IRAM writes on bus |
+| 3 | Microcontroller via IRAM writes | Polling via SM (optional) | IRAM writes |
+| 4 | SM00 EXEC (self-hosted) | Memory-mapped SM00 | IRAM writes from EXEC |
 
-Each phase adds capability without redesigning previous work. the key
-enabler is that config writes (type-11 subtype-01) work the same whether
-they come from a microcontroller or the I/O controller. the network
-doesn't know or care about the source.
+Each phase adds capability without redesigning previous work. The key
+enabler is that IRAM write tokens work the same whether they come from a
+microcontroller or SM00's EXEC sequencer. The network doesn't know or care
+about the source.
+
+---
 
 ## Open Design Questions
 
-1. **I/O return routing** — option (a), (b), or (c) from above?
-2. **Unsolicited token destination config** — hardcoded or runtime-
-   configurable? if configurable, via what mechanism? (probably a
-   type-11 config write to the I/O controller itself)
-3. **I/O controller bootstrap ROM** — how big? what's in it? just a
-   state machine for "read flash, emit config writes" or something more?
-4. **Flash/EEPROM interface** — SPI? parallel? what storage device?
-5. **Program image format** — what does the compiler output? a stream of
-   (target_PE, address, instruction_word) tuples? plus seed tokens at
-   the end?
-6. **Multiple I/O devices** — how does the device field in the I/O token
-   scale? 3 bits = 8 devices. enough?
-7. **I/O controller as bootstrap PE** — at what point (if ever) does it
-   make sense to make the I/O controller a full PE with a boot ROM
-   instead of fixed-function? probably not for v0-v4, but worth keeping
-   in mind architecturally.
+1. **IO address range size** — how many cells reserved for IO in SM00?
+   Depends on device count and register depth per device.
+2. **IO cell buffering depth** — single cell (1-deep) per IO register, or
+   a range of cells for circular buffering? 1-deep is simplest; circular
+   buffer needs SM-side write pointer management.
+3. **IO write-overwrite semantics** — if an IO device writes to a FULL
+   cell (previous data not yet consumed), overwrite or error? Overwrite
+   is simpler but loses data. Error needs a signalling mechanism.
+4. **Flash/EEPROM interface for ROM** — SPI? Parallel? What storage device?
+   ROM could be physical ROM chips on SM00's address bus, or flash accessed
+   via page register.
+5. **Program image format** — flat sequence of (flit1, flit2) token pairs
+   in ROM. Needs a terminator or length prefix so EXEC knows when to stop.
+   Length is the EXEC count parameter.
+6. **SM00 further specialisation** — documented as an option (see
+   `sm-design.md`). Not committed for v0. Standard SM opcodes are
+   sufficient for basic IO via I-structure semantics.

design-notes/pe-design.md

···
 ```
 Stage 1: TOKEN INPUT
   - Receive reassembled token from input deserialiser
-  - Classify: type 00/01 (normal), type 11 subtype 01 (config write)
-  - Normal tokens -> pipeline FIFO
-  - Config writes -> instruction memory write port (stalls pipeline)
+  - Classify by prefix: dyadic wide (00), monadic normal (010),
+    misc bucket (011). Within misc bucket: dyadic narrow (sub=00),
+    IRAM write (sub=01), monadic inline (sub=10)
+  - Compute/data tokens -> pipeline FIFO
+  - IRAM writes -> instruction memory write port (stalls pipeline)
   - Buffer in small FIFO (8-deep, storing reassembled tokens)
   - ~1K transistors (flip-flops) or use small SRAM
 
 Stage 2: MATCH / BYPASS
-  - Type 00 (dyadic): direct-index into context slot array
+  - Dyadic (prefix 00 or 011+00): direct-index into context slot array
     - Check generation counter: mismatch = stale, discard
     - First operand: store in slot, advance to wait state
     - Second operand: read partner from slot, both proceed
-  - Type 01 (monadic): bypass matching entirely, proceed directly
+  - Monadic (prefix 010 or 011+10): bypass matching, proceed directly
   - Single cycle for all cases (no hash path, no CAM search —
     direct indexing only, see matching store section below)
   - Estimated: ~200-300 transistors + SRAM
···
 
 ### Runtime Writability
 
-Instruction memory is **not** read-only. It is writable from the network via type-11 subtype-01 (config/extended address) packets. This serves two purposes:
+Instruction memory is **not** read-only. It is writable from the network via IRAM write (prefix 011+01) packets. This serves two purposes:
 
 1. **Bootstrap**: loading programs before execution starts
 2. **Runtime reprogramming**: loading new function bodies while other PEs continue executing (future capability, not needed for v0)
···
 
 #### IRAM Width
 
-| Field | Purpose | Bits (est.) |
-|-------|---------|-------------|
-| Opcode | ALU/control operation | 5-8 |
-| Dest 1 addr | first output instruction address | 10-12 |
-| Dest 1 port | L/R input on destination | 1 |
-| Dest 2 addr | second output instruction address (fan-out) | 10-12 |
-| Dest 2 port | L/R input on destination | 1 |
-| Dest 2 PE | remote PE flag + PE_id for cross-PE outputs | 0-3 |
-| Arity | monadic/dyadic (or encoded in opcode) | 0-1 |
-| Flags | immediate mode, structure op, etc. | 2-4 |
-| Immediate | small constant for immediate-mode ops | 0-8 |
+| Field       | Purpose                                     | Bits (est.) |
+| ----------- | ------------------------------------------- | ----------- |
+| Opcode      | ALU/control operation                       | 5-8         |
+| Dest 1 addr | first output instruction address            | 10-12       |
+| Dest 1 port | L/R input on destination                    | 1           |
+| Dest 2 addr | second output instruction address (fan-out) | 10-12       |
+| Dest 2 port | L/R input on destination                    | 1           |
+| Dest 2 PE   | remote PE flag + PE_id for cross-PE outputs | 0-3         |
+| Arity       | monadic/dyadic (or encoded in opcode)       | 0-1         |
+| Flags       | immediate mode, structure op, etc.          | 2-4         |
+| Immediate   | small constant for immediate-mode ops       | 0-8         |
 
 This sums to roughly **32-48 bits** depending on address space size and
 how aggressively fields are packed. 48 bits (3 x 16-bit SRAM words) is a
···
 lines. Width costs physical chips but does NOT add pipeline latency.
 
 **Instruction words are never serialised onto the external bus** during
-normal execution. They are only written via type-11 config packets during
+normal execution. They are only written via IRAM write packets during
 program loading (slow-path, multi-flit operation). The opcode is an
 implementation detail of the PE — from the network's perspective, it
 doesn't exist.
···
 **Candidate configurations (targeting clean SRAM utilisation):**
 
 ```
-Config A: 32 slots x 16 entries = 512 cells
-  - 9-bit SRAM address (5 ctx + 4 offset)
-  - 16-bit values: 1KB exactly in one 8Kbit SRAM chip
-  - Good concurrency headroom, smaller function chunks
-
 Config B: 16 slots x 32 entries = 512 cells
   - 9-bit SRAM address (4 ctx + 5 offset)
   - 16-bit values: 1KB exactly
-  - Matches current 4-bit ctx_slot token format
-  - Fewer concurrent activations, bigger function chunks
+  - Matches the 4-bit ctx and 5-bit offset in dyadic wide tokens
+  - 32 dyadic instructions per context chunk
 
 Config C: 32 slots x 32 entries = 1024 cells
   - 10-bit SRAM address (5 ctx + 5 offset)
   - 16-bit values: 2KB, fits in one 16Kbit SRAM chip
+  - Requires 5-bit ctx (would need wider token format in future)
   - Most headroom in both dimensions
-  - Probably the sweet spot for SRAM utilisation vs headroom
-
-Config D: 64 slots x 16 entries = 1024 cells
-  - 10-bit SRAM address (6 ctx + 4 offset)
-  - 16-bit values: 2KB
-  - Favours concurrency over function chunk size
-  - 64 concurrent activations likely overkill for v0 but future-proof
 ```
 
 **Entry format (per context slot, per instruction offset):**
···
 > measuring actual concurrent activation counts and dyadic instruction
 > density per PE.
 
-**Recommendation for v0**: start with Config B (16 slots x 32 entries = 1KB) to match the current 4-bit ctx_slot token field. Upgrade to Config C (32 x 32 = 2KB, needs 5-bit ctx_slot) if 16 concurrent activations proves too tight. The physical SRAM chip doesn't change between these configs — just the address generation logic.
+**Recommendation for v0**: Config B (16 slots x 32 entries = 1KB). This
+matches the token format directly: 4-bit ctx from flit 1, 5-bit offset
+from flit 1. Matching store address = `[ctx:4][offset:5]` = 9 bits. The
+SRAM chip doesn't change if upgraded to Config C later — just the address
+generation logic and token format would need a wider ctx field.
 
 ### Instruction Address vs Matching Store Address
 
···
 The matching store is dense with respect to dyadic instructions — no
 gaps for monadic instructions. A function chunk with 20 instructions,
 8 of which are dyadic, uses 8 matching store entries, not 20.
+
+Dyadic instructions pack into IRAM offsets 0-31 (matching the 5-bit
+offset field). Monadic instructions use offsets above the dyadic ceiling,
+addressed by the 7-bit monadic offset field relative to the ceiling.
+See `bus-architecture-and-width-decoupling.md` for the relative addressing
+scheme.
 
 ### Unified Offset: Instruction Address = Matching Store Entry
 
···
 SM can hold code or data — there is no architectural distinction. The
 compiler or loader writes code pages into SM addresses during bootstrap
 or at runtime. A PE (or the I/O controller) reads code from SM and
-reformats it as type-11 config writes to load into the target PE's
-IRAM.
+reformats it as IRAM write tokens to load into the target PE's IRAM.
 
 SM capacity is not enough for more than a small program's code, so
 external addressable code storage is required for anything nontrivial.
···
 assigns a PE (typically the least-utilized one) to pull instruction
 pages from storage and load them onto the bus in advance of when they're
 needed. This is part of the program graph itself — the loader PE runs
-dataflow code that reads from SM or external storage and emits type-11
+dataflow code that reads from SM or external storage and emits IRAM write
 config writes.
 
 This fits naturally into the dataflow paradigm:
···
 every PE's IRAM. that's one approach but costs a lot of memory.
 
 The middle ground is a **working set model**: keep hot function bodies
-loaded, swap cold ones via type-11 config writes when the scheduler
+loaded, swap cold ones via IRAM write tokens (prefix 011+01) when the scheduler
 wants to place an activation on a PE that doesn't have the code yet.
 this is demand paging for instruction memory, and the code storage
 hierarchy (external → SM → IRAM) provides the backing store.
···
   overwriting IRAM. throttle stalls new activations for that fragment,
   existing ones complete, then overwrite. coarse-grained context switch.
 
-The hardware path is already there — writable IRAM + type-11 config
+The hardware path is already there — writable IRAM + IRAM write
 writes + throttle + code storage hierarchy. the missing piece is the
 scheduler, which is a software/firmware problem. nothing in the v0
 hardware prevents adding this later.

design-notes/pe-pipelining-and-multiplexing.md

···
+# PE Pipelining and Metadata/SC Register Multiplexing
+
+Design notes on pipelining the PE's token processing path, the matching
+store read-modify-write timing problem, and a dual-use 74LS670-based
+subsystem that serves as both a matching store metadata cache (dataflow
+mode) and an SC block register file (sequential mode).
+
+---
+
+## 1. Current Pipeline Stages (Unpipelined Baseline)
+
+The PE processes one token to completion before accepting the next:
+
+```
+Stage 1: INPUT     Deserialise flits from bus → internal registers
+Stage 2: MATCH     Matching store R/M/W (read occupied, store/retrieve operand)
+Stage 3: IFETCH    IRAM read (node address → opcode + destinations)
+Stage 4: EXECUTE   ALU operation (data from match + control from IRAM)
+Stage 5: OUTPUT    Form result token, serialise to flits, inject onto bus
+```
+
+Unpipelined throughput: ~8–10 clocks per token (all stages sequential).
+This is the baseline against which pipeline improvements are measured.
+
+---
+
+## 2. The Matching Store Timing Problem
+
+### The Read-Modify-Write Requirement
+
+Matching store access (stage 2) requires:
+
+1. Read the cell at `[ctx_slot : match_entry]`
+2. Check metadata: occupied bit, generation counter, port flag
+3. **If occupied** (second operand arriving): read stored value, clear
+   occupied bit → proceed to instruction fetch with both operands
+4. **If not occupied** (first operand): write incoming value, set
+   occupied bit, record port → consume token, advance to next input
+
+This is an atomic read-modify-write. With single-ported SRAM (the 2114
+at 200 ns access time in a 200 ns clock period at 5 MHz), only one
+operation — read OR write — fits in a single cycle.
+
+### The Pipeline Hazard
+
+If two consecutive tokens target the same matching store cell (both
+operands for the same dyadic instruction arriving back-to-back), the
+second token's read must see the first token's write. With a pipelined
+matching stage, this is a classic RAW (read-after-write) hazard.
+
+Note: this hazard is **statistically uncommon** in dataflow execution.
+Two operands arriving back-to-back means both sides of a computation
+completed near-simultaneously, which requires coincidental timing. The
+two operands typically originate from different parts of the graph with
+different latencies. The bypass path is cheap insurance that fires
+infrequently.
+
+---
+
+## 3. Pipeline Solutions by Aggressiveness
+
+### Option 1: 2-Cycle Matching (Conservative, 1979-Safe)
+
+Accept that matching takes 2 clock cycles: read in cycle 1, decision +
+write in cycle 2. Pipeline everything else around it.
+
+```
+Clock:  1    2    3    4    5    6    7    8
+Token A: IN   MA1  MA2  IF   EX   OUT
+Token B:      IN   ---  MA1  MA2  IF   EX   OUT
+```
+
+Throughput: one token per ~3 clocks (match is the bottleneck at 2
+cycles; other stages overlap). This is roughly a 3× improvement over
+the unpipelined baseline.
+
+Hardware cost: minimal — just pipeline registers between stages.
+~500 extra transistors.
+
+**This is the recommended v0 approach for the discrete build at 5 MHz
+with 2114 SRAM.**
+
+### Option 2: Half-Clock Split (1981+ with Faster SRAM)
+
+Split the matching store cycle into two half-clock phases:
+- Rising edge: address stable, read data appears (~100 ns)
+- Mid-cycle: decision logic resolves
+- Falling edge: write-back commits
+
+Requires SRAM access time < half the clock period. At 5 MHz (200 ns
+period), this needs <100 ns SRAM — achievable with 6116 (120–150 ns
+fast grades) from ~1981, comfortable with 6264 (70–100 ns) from 1983.
+
+Not feasible with 200 ns 2114s at 5 MHz.
+
+Throughput: one token per ~1–2 clocks through matching. With overlap,
+~5 stages at 1 clock each = **one token per clock** in steady state.
+
+### Option 3: Forwarding / Bypass Path
+
+Detect when the incoming token targets the same matching store address
+as a token currently in the pipeline. Forward the in-flight data
+directly instead of reading stale SRAM.
+
+Hardware: address comparator (2 × 74LS85 or 1 × 74LS688) + data mux
+(74LS157). ~4–6 chips per PE.
+
+Useful in combination with options 1 or 2 to handle the rare
+back-to-back hazard case. Not a standalone solution.
+
+### Option 4: Metadata Cache with 74LS670 (Recommended Enhancement)
+
+Separate the metadata (occupied, port, generation — 4 bits per entry)
+from the bulk operand data (16 bits per entry). Store metadata for
+recently-accessed entries in 74LS670 register file chips, which support
+**simultaneous read and write to different addresses** at ~20–24 ns.
+
+The SRAM holds the authoritative copy of all metadata. The 670s act as
+a write-through cache for the hot working set. On a cache hit, the
+dual-port 670 provides single-cycle read-modify-write with no timing
+gymnastics. On a cache miss, fall back to 2-cycle SRAM access.
+
+See section 5 for the full design, which combines this metadata cache
+with the SC block register file.
+
+---
+
+## 4. SRAM Width and the 2114 Constraint
+
+### The Width Problem
+
+The 2114 is 1K × 4 bits. For 16-bit operand data, 4 chips must be
+paralleled (same address lines, each contributing 4 bits). This is
+straightforward — it's just wiring.
+
+The issue is that each chip has 1024 locations but we may use only 256
+(for the 8 ctx × 32 entry configuration). The unused capacity is
+wasted. However, the chip count is determined by **width**, not depth —
+you need 4 chips regardless of whether you use 256 or 1024 locations.
+
+### Matching Store Sizing
+
+| Config | Cells | Address bits | Data SRAM (16-bit) | Dyadic limit |
+|--------|-------|--------------|--------------------|-------------|
+| 16 ctx × 32 entries | 512 | 9 (4+5) | 4 × 2114 | 32 per chunk |
+| 8 ctx × 32 entries | 256 | 8 (3+5) | 4 × 2114 | 32 per chunk |
+| 8 ctx × 16 entries | 128 | 7 (3+4) | 4 × 2114 | 16 per chunk |
+
+All three use the same 4 × 2114 for data — the chip count doesn't
+change. The 8 × 32 configuration (256 cells, 8-bit address) is
+recommended as the v0 starting point: sufficient concurrency for
+static PE assignment with 4 PEs, and 32 dyadic instructions per
+function chunk avoids forced mid-computation splits.
+
+### Implications for IRAM
+
+32 dyadic entries implies ~55–80 total instructions per function chunk
+(assuming 40–60% dyadic ratio). IRAM should be sized for 128–256
+entries at 24-bit width:
+
+- 128 entries × 24 bits: 4 × 2114 (using 128 of 1024 locations)
+- 256 entries × 24 bits: 6 × 2114 (or reorganise encoding to 32-bit
+  and use 4 × 2114)
+
+---
+
+## 5. The Shared 670 Subsystem: Metadata Cache + SC Register File
+
+### Core Insight
+
+During **dataflow mode**, the PE uses matching store metadata constantly
+but the SC register file is idle (no SC block executing). During **SC
+mode**, the PE uses the register file constantly but the matching store
+is idle (SC block has exclusive PE access; no tokens enter matching).
+
+These two functions can share the same physical 74LS670 chips,
+repurposed by a mode switch.
+
+### Metadata Format
+
+Per matching store entry (4 bits — exact 670 word width):
+
+```
+Bit 3: occupied    (has a first operand been stored?)
+Bit 2: port        (was it left or right operand?)
+Bit 1: gen_hi      (generation counter high bit)
+Bit 0: gen_lo      (generation counter low bit)
+```
+
+Per context slot, the generation counter can optionally be stored
+separately (in the per-slot portion of the 670 address space) or
+replicated per-entry for finer-grained invalidation.
+
+### Configuration: 8 × 74LS670
+
+8 chips in parallel, each providing 4 words × 4 bits. Addressing:
+
+- 2 address bits select the word within each chip (4 words)
+- chip-select logic maps the entry address across the 8 chips
+
+Total capacity: 8 chips × 4 words = 32 entries of 4-bit metadata.
+This is exactly one full context slot (32 entries), or a 32-entry
+write-through cache window into the 256-entry matching store.
+
+In **SC mode**, the same 8 chips provide:
+
+- 32 words × 4 bits = 32 × 4 = 128 bits total
+- Interpreted as: **8 registers × 16 bits** (4 chips per register
+  for width)
+
+This gives 8 SC registers of 16 bits each — sufficient for most
+short SC blocks (the EM-4 had 16 but targeted longer blocks; 8
+covers the common case of 4–8 instruction sequential regions).
+
+### The Predicate Slice
+
+One of the 8 chips can be **permanently dedicated as a predicate
+register** rather than participating in the cache/register-file
+multiplexing. This provides:
+
+- 4 entries × 4 bits = 16 predicate bits, always available
+- Useful for: conditional token routing (SWITCH), loop termination
+  flags, SC block branch conditions, I-structure status flags
+- Does not reduce the register file capacity significantly:
+  7 remaining chips still provide 7 registers × 16 bits in SC mode,
+  or 28 metadata cache entries in dataflow mode
+
+The predicate register is always readable and writable regardless of
+mode, since it's a dedicated chip with its own address/enable lines.
+Instructions can test or set predicate bits without going through the
+matching store or the ALU result path.
+
+### Mode Switching
+
+When transitioning from dataflow mode to SC mode:
+
+1. **Save cached metadata** from the 7 shared 670s (7 × 4 words × 4
+   bits = 112 bits) to spill storage.
+2. **Load initial SC register values** (matched operand pair that
+   triggered the SC block) into the 670s.
+3. **Switch address mux**: 670 address lines now driven by instruction
+   R0/R1/R2 fields instead of matching store entry address.
+4. **Switch IRAM to counter mode**: sequential fetch via incrementing
+   counter rather than token-directed node address.
+
+When transitioning back:
+
+1. **Emit final SC result** as token (last instruction with OUT=1).
+2. **Restore cached metadata** from spill storage to the 670s.
+3. **Switch address mux back** to matching store entry addressing.
+4. **Resume token processing** from input FIFO.
+
+### Spill Storage Options
+
+112 bits (or 128 bits if including the predicate slice) need temporary
+storage during SC block execution.
+
+**Option A: Shift registers.** 2 × 74LS165 (parallel-in, serial-out)
+for save + 2 × 74LS595 (serial-in, parallel-out) for restore. Total:
+4 chips. Save/restore takes ~16 clock cycles each (shifting 112+ bits
+serially at 8 bits per chip per cycle).
+
+**Option B: Dedicated spill 670.** One additional 74LS670 (4 × 4 bits)
+holds 16 bits per save cycle; need ~7 write cycles to save all 7
+chips' contents. Total: 1 chip, ~7 cycles per save/restore.
+
+**Option C: Spill to matching store SRAM.** During SC mode, the
+matching store data SRAM is idle. Write the 670 metadata contents into
+unused matching store SRAM locations (e.g., a reserved region at the
+top of the address space). No extra chips needed. ~7 SRAM write cycles
+to save, ~7 to restore. The SRAM is single-ported but there's no
+contention because nothing else accesses it during mode switch.
+
+**Recommended: Option C.** Zero additional chips. The matching store
+SRAM is guaranteed idle during SC mode, and the metadata only needs
+to survive for the duration of the SC block (typically 4–20
+instructions = a few microseconds). The save/restore overhead of
+~7 cycles per transition is negligible compared to the SC block's
+execution savings (EM-4 data: 23 clocks pure dataflow vs 9 clocks SC
+for Fibonacci, so even with 14 cycles of mode switch overhead, you
+break even at ~7 SC instructions).
+
+### Chip Budget Summary
+
+| Component | Chips | Function |
+|-----------|-------|----------|
+| 7 × 74LS670 | 7 | Shared metadata cache / SC register file |
+| 1 × 74LS670 | 1 | Dedicated predicate register (8 × 1-bit usable or 4 × 4-bit) |
+| ~3 chips | 3 | Address mux, mode control, chip-select decode |
+| 0 chips | 0 | Spill storage (reuse matching store SRAM) |
+| **Total** | **~11** | |
+
+This replaces what would otherwise require separate implementations:
+- Metadata cache alone: ~7 chips (670s) + ~5 chips (tag comparators)
+- SC register file alone: ~4–8 chips (670s)
+- Predicate register alone: ~1 chip
+
+The shared design is fewer chips than either separate subsystem, and
+provides all three functions.
+
+---
+
+## 6. Pipeline Timing by Era
+
+### 1979 (5 MHz, 2114 SRAM)
+
+```
+Matching: 2 cycles (SRAM single-port constraint)
+670 metadata cache: single-cycle on hit, 2-cycle on miss
+SC block throughput: ~1 instruction per clock (670 dual-port)
+Overall token throughput: ~1 token per 3 clocks (pipelined)
+```
+
+### 1982 (5–8 MHz, 6116 SRAM)
+
+```
+Matching: 1 cycle (half-clock split feasible at 5 MHz)
+670 metadata cache: single-cycle (rarely needed, SRAM is fast enough)
+SC block throughput: ~1 instruction per clock
+Overall token throughput: ~1 token per clock (fully pipelined)
+```
+
+### 1984+ (10 MHz, 6264 SRAM)
+
+```
+Matching: 1 cycle (half-clock comfortable)
+SC block throughput: ~1 instruction per clock
+Overall token throughput: ~1 token per clock
+670s primarily useful for SC register file and predicate register
+```
+
+### Integrated (on-chip SRAM, sub-ns access)
+
+```
+Matching: 1 cycle (trivially fast)
+SC block throughput: 1 instruction per clock
+Token throughput: 1 per clock, potentially 2 with banked match store
+670 equivalent: on-chip multi-ported register file, ~200 transistors
+```
+
+---
+
+## 7. Interaction with PE-to-PE Pipelining
+
+When multiple PEs are chained for software-pipelined loops (see
+architecture overview), the per-PE pipeline throughput determines the
+overall chain throughput.
+
+With the pipelined design (1 token per 1–3 clocks depending on era),
+the inter-PE hop cost becomes the critical path for chained execution:
+
+| Interconnect | Hop latency | Viable? |
+|-------------|-------------|---------|
+| Shared bus (discrete build) | 5–8 cycles | Marginal — chain overhead dominates |
+| Dedicated FIFO between adjacent PEs | 2–3 cycles | Worthwhile for tight loops |
+| On-chip wide parallel link (integrated) | 1–2 cycles | Competitive with intra-PE SC block |
+
+For the discrete v0 build, dedicated inter-PE FIFOs (a small 74LS224
+or similar between adjacent PEs, bypassing the shared bus) would enable
+PE chaining at reasonable cost. This is a low-chip-count addition (~2–4
+chips per PE pair) that unlocks software-pipelined loop execution.
+
+---
+
+## 8. The Execution Mode Spectrum
+
+The pipelined PE with SC blocks and predicate register supports a
+spectrum of execution modes, selectable by the compiler per-region:
+
+| Mode | Pipeline behaviour | Throughput | When to use |
+|------|-------------------|-----------|-------------|
+| Pure dataflow | Token → match → fetch → exec → output | 1 token / 1–3 clocks | Parallel regions, independent ops |
+| SC block (register) | Sequential IRAM fetch, 670 register file | ~1 instr / clock | Short sequential regions (≤8 instrs) |
+| SC block + predicate | As above, with conditional skip/branch via predicate bits | ~1 instr / clock | Conditional sequential regions |
+| PE chain (software pipeline) | Tokens flow PE₀→PE₁→PE₂, each PE handles one stage | 1 iteration / PE-pipeline-depth clocks | Loop bodies across PEs |
+| SM-mediated sequential | Tokens to/from SM for memory-intensive work | SM-bandwidth-limited | Array/structure traversal |
+
+The compiler partitions the program graph and selects the best mode for
+each region. This spectrum is arguably more expressive than what a
+modern OoO core offers (which has exactly one mode: "pretend to be
+sequential, discover parallelism at runtime").
+
+---
+
+## 9. Open Items
+
+1. **670 cache tag comparison**: the current design assumes a
+   single-slot cache window (all 32 entries of the active context
+   slot). If the working set frequently spans multiple slots, a proper
+   tag-compared cache may be needed. Evaluate hit rates via the
+   behavioural emulator before committing to hardware.
+
+2. **SC block maximum length**: with 7 registers (after dedicating one
+   670 to predicates), what is the longest SC block the compiler can
+   generate before register pressure forces a spill? Standard graph
+   colouring gives a rough answer; evaluate empirically on target
+   workloads.
+
+3. **Predicate register uses**: document specific instruction
+   encodings for predicate test/set/clear, and how SWITCH instructions
+   interact with predicate bits. The predicate register may subsume
+   some of the cancel-bit functionality planned for token format.
+
+4. **Mode switch latency measurement**: build a cycle-accurate model of
+   the save-to-SRAM / restore-from-SRAM path and determine exact
+   overhead. Target: ≤10 cycles per transition.
+
+5. **Dual-use validation**: simulate the metadata cache hit rate for
+   representative dataflow programs using the behavioural emulator.
+   If hit rates are below ~70%, the metadata cache may not justify its
+   complexity vs simply accepting 2-cycle matching everywhere.

design-notes/sm-and-token-format-discussion.md

···
+# Extended SM Design Discussion & Token Format Rework
+
+Covers SM enhancements, token format rearrangement, DRAM latency context,
+wide pointers, bulk SM operations, bootstrap/EXEC unification, bootstrap
+SM ownership, and presence metadata design.
+
+See `sm-design.md` for the base SM design this builds on.
+See `architecture-overview.md` for module taxonomy and existing token format.
+
+---
+
+## DRAM vs SRAM Latency in the Target Era
+
+Historical context for SM backing store decisions.
+
+### 4116 DRAM (the workhorse of 1979)
+
+The MK4116 (16Kx1) was ubiquitous: ZX Spectrum, Apple II, IBM PC.
+
+```
+Speed grade   Access time (RAS)   Cycle time   Page mode access
+─────────────────────────────────────────────────────────────────
+4116-2        150 ns              320 ns       100 ns
+4116-3        200 ns              375 ns       135 ns
+4116-4        250 ns              410 ns       165 ns
+```
+
+**Access time** = when valid data appears after RAS goes low.
+**Cycle time** = minimum time between the start of one access and start of
+the next. Includes RAS precharge recovery. A new random access cannot
+begin until the full cycle time elapses.
+
+Comparison: 2114 SRAM at 200ns has access time AND cycle time of ~200ns.
+No precharge, no refresh. DRAM is roughly **half the random-access
+throughput** of SRAM at the same clock speed due to cycle time overhead.
+
+The 4116 also needs 128 refresh cycles every 2ms, stealing ~2-3% of
+available bandwidth.
+
+**Page mode** is noteworthy: when accessing multiple locations in the same
+128-bit row, page mode on the 4116-2 drops to 100ns — faster than the
+2114. The row stays open; the controller just strobes new column
+addresses. This is how the C64 and BBC Micro shared DRAM between CPU and
+video on alternate half-cycles.
+
+### The SRAM/DRAM Ratio Over Time
+
+```
+Era      SRAM access   DRAM access   DRAM cycle   Ratio (DRAM/SRAM)
+─────────────────────────────────────────────────────────────────────
+1979     200 ns        200 ns        375 ns       ~1-2x
+1985     70 ns         100 ns        230 ns       ~1.5-3x
+1995     15 ns         60 ns         ~120 ns      ~4-8x
+2005     2 ns          ~50 ns (CAS)  ~100 ns      ~25-50x
+2024     0.5 ns        ~15 ns (CAS)  ~50 ns       ~30-100x
+```
+
+In 1979, DRAM was at most **2x slower** than SRAM for random access.
+Today it's **50-100x slower** relative to on-chip SRAM. The memory wall
+barely existed in 1979.
+
+**Implication for SM:** SM backed by DRAM in 1979 incurs only a 2x
+latency penalty vs SRAM — viable without caching. In a modern version,
+the same architecture is better positioned for the memory wall than
+conventional designs, because dataflow provides natural latency tolerance:
+the PE processes other tokens while waiting for SM responses.
+
+### C64 Memory Architecture Note
+
+Main 64K: 8× 4116 DRAM. Colour RAM: single 2114 SRAM (1K×4, low nybble
+only, 16 colours). The colour RAM was SRAM specifically because it needed
+independent access without fighting the VIC-II for DRAM bus cycles.
+
+---
+
+## 74LS610 Memory Mapper for SM Banking
+
+The 74LS610 is a TI memory mapper chip (originally for TMS9900 family):
+
+- 16 mapping registers, each 12 bits wide
+- 4-bit logical address input (MA0-MA3) selects register
+- 12-bit physical address output (MO0-MO11)
+- The '610 has a **latch control** pin (pin 28) absent from the '612 —
+  outputs can be frozen while register contents change
+- Appeared in PC-AT boards and Nintendo cartridges
+- Internally a multiplexed register file, not dual-port
+
+### SM Address Translation Path
+
+1. Token arrives with structure address
+2. High bits go to '610, select mapping register → 12-bit physical bank
+   (~40-50ns propagation delay, LS family)
+3. Bank bits + low address bits drive DRAM row/column
+4. DRAM access (~200ns access + 375ns cycle for 4116)
+
+The '610 propagation delay is pipelineable — it's a combinational lookup
+that overlaps with DRAM RAS setup. The real cost comes from *changing* a
+mapping register mid-operation (a write cycle to the '610's internal
+registers via the data bus). That is the bank-switch overhead.
+
+### SM Usage Model
+
+Mapping registers are set at load time and mostly left alone. SM
+addresses are global — every PE sees the same SM address space. The
+mapping registers expand physical capacity rather than providing
+per-context isolation.
+
+Bank switching hurts when more live structures exist than fit in the
+directly-mapped physical space. The compiler can hint which structures are
+hot vs cold, and the SM controller can manage the mapping registers
+accordingly: fast path (bank already mapped → straight through) vs slow
+path (bank miss → remap → re-access).
+
+---
+
+## SM Return Routing: Pre-Formed Token Templates
+
+The return routing field in SM READ requests (flit 2) is conceptualized as a
+**pre-formed CM token template**. The SM's result formatter simply latches the
+template, concatenates the read data, and pushes the result to the output.
+No bit-shuffling, no field packing — the requesting CM does all that work
+upfront when constructing the request.
+
+Because the template is a full 16-bit flit carried in flit 2 (or flit 3
+for extended formats), it has enough room to encode any token format whose
+routing information fits in a single flit. In practice this means any
+format OTHER than dyadic narrow can serve as a return route: dyadic wide,
+monadic normal, and monadic inline all fit their routing fields into
+flit 1. The SM does not need to understand the format — it just prepends
+the template as flit 1 and appends the read data as flit 2.
+
+This means SM read results can land directly in a matching store slot as
+one operand of a dyadic instruction. The result does not need to pass
+through an intermediate monadic forwarding step — it can match against
+another token that arrived independently, enabling patterns like "fetch
+value from SM, combine with a locally-computed operand, produce result"
+in a single matching store cycle.
+
+**Implication:** bits cannot be stolen from the return routing field for
+page register selection or other SM-side metadata, because the SM would
+need to parse its own return routing — defeating the purpose of making it
+an opaque blob.
+
+---
+
+## Token Format Rework: 1-Bit SM/CM Split
+
+### Motivation
+
+Eliminating type-11 (system) tokens and moving to a 1-bit SM/CM
+discriminator reclaims 1 bit in the SM flit. This bit can be spent on
+addressing, opcodes, or SM_id width.
+
+### Why Type-11 Can Be Eliminated
+
+Each type-11 subtype can be absorbed into existing types:
+
+- `11+00` (IO): IO module becomes a specialised SM or memory-mapped
+  region within SM address space
+- `11+01` (config/IRAM load): becomes a CM opcode (see IRAM Write below)
+- `11+10` (debug/trace): reserved SM address range or special monadic
+  opcode
+- `11+11` (reserved): not committed
+
+Bootstrap/initial loading uses a dedicated hardware path (see Bootstrap
+section below), not runtime tokens.
+
+### IO as Memory-Mapped SM
+
+The IO module is interacted with like an SM: reads/writes use the
+standard SM token format. I-structure semantics help naturally — a READ
+from an IO device that doesn't have data ready defers, and the response
+arrives when the device is ready. This provides interrupt-driven IO
+without interrupts.
+
+At v0 scale, dedicating one SM_id to IO leaves 3 SMs × 512 = 1536
+structure cells. See "Bootstrap SM Ownership" below for how this interacts
+with the bootstrap path.
+
+### IRAM Write as CM Opcode
+
+From the CM's perspective, an IRAM write is "put this instruction word at
+this IRAM address." It needs no ctx, port, gen, or matching store access.
+Those bits become extra address or data bits.
+
+The CM is also in the best position to know whether it can safely swap out
+a given instruction or whether tokens are in flight for it, enabling
+finer-grained hot-reload at runtime.
+
+### New Token Encoding
+
+```
+═══════════════════════════════════════════════════════════════════
+BIT[15] = 1: SM TOKEN
+═══════════════════════════════════════════════════════════════════
+
+Standard (2 flit):
+  flit 1: [1][SM_id:2][op:3-5][addr:8-10]                     = 16
+  flit 2: [data:16] or [return_routing:16]
+
+  15 bits available. See "SM Opcode Width Options" below.
+
+═══════════════════════════════════════════════════════════════════
+BIT[15:14] = 00: DYADIC WIDE (hot path)
+═══════════════════════════════════════════════════════════════════
+
+  flit 1: [0][0][PE:2][offset:5][ctx:4][port:1][gen:2]        = 16
+  flit 2: [data:16]
+
+  offset:5 = 32 dyadic slots per context (doubled from 16)
+  matching store addr = [ctx:4][offset:5] = 9 bits = 512 cells
+  decode: bit[15]=0 AND bit[14]=0 → two gates
+
+═══════════════════════════════════════════════════════════════════
+BIT[15:13] = 010: MONADIC NORMAL (2 flit)
+═══════════════════════════════════════════════════════════════════
+
+  flit 1: [0][1][0][PE:2][offset:7][ctx:4]                    = 16
+  flit 2: [data:16]
+
+  offset:7 = 128 IRAM slots, unchanged
+  No port, no gen
+
+═══════════════════════════════════════════════════════════════════
+BIT[15:13] = 011: MISC BUCKET (infrequent formats)
+═══════════════════════════════════════════════════════════════════
+
+  flit 1: [0][1][1][PE:2][sub:2][...9 bits...]                = 16
+
+  sub=00: DYADIC NARROW (2 flit, 8-bit data)
+    flit 1: [011][PE:2][00][offset:5][ctx:4]                   = 16
+    flit 2: [data:8][port:1][gen:2][spare:5]                   = 16
+
+  sub=01: IRAM WRITE (2+ flit)
+    flit 1: [011][PE:2][01][iram_addr:7][flags:2]             = 16
+    flit 2: [instruction_word_low:16]                          = 16
+    (flit 3: [instruction_word_high:8][spare:8] if needed)
+    7-bit addr = 128 IRAM slots, full coverage.
+    No ctx/port/gen needed.
+
+  sub=10: MONADIC INLINE (1 flit, trigger)
+    flit 1: [011][PE:2][10][offset:4][ctx:4][spare:1]         = 16
+    No flit 2.
+
+  sub=11: SPARE
+    Reserved. Candidates: extended monadic with wider offset,
+    broadcast/multicast, debug/trace injection.
+```
+
+### Summary Table
+
+```
+prefix   format            flits  offset  ctx  port  gen   vs current
+──────────────────────────────────────────────────────────────────────
+1        SM standard       2      9-10    —    —     —     +1 bit (addr or op)
+00       dyadic wide       2      5 (32)  4    1     2     +1 offset (was 4)
+010      monadic normal    2      7 (128) 4    —     —     unchanged
+011+00   dyadic narrow     2      5 (32)  4    1     2     unchanged
+011+01   IRAM write        2-3    7 (128) —    —     —     NEW
+011+10   monadic inline    1      4 (16)  4    —     —     unchanged
+011+11   (spare)           ?      ?       ?    ?     ?     reserved
+```
+
+### Hot Path Decode
+
+Two bits determine the fast-path pipeline:
+
+- bit[15] splits SM/CM: one gate
+- bit[14] splits dyadic-wide from everything else: one gate
+- the PE can start matching store SRAM read on [ctx:4][offset:5] the
+  instant flit 1 is latched for dyadic-wide tokens (the dominant format)
+- monadic decode adds one more gate at bit[13]
+- the misc bucket is three gates deep, but nothing there is
+  latency-critical
+
+### Dyadic Narrow as Demoted Format
+
+Dyadic narrow carries 8-bit data but still costs two flits. Its main
+advantage is a wider offset field plus spare bits in flit 2. It is less
+broadly useful than dyadic wide (16-bit data, the common case) and
+comfortably shares the misc bucket with IRAM write and monadic inline —
+all three are infrequent relative to the two hot-path formats.
+
+### Monadic Offset Relative Addressing
+
+Dyadic instructions pack into the lowest IRAM offsets (0-15 wide, 0-31
+narrow). Monadic tokens never target those slots. Making monadic offsets
+**relative to the dyadic ceiling** avoids wasting encodings:
+
+```
+wide mode:   16 dyadic slots → monadic base = 16
+  6-bit relative offset → addresses 16-79 (64 monadic slots, all valid)
+
+narrow mode: 32 dyadic slots → monadic base = 32
+  6-bit relative offset → addresses 32-95 (64 monadic slots, all valid)
+```
+
+Hardware cost: since the dyadic ceiling is always a power of 2 (16 or
+32), the base can be OR'd onto the high address bits. One gate plus a
+config bit.
+
+**SC block interaction:** SC blocks need contiguous IRAM space that does
+not respect the dyadic-below-monadic packing rule. The compiler packs SC
+blocks into a separate IRAM region above the monadic ceiling, addressed
+via a base register set on entering SC mode.
+
+### SM Opcode Width Options
+
+With 15 bits available after the SM discriminator bit, the SM_id (2 bits)
+leaves 13 bits split between opcode and address. Three alternatives:
+
+**3-bit fixed:** 8 ops, 10-bit addr (1024 cells). READ, WRITE, ALLOC,
+FREE, CLEAR, READ_INC, READ_DEC, CAS fills it exactly. No headroom, no
+decode complexity.
+
+**4-bit fixed:** 16 ops, 9-bit addr (512 cells). Room for EXT, RAW_READ,
+EXEC, and 5 spare slots. Trivial decode. 11 defined operations with 5
+spare gives comfortable expansion room.
+
+**Variable 3/5:** one decode gate. Common ops get 3-bit opcode + 10-bit
+addr (1024 cells). Rare/special ops get 5-bit opcode + 8-bit payload
+(256 addresses or inline data).
+
+```
+op[2:1] != 11:  6 opcodes × 10-bit addr (1024 cells)
+  READ, WRITE, ALLOC, FREE, CLEAR, EXT
+
+op[2:1] == 11:  extends to 5-bit → 8 opcodes × 8-bit payload
+  READ_INC, READ_DEC, CAS, RAW_READ, EXEC, SET_PAGE, WRITE_IMM, (spare)
+```
+
+**Key insight for variable-width encoding:** not all SM ops are
+`op(address)`. Some are `op(config_value)` or `op()` with no cell
+operand. The 8-bit payload in the restricted tier can be inline data,
+config values, or range counts depending on the opcode:
+
+- EXEC: payload = length/count (base addr in config register)
+- SET_PAGE: payload = page register value
+- WRITE_IMM: 8-bit addr + 8-bit immediate (single-flit small constant
+  writes, feasible if flit 2 is repurposed or omitted)
+- CLEAR_RANGE: base addr + count
+
+---
+
+## Bootstrap and EXEC Unification
+
+### The EXEC Concept
+
+An SM operation that reads from a region of SM address space, **bypasses
+the result token formatter**, and pushes raw data onto the token bus as
+pre-formed tokens.
+
+### Bootstrap via EXEC
+
+At power-on, a small state machine (counter + comparator + a few gates)
+begins reading from a ROM base address. The ROM is mapped into the SM's
+extended address space (directly wired or via '610 mapper). Its contents
+are pre-assembled tokens: IRAM writes, routing config, and everything
+else needed to bring the system alive.
+
+```
+Bootstrap sequence:
+  1. Power on, reset
+  2. Bootstrap state machine starts clocking reads from ROM base
+  3. SM reads ROM, pushes raw bytes onto token bus
+  4. Those bytes ARE tokens — CM IRAM writes, SM config, routing setup
+  5. CMs and SMs see valid tokens on the bus, process normally
+  6. Bootstrap hits stop sentinel, halts
+  7. System is loaded, bootstrap state machine goes idle
+  8. Final token in ROM sequence could be a "go" trigger
+```
+
+Bootstrap hardware: ~5-8 chips (12-bit counter, stop comparator, bus
+driver, trigger logic, mux between bootstrap and runtime address sources).
+
+### Bootstrap Bus Arbitration
+
+During bootstrap, nothing else transmits (nothing is loaded yet). The
+bootstrap SM gets unconditional bus access until completion. A single
+flip-flop ("bootstrap complete," active-low) gates other bus requesters.
+Normal arbitration activates after bootstrap signals done.
+
+### ROM Image Format
+
+The toolchain compiles the program, generates a token stream for loading,
+and packs it into a ROM image. No special bootstrap format or separate
+loader protocol — the ROM contains the same tokens that would flow on the
+bus during normal operation, pre-baked.
+
+**Token ordering in the ROM is critical:** routing config must precede
+compute tokens (so the network knows where to route), IRAM loads must
+precede trigger tokens (so instructions exist before anything fires).
+This is a constraint on the assembler/linker output ordering.
+
+### Runtime EXEC
+
+At runtime, EXEC reuses the same address counter, bus output path, and
+sequencing logic as bootstrap. The differences:
+
+- Triggered by a token instead of a power-on reset signal
+- Address + length come from the token (or from a wide pointer) rather
+  than "start at 0, go until sentinel"
+- Additional hardware: trigger latch, length register (~2 chips)
+
+Runtime EXEC enables:
+
+- **Checkpoint/restore:** snapshot tokens into SM region, reload via EXEC
+- **Code migration:** EXEC a sequence that writes new IRAM to a target
+  PE, updates routing, and re-injects pending tokens
+- **Computed token streams:** a CM builds a token sequence in SM via
+  WRITEs, then triggers EXEC to emit them all at once
+- **Bulk scatter:** pre-formed token templates in SM, EXEC distributes
+  data to PEs (faster than a CM emit loop)
+
+### Bus Bandwidth During EXEC
+
+EXEC monopolises the bus while clocking out tokens. At v0 scale this is
+acceptable. At scale, EXEC should be backpressure-aware — the SM only
+emits when the bus grants access, naturally interleaving with other
+traffic.
+
+### Security Consideration
+
+EXEC allows an SM to inject tokens that look like they came from any
+source, targeting any PE, with any opcode. At v0 this is a non-issue
+(same threat model as a 6502 — all code is trusted). At scale, EXEC
+should be gated behind privilege levels or a config bit controlling which
+SMs can use it.
+
+---
+
+## Bootstrap SM Ownership
+
+### Dedicated Bootstrap SM
+
+One SM (likely SM00) is wired to the system reset signal. On coming out
+of reset, it calls EXEC on a predetermined address in program storage
+(ROM or flash mapped into its extended address space).
+
+The bootstrap program at the reset vector is responsible for:
+
+1. Commanding all other CMs and SMs to clear existing state
+2. Loading the program (IRAM writes, routing config, initial data)
+3. Emitting the initial trigger tokens to start execution
+
+Any program loaded by the bootstrap must **not** issue commands to the
+bootstrap SM as part of its own loading sequence — doing so could
+interfere with the bootstrap process itself.
+
+At runtime, the same EXEC behaviour can be triggered on any SM targeting
+any part of memory. The only thing special about SM00 is the reset-vector
+wiring.
+
+### Should the Bootstrap SM Be Further Specialised?
+
+This is an open question with trade-offs in both directions.
+
+**Arguments for specialisation (SM00 as "IO SM"):**
+
+Some SM opcodes (atomics, alloc/free) don't have meaningful semantics on
+memory-mapped IO addresses. On SM00 (aliased `io` in the assembler), the
+atomic and allocation opcodes could be repurposed for specialised IO
+operations. This avoids wasting opcode space on operations that don't
+apply to IO, and gives the IO subsystem its own instruction vocabulary
+within the existing token format.
+
+SM00 would also be the natural home for program storage (ROM/flash) and
+the serial port, since the bootstrap hardware already requires access to
+external storage.
+
+**Arguments against specialisation:**
+
+Making SM00 special outside the boot process creates a bottleneck. If
+SM00 is the only path to program storage, serial IO, and other
+peripherals, it concentrates traffic. In a system with complex IO
+requirements or significant address space demand, a single special-cased
+SM limits scalability.
+
+The more devices or address space mapped through SM00, the worse the
+contention. Other SMs cannot help share the load because they lack the
+specialised decode logic.
+
+**Middle ground (recommended for v0):**
+
+SM00 is special only at boot (reset vector wiring). At runtime, IO is
+memory-mapped into SM00's address space using the standard SM opcode set.
+Opcode reuse for IO-specific operations is deferred until profiling shows
+the standard opcodes are insufficient. Any SM can perform EXEC at runtime,
+so program loading and code migration are not locked to SM00.
+
+This avoids committing to a specialised instruction set before knowing
+what IO operations actually need hardware support vs what the standard
+read/write/presence-bit model can handle.
+
+---
+
+## Memory Tier Model
+
+Not all addressable storage needs synchronising memory semantics. Treating
+every cell as an I-structure is expensive (presence SRAM, FSM complexity,
+deferred read logic) and unnecessary for many use cases. The SM address
+space should support regions with different semantics tiers, selected by
+address range.
+
+### Tier Definitions
+
+**Tier 0: Raw memory.** No presence bits, no metadata, no I-structure
+semantics. Reads always return whatever is stored; writes always go
+through. No per-cell state means no consistency concerns — this tier can
+be trivially shared across SMs because there is nothing to keep
+synchronised. The SM hardware path for tier 0 is minimal: address decode,
+SRAM/DRAM read/write, done. No FSM, no deferred read register, no
+presence SRAM access.
+
+Use cases: framebuffers, ROM, DMA buffers, lookup tables, program
+storage, any memory region where the programmer accepts "last writer wins"
+semantics or read-only access.
+
+**Tier 1: I-structure memory.** The full presence-bit model.
+EMPTY/RESERVED/FULL/WAITING state per cell, deferred reads, write-once
+semantics with diagnostic on overwrite. Each cell has metadata in the
+presence SRAM. This is the synchronising memory that makes the dataflow
+architecture work — producer-consumer coordination without locks. Must be
+owned by a single SM because the metadata is authoritative.
+
+**Tier 2: Wide/bulk memory.** Tier 1 plus the is_wide tag, sequencer
+support for ITERATE/COPY_RANGE, and bounds checking via wide pointer
+metadata. A superset of tier 1 that enables SM-local bulk operations.
+Same ownership constraints as tier 1.
+
+### Tier Selection by Address Range
+
+For v0, the tier boundary is a fixed address convention. Addresses below
+a threshold are tier 1 (I-structure); addresses above it are tier 0
+(raw). The boundary may be a hardwired constant or a config register. The
+decode logic is one comparator.
+
+The compiler and assembler know the layout and enforce placement:
+I-structure cells go in the tier 1 range, framebuffers and lookup tables
+go in tier 0. The ROM base address (and therefore the EXEC reset vector)
+is always in tier 0 at a fixed location, because the bootstrap hardware
+must know where to start reading without any configuration having
+occurred.
+
+Future upgrade path: **per-page tier tags.** If the '610 mapper is
+present, each mapping register can carry 2 extra bits indicating the tier
+for that page. The mapper already translates logical→physical addresses;
+it additionally outputs "this page is tier 0/1/2" alongside the physical
+address. The SM FSM uses this signal to skip the presence check and
+deferred-read logic for tier 0 pages. Hardware cost: 2 extra bits per
+mapping register and one mux on the presence SRAM read-enable line.
+
+### Implications for Shared Access
+
+Tier 0 regions do not need to be owned by a single SM. If there are no
+presence bits, there is no per-cell state to be inconsistent. Multiple
+SMs can map the same physical DRAM or ROM as tier 0, and concurrent
+access works without coordination — reads are instantaneous, writes are
+last-writer-wins. The hardware cost per SM for tier 0 access is
+essentially zero beyond address decode and the bus interface.
+
+This directly solves the "program storage bottleneck on SM00" problem
+from the bootstrap discussion. If ROM is tier 0 and any SM can map it,
+then any SM can EXEC from it or issue READs to it. SM00 has the reset
+vector wiring for initial bootstrap, but at runtime program storage is
+accessible from any SM. No bottleneck.
+
+For ROM specifically, the path is even simpler: tier 0 read-only. The SM
+does not need write logic for the ROM region. EXEC on ROM is the
+bootstrap path. Regular READs on ROM are just reads — no presence check,
+no state transition, the fastest possible SM path.
+
+---
+
+## Address Space Distribution Across SMs
+
+### The Core Tension
+
+Each SM manages presence bits and metadata for its own cells. This
+requires per-SM ownership of tier 1/2 cells, which inherently segments
+the memory space. The question is how to present this to the programmer
+and how to handle structures that don't fit neatly into one SM's address
+range.
+
+### Option Analysis
+
+**Hard partitioned (current design).** SM_id in the token selects the SM;
+address bits are local to that SM. Each SM owns its cells, its presence
+metadata, everything. The compiler/programmer must know which SM holds
+what.
+
+Advantages: zero contention on metadata, SMs are completely independent,
+simplest hardware. Four SMs running in parallel can service four requests
+simultaneously. Wide pointers and bulk ops work trivially because all
+cells in a structure are SM-local.
+
+Disadvantages: the programmer sees 4 small address spaces instead of one
+large one. A 200-element array must either fit in one SM (consuming nearly
+half its capacity at 512 cells) or be explicitly split across SMs by the
+compiler. No parallelism on accesses within one SM's address range.
+
+**Interleaved.** Low address bits select the SM; high bits select the cell
+within it. The programmer sees a flat address space.
+
+Advantages: flat addressing, automatic load balancing for sequential
+access patterns.
+
+Disadvantages: locality is destroyed. Consecutive elements are on
+different SMs, which breaks wide pointers (cell[N] on SM0, cell[N+1] on
+SM1) and prevents SM-local bulk ops (ITERATE, COPY_RANGE). Wide pointers
+effectively rule out pure interleaving.
+
+**Block interleaved.** Blocks of N cells (16-32) assigned to SMs
+round-robin. Consecutive cells within a block are on the same SM.
+
+Advantages: flat-ish addressing, wide pointers work within blocks, some
+load balancing for large structures. Bulk ops work within a block.
+
+Disadvantages: block boundaries create edge cases for structures that
+straddle two SMs. The compiler must be block-aware for optimal placement.
+
+**Segmented with toolchain abstraction (recommended for v0).** Keep hard
+partitioning in hardware, but provide a toolchain abstraction layer. The
+assembler provides named memory regions mapping to SM_id + local address.
+The compiler handles placement. At runtime, the SM_id bits in the token
+explicitly select the SM, but the programmer writes `STORE array[i]` and
+the toolchain resolves the target.
+
+Advantages: hardware stays simple, programmer does not manually manage SM
+placement, wide pointers and bulk ops work trivially (everything within
+a structure is on one SM). The "address space" is as large as the
+toolchain can represent.
+
+Disadvantages: parallelism requires the compiler to deliberately
+distribute structures across SMs. A hot array on one SM cannot benefit
+from idle SMs. Essentially hard partitioning with better ergonomics.
+
+### Recommended Approach
+
+**v0: segmented with toolchain abstraction.** Hard partitioning is the
+correct hardware choice because independent metadata, no contention, and
+no multi-port reads are prerequisites for the wide pointer and bulk
+operation features. The programmer experience problem is real but solvable
+in the toolchain. The compiler can be smart about placement: arrays that
+will be iterated go on one SM (for ITERATE), independent structures go on
+different SMs (for parallelism), hot accumulators go on SMs not busy with
+bulk ops.
+
+**Scale: block interleaving.** At 8+ SMs with a dedicated CM×SM fabric,
+the network can route based on address bits without needing an explicit
+SM_id in the token. The SM_id effectively becomes the high address bits.
+This is a clean evolution from "explicit SM_id in the token" to "implicit
+SM selection from address bits" without changing the token format — the
+2-3 SM_id bits are simply reinterpreted.
+
+### Cross-SM Wide Pointers
+
+A wide pointer can reference cells on a *different* SM if the base
+address includes an SM_id (or maps to a different SM through the address
+translation layer). When an SM processes an ITERATE on such a pointer, it
+cannot read the target cells locally. Instead, it emits READ tokens to
+the target SM for each element, acting as a "list controller" that
+orchestrates access across the system.
+
+This is slower than SM-local iteration (bus traffic per element instead of
+internal reads) but papers over the distribution from the programmer's
+perspective. The programmer writes ITERATE; the hardware determines
+whether it can run locally or must go remote. Amamiya's SM list operations
+worked on a similar principle.
+
+The resulting access patterns:
+
+```
+Local ITERATE (target cells on same SM):
+  1 ITERATE token + N internal reads + N response tokens  = 2 + 2N flits
+
+Remote ITERATE (target cells on different SM):
+  1 ITERATE token + N remote READs + N responses back     = 2 + 4N flits
+```
+
+Remote iteration is 2× the bus traffic of local iteration, but still
+better than the CM orchestrating each access individually (which would
+also be 4N flits, plus the CM compute overhead per element).
+
+### Tier 0 Regions and Distribution
+
+Tier 0 (raw) memory sidesteps the distribution problem entirely. Because
+there are no presence bits or metadata, tier 0 regions can be shared
+across SMs without ownership constraints. A framebuffer mapped as tier 0
+can be written by any SM, read by any SM, with no coordination overhead.
+The only concern is last-writer-wins semantics, which is acceptable for
+use cases like display buffers, shared lookup tables, and ROM.
+
+This creates a natural split: tier 1/2 memory is partitioned across SMs
+for correctness (metadata ownership), while tier 0 memory is shared for
+convenience and throughput.
+
+---
+
+## Wide Pointers and Bulk SM Operations
+
+### Motivation
+
+Historical SM designs (including Amamiya's) treated SM as dumb storage:
+cells with presence bits, every operation one-cell-at-a-time, CM doing
+all orchestration. Amamiya's SM had CAR/CDR fields per cell for LISP cons
+cells.
+
+The approach here is analogous to Rust's wide pointers: carry length +
+address metadata alongside the cell data. The SM becomes a **smart memory
+controller** that can operate on structures without per-element CM
+round-trips.
+
+Inspired in part by near-data-processing research (e.g. SFU 2022 paper
+on smarter caches, DOI: 10.1145/3470496.3527380).
+
+### Wide Pointer = (address, length)
+
+An SM cell tagged as a "wide pointer" implicitly pairs with the next cell
+to form a `(base_address, length)` tuple. The SM can act on this metadata
+without CM involvement.
+
+### Capabilities Enabled
+
+**Bounded slices:** the SM knows the extent of a structure. Hardware
+bounds checking on READ rejects out-of-range accesses without a CM
+round-trip.
+
+**SM-local iteration (READ_NEXT / ITERATE):** the SM maintains an
+internal cursor. The CM sends "give me the next element," the SM
+increments its pointer, and returns the value. One token in, one token
+out, repeated until exhaustion. The CM does not track the index.
+
+```
+Bus traffic for 64-element array iteration:
+  without bulk ops:  64 READs + 64 responses                = 256 flits
+  with ITERATE:      1 ITERATE + 64 responses                = 130 flits
+```
+
+**SM-local memcpy/memmove (COPY_RANGE):** source and destination slices
+provided, SM handles the copy internally. No per-element tokens on the
+bus.
+
+```
+  without:  64 READs + 64 responses + 64 WRITEs             = 384 flits
+  with:     1 COPY_RANGE + 1 completion token                = 4 flits
+```
+
+**SM-local string ops:** a length-aware SM can perform compare, search,
+and concat on packed byte data (2 chars per 16-bit cell) without per-byte
+CM involvement.
+
+### Cell Type Tag Implementation
+
+**Recommended: tagged cells.** Widen per-cell metadata from 2-bit
+presence to 3+ bits: presence:2 + is_wide:1.
+
+- Cells that are not wide pointers pay zero overhead (is_wide = 0)
+- Wide pointer cells consume 2 cells (the pointer cell + the length/
+  metadata cell)
+- The SM knows to treat them as a unit because of the tag
+- Presence SRAM goes from 2 bits/cell to 3 bits/cell, still trivially
+  fits the same small SRAM chip
+
+Alternatives considered:
+
+- **Paired cells:** even addresses hold data, odd hold metadata. Simple,
+  but halves effective cell count for all cells regardless of use.
+- **Separate metadata SRAM:** a third SRAM plane alongside data and
+  presence. Does not eat cell count but costs additional chips.
+
+Tagged cells are the most flexible option — only wide-pointer cells pay
+the cost of consuming two cells.
+
+### Hardware Reuse: EXEC Sequencer = Bulk Op Engine
+
+The bootstrap/EXEC hardware and the bulk operation engine share nearly
+all their components:
+
+```
+Already present for EXEC:
+  - Address counter
+  - Limit comparator (stop sentinel)
+  - Increment logic (READ_INC/DEC already requires 16-bit incrementer)
+  - Output path to bus (result formatter bypass)
+  - Internal read/write sequencing (FSM)
+
+Additional for bulk ops:
+  - Second address register (destination for COPY_RANGE)
+  - Mode selector (determines per-element action)
+  ~5-6 extra chips on top of the EXEC sequencer
+```
+
+All bulk operations are modes of the same sequencer:
+
+- **EXEC:** read cells, push raw to bus
+- **ITERATE:** read cells, push as formatted response tokens
+- **COPY_RANGE:** read cells, write to other cells internally
+- **CLEAR_RANGE:** write zeros across a cell range
+
+### Wide Pointer as Sequencer Parameter Block
+
+Without wide pointers, every bulk op requires the CM to send base+length
+as part of the command (3-flit tokens minimum; SM latches parameters from
+the token).
+
+With wide pointers, the command is just "ITERATE cell[N]." The SM reads
+cell[N], sees the is_wide tag, reads cell[N+1] for the length, loads the
+sequencer, and runs. A single 2-flit token kicks off an arbitrarily long
+bulk operation.
+
+The limit register IS the length from the wide pointer. The base address
+IS the address from the wide pointer. The wide pointer serves directly as
+the parameter block for SM-internal bulk operations.
+
+### Bus Contention During Bulk Ops
+
+**Backpressure-based (recommended for v0):** the SM only emits when it
+receives bus access, naturally interleaving with other traffic. The
+sequencer pauses when it cannot transmit. This falls out of normal bus
+arbitration and degrades throughput gracefully rather than starving other
+devices.
+
+An alternative is interruptible sequencing with burst length limits (the
+SM processes N elements, yields the bus, resumes later). This adds a
+resume-state register but is probably unnecessary at v0 scale.
+
+### Complexity Boundary
+
+The SM should perform **address arithmetic and counting**, not
+**data-dependent branching on cell values**. Once the SM starts evaluating
+data content (e.g. "if value > threshold, do X"), it has crossed from
+smart memory controller into coprocessor territory and gate count
+escalates.
+
+Acceptable SM-internal decisions:
+
+- Presence state checks (metadata the SM owns)
+- Wide pointer length/bounds checks (structural metadata)
+- Counter increment/compare (sequencer logic)
+
+Belongs in the CM / dataflow graph, not the SM:
+
+- Conditional operations based on data values
+- Arbitrary arithmetic on cell contents
+- Data-dependent control flow
+
+The existing atomic ops (READ_INC, READ_DEC, CAS) do modify data, but
+they are fixed-function single-cell operations, not sequenced bulk
+compute. They remain below the complexity line.
+
+### Road Not Taken: SM Evolution Trajectory
+
+Hypothetical trajectory if someone had cracked the compiler problem circa
+1975:
+
+```
+1975-78:  SM = dumb cells + presence bits (Amamiya baseline)
+1979-82:  SM gains atomic ops, wide pointers (structure-aware memory)
+1983-86:  SM gains bulk sequencer (EXEC/ITERATE/COPY_RANGE)
+1987-90:  SM gets microcode ROM for near-data programs (filter, reduce)
+1992+:    SM becomes a specialised vector unit next to memory
+          (essentially what GPUs independently reinvented)
+```
+
+Compare to the actual historical trajectory: make the CPU faster, add
+cache layers to hide memory latency, add OoO to hide cache miss latency,
+add prefetchers to hide OoO limits — each layer compensating for the
+previous layer's failure to solve data-far-from-compute.
+
+---
+
+## Presence Metadata SRAM Design
+
+### Constraint
+
+Presence metadata must have **single-cycle immediate access**. In the
+historical scenario this means fast SRAM regardless of whether the data
+backing store is DRAM. The presence check determines the FSM's action
+(defer, satisfy, error) and cannot wait for DRAM latency.
+
+### Parallel Access
+
+Presence SRAM and data SRAM share address lines (same address driven to
+both chips simultaneously). The presence result feeds the FSM decision
+logic while the data result waits in a latch. If the FSM decides the data
+is needed (cell is FULL, op is READ), it is already available. If not
+(cell is EMPTY, defer), the data latch is simply ignored.
+
+For historical DRAM backing: the DRAM data read can be speculative —
+kicked off in parallel with the presence check and cancelled or ignored if
+the cell turns out to be EMPTY.
+
+### Per-Cell Metadata Candidates
+
+**Checked on every operation (fast path):**
+
+- Presence state: 2 bits (EMPTY/RESERVED/FULL/WAITING)
+- is_wide tag: 1 bit (SM needs this before deciding whether to also read
+  the next cell)
+
+**Checked on most operations (likely fast path):**
+
+- Type tag: 1-2 bits (scalar, wide pointer, packed bytes — avoids wasted
+  reads or misinterpretation of cell contents)
+- Write-once flag: 1 bit (hard error on overwrite, distinct from FULL
+  which permits overwrite with a diagnostic indicator)
+
+**Checked selectively (possibly fast path):**
+
+- Owner/source: 2 bits (which CM "owns" this cell — for future access
+  control)
+- Refcount indicator: 1 bit (flag that this cell uses atomic semantics,
+  allowing ref-counted and non-ref-counted cells to coexist)
+
+### Recommended: 4 Bits Per Cell
+
+`presence:2 + is_wide:1 + spare:1`
+
+At 512 cells this is 256 bytes — trivially fits any small SRAM chip.
+Using a byte-wide SRAM chip means bits 4-7 are physically present whether
+used or not. Committing 4 bits with 4 spare avoids needing to change the
+presence SRAM layout when write-once enforcement or type tags are added
+during testing.
+
+---
+
+## Open Design Questions
+
+1. **SM opcode width** — 3-bit fixed (maximum address range), 4-bit fixed
+   (maximum opcodes, simplest decode), or variable 3/5 (both benefits, one
+   extra decode gate)? Depends on how much the 512 vs 1024 cell
+   difference matters in practice.
+
+2. **Wide pointer cell format** — is (base_addr, length) in two
+   consecutive cells sufficient, or should the metadata cell also carry a
+   type/tag byte? e.g. cell[N] = base_addr, cell[N+1] = length |
+   element_type.
+
+3. **EXEC stop condition** — sentinel value in the data stream, or length
+   register preloaded from a wide pointer or command? Sentinel is simpler
+   for bootstrap (no length needed); a length register is safer for
+   runtime EXEC (no risk of data accidentally matching the sentinel).
+
+4. **Bulk op completion signalling** — when ITERATE or COPY_RANGE
+   finishes, does the SM emit a completion token? Could reuse the return
+   routing from the original request to send a "done" signal that fires
+   the next node in the dataflow graph.
+
+5. **Bulk ops on non-FULL cells** — if ITERATE reads a cell in WAITING
+   state (an I-structure not yet fulfilled), should the sequencer stall
+   per-cell, skip the cell, or error? Per-cell stalling risks blocking
+   the sequencer indefinitely.
+
+6. **IRAM write multi-flit handling** — if instruction words are wider
+   than 16 bits, IRAM write needs 3 flits. The misc bucket sub=01 format
+   has 2-bit flags that could signal 2-flit vs 3-flit mode. Depends on
+   final instruction word width.
+
+7. **IO address space allocation** — if IO becomes memory-mapped SM,
+   which SM_id is reserved? Is IO mapped into a specific address range
+   within SM00, or distributed across SMs?
+
+8. **Relative monadic offset + SC blocks** — SC blocks need their own
+   IRAM region. Does the relative offset mechanism require a third base
+   register for SC mode, or does SC bypass offset translation entirely
+   (using raw IRAM addresses from a sequential counter)?
+
+9. **Bootstrap SM specialisation** — should SM00 repurpose unused opcodes
+   (atomics, alloc/free) for IO-specific operations, or should it use the
+   standard SM opcode set with IO handled purely through read/write and
+   presence-bit semantics? Specialisation provides richer IO control;
+   uniformity avoids creating a traffic bottleneck and simplifies the
+   hardware.
+
+10. **Tier boundary configuration** — hardwired address split between
+    tier 0 (raw) and tier 1 (I-structure), or config register settable at
+    load time? Hardwired is simplest; a config register allows different
+    programs to allocate different amounts of raw vs synchronised memory.
+    The ROM base / reset vector address is always fixed regardless.
+
+11. **Tier 0 write semantics** — should tier 0 cells support writes from
+    any SM (true shared memory), or only from the "home" SM with other SMs
+    issuing remote write requests? True sharing is simpler but
+    last-writer-wins can cause subtle bugs if two CMs write the same cell
+    concurrently. Remote writes add a serialisation point.
+
+12. **Cross-SM ITERATE** — remote iteration is 2× the bus traffic of
+    local iteration. Is this acceptable, or should the compiler be
+    required to keep iterable structures SM-local? If required, the
+    cross-SM path could be omitted from v0 and treated as an error.
+
+13. **Per-page tier tags with '610** — the '610 mapper has 12-bit output
+    registers. Are spare bits available for tier tags, or does the full
+    12-bit output go to physical addressing? If the physical address space
+    does not need all 12 bits, the high bits could encode tier.

design-notes/sm-design.md

···
 # Dynamic Dataflow CPU — SM (Structure Memory) Design
 
 Covers the SM interface protocol, operation set, banking scheme, address
-space extension, and hardware architecture.
+space extension, memory tiers, wide pointers, bulk operations,
+EXEC/bootstrap, and hardware architecture.
 
 See `architecture-overview.md` for module taxonomy and token format.
 See `network-and-communication.md` for how SM connects to the bus.
 See `bus-architecture-and-width-decoupling.md` for bus width rationale
 and SM internal datapath confirmation.
+See `sm-and-token-format-discussion.md` for extended discussion of design
+decisions including DRAM latency context, bootstrap unification, and
+address space distribution.
 
 ## Role
 
-SM stores structured data (arrays, lists, heap) and performs operations on
-it. it is NOT used for I/O mapping — I/O lives in the type-11 subsystem
-(see `io-and-bootstrap.md`).
+SM stores structured data (arrays, lists, heap), performs operations on it,
+and provides memory-mapped IO.
 
-SM is **synchronising memory** — not just a data store. each cell has
+SM is **synchronising memory** — not just a data store. Tier 1 cells have
 presence state (empty/full), and reads to empty cells are deferred until
-a write arrives. this gives implicit producer-consumer synchronisation
+a write arrives. This gives implicit producer-consumer synchronisation
 without locks or explicit message-passing: the write *is* the signal.
-this is the dataflow architecture's answer to shared mutable state.
+This is the dataflow architecture's answer to shared mutable state.
 
-from a CM's perspective: send a type-10 request, get a result token back
-eventually. split-phase, asynchronous relative to the requesting CM. a
-READ may return immediately (cell is full) or later (cell is empty,
+**IO is memory-mapped into SM address space.** An SM (typically SM00 at v0)
+maps IO devices into its address range. I-structure semantics provide
+natural interrupt-free IO: a READ from an IO device that has no data defers
+until data arrives, triggering the receiving node in the dataflow graph.
+
+From a CM's perspective: send a bit[15]=1 request, get a CM result token
+back eventually. Split-phase, asynchronous relative to the requesting CM.
+A READ may return immediately (cell is full) or later (cell is empty,
 deferred until written).
 
 See `em4-analysis.md` for context on why dedicated synchronising memory
···
 info in the bits that are unused by that operation type. SM does not
 maintain persistent per-request state — result packets are self-addressed.
 
-**Exception**: deferred reads. when a READ hits an empty cell, the SM
+**Exception**: deferred reads. When a READ hits an empty cell, the SM
 stashes the return routing in a deferred read register and sends the
-result later when a WRITE arrives. this is the one case where the SM
-holds pending state. see "Deferred Read Register" section below.
+result later when a WRITE arrives. This is the one case where the SM
+holds pending state. See "Deferred Read Register" section below.
 
-### Request Formats (type 10, 2-flit, received on AN)
+### Request Format (bit[15]=1, 2-flit standard)
 
 All SM requests arrive as 2 flits on the 16-bit bus and are reassembled
 at the SM input FIFO before processing.
 
 ```
 Flit 1 (common to all SM ops):
-  [type:2=10][SM_id:2][op_base:3][addr/op_ext:1][addr_low:8]     = 16 bits
+  [1][SM_id:2][op_base:3][addr/op_ext:2][addr_low:8]              = 16 bits
+
+  15 bits available after the SM discriminator bit. SM_id (2 bits) selects
+  the target SM. The remaining 13 bits encode opcode and address using
+  variable-width encoding:
+
+  When op[2:1] != 11: 3-bit opcode, 10-bit addr (1024 cells)
+  When op[2:1] == 11: extends to 5-bit opcode, 8-bit payload (256 cells)
 
-  When op_base[2:1] != 11: bit[8] is addr MSB → 3-bit op, 9-bit addr
-  When op_base[2:1] == 11: bit[8] is opcode extension → 4-bit op, 8-bit addr
-  See "Bus Encoding" in Operation Set section for full decode table.
+  Decode signal: op[2] AND op[1] — one gate.
 
 Flit 2 varies by operation:
 
···
     Write data to address. No DN response unless cell was WAITING
     (deferred read satisfied — result token emitted using saved routing).
 
-  READ / CLEAR / ALLOC / FREE: [return routing:16]
-    Flit 2 carries return routing (destination CM, offset, ctx, port)
-    instead of data. Exact bit packing TBD — 16 bits available for
-    ret_CM + ret_offset + ret_ctx + ret_port.
+  READ / CLEAR / ALLOC / FREE: [return_routing:16]
+    Flit 2 carries a **pre-formed CM token template**. The SM's result
+    formatter latches this template, prepends it as the result's flit 1,
+    and appends read data as flit 2. No bit-shuffling — the requesting
+    CM does all format work upfront. The SM treats this as an opaque
+    16-bit blob.
     (CLEAR/ALLOC/FREE may not need return routing — if no result token
     is emitted, flit 2 could be omitted or carry flags instead. TBD.)
 
-  READ_INC / READ_DEC: [return routing:16]
-    Same as READ. atomic ops always return the old value.
+  READ_INC / READ_DEC: [return_routing:16]
+    Same as READ. Atomic ops always return the old value.
 
   CAS — compare-and-swap:
     Requires 3-flit extended format to carry expected_value, new_value,
···
 ```
 
 **3-flit extended addressing mode**: for access to external RAM or
-memory-mapped I/O address spaces, a 3-flit structure token provides
-wider addresses at the cost of one extra flit cycle:
-```
-  flit 1: [type:2=10][SM_id:2][op:3][flags:9]                     = 16 bits
-  flit 2: [extended_addr:16]                                       = 16 bits
-  flit 3: [data:16] or [return routing:16]                         = 16 bits
-```
-This is distinct from the type-11 extended structure path — it stays
-within the type-10 traffic class but uses a flag or reserved opcode to
-signal 3-flit format.
+memory-mapped IO address spaces, a 3-flit SM token provides wider
+addresses at the cost of one extra flit cycle. The EXT opcode (one of
+the 3-bit tier) signals 3-flit format.
 
-### Result Format (on DN, repackaged as type 00 or 01)
+### Result Format (on DN, pre-formed CM token)
 
-SM extracts return routing from the request's flit 2 and constructs a
-standard 2-flit compute token:
+SM uses the pre-formed CM token template from the request's flit 2 as the
+result's flit 1, and appends the read data as flit 2:
 
 ```
-Result (2 flits, type 00 or 01):
-  flit 1: [type:2][ret_CM:2][...12 bits: ret addr, ctx, port...]  = 16 bits
-  flit 2: [fetched_data:16]                                        = 16 bits
+Result (2 flits):
+  flit 1: [return_routing:16]   (opaque template from original request)
+  flit 2: [fetched_data:16]
 ```
 
-The requesting CM specified where this result should land (which PE,
-offset, context slot, port). SM just repackages. the result looks like
-any other token arriving at the CM — the CM doesn't know or care that
-it came from SM.
+The template can encode any CM token format whose routing fits in 16 bits:
+dyadic wide, monadic normal, or monadic inline. This means SM read results
+can land directly in a matching store slot as one operand of a dyadic
+instruction — no intermediate monadic forwarding step needed.
 
-**Open question**: the return routing in READ requests needs to include
-enough information to form a complete flit-1 for the result token. If
-the result is type 01 (monadic), no generation counter is needed and 16
-bits of return routing may suffice. If type 00 (dyadic), gen bits are
-needed. Options:
-- (a) SM results are always monadic (type 01) — simplest, SM results
-  bypass matching and go straight to instruction fetch
-- (b) Return routing in flit 2 includes gen bits, reducing space for
-  other return fields
-- (c) The requesting CM stores the gen locally and the SM result matches
-  without it
-Option (a) remains simplest — SM results always feed monadic instruction
-inputs.
+**Implication:** bits cannot be stolen from the return routing field for
+SM-side metadata, because the SM would need to parse its own return
+routing — defeating the purpose of keeping it opaque.
 
 ## Cell State Model (I-Structure Semantics)
 
···
 - **FREE**: transitions any→EMPTY. if cell was WAITING, cancels the
   deferred read (same as CLEAR). deferred to post-v0.
 
-### Presence State Hardware
+### Presence Metadata Hardware
 
-2 bits per cell. at 512 cells = 1024 bits = 128 bytes. implementation
-options:
+4 bits per cell: `[presence:2][is_wide:1][spare:1]`
 
-- **Small SRAM** alongside the data SRAM. addressed in parallel, read/
-  written on every operation. one 8-bit-wide SRAM chip covers 4 cells
-  per byte → 128 bytes easily fits.
-- **Register file** if cell count is small enough. 512 × 2 bits is too
-  big for discrete flip-flops, but a small SRAM works fine.
+- **presence:2** — EMPTY/RESERVED/FULL/WAITING (checked on every operation)
+- **is_wide:1** — tags this cell as part of a wide pointer pair. The SM
+  checks this before deciding whether to also read the next cell for
+  length metadata. See "Wide Pointers" section below.
+- **spare:1** — reserved. Candidates: write-once flag, type tag, owner ID.
+
+At 1024 cells = 4096 bits = 512 bytes. Using a byte-wide SRAM chip means
+bits 4-7 are physically present whether used or not. Committing 4 bits
+with 4 spare avoids needing to change the presence SRAM layout when
+additional per-cell metadata is added during testing.
+
+Implementation:
+
+- **Small SRAM** alongside the data SRAM. Addressed in parallel, read/
+  written on every operation. One 8-bit-wide SRAM chip covers 2 cells
+  per byte (4 bits each) → 256 bytes easily fits.
 - Must support single-cycle read-modify-write (read state, decide action,
-  write new state) within one clock. achievable if the state SRAM access
+  write new state) within one clock. Achievable if the state SRAM access
   time is less than half the clock period (read in first half, write in
   second half — same half-clock RMW technique as the EM-4 matching stage).
 
···
 
 ```
 Deferred Read Register:
-  [valid:1][cell_addr:9][return_routing:16]  = 26 bits
+  [valid:1][cell_addr:10][return_routing:16]  = 27 bits
 ```
 
-- **valid**: set when a READ hits an EMPTY/RESERVED cell. cleared when the
+- **valid**: set when a READ hits an EMPTY/RESERVED cell. Cleared when the
   deferred read is satisfied (WRITE to the target cell) or cancelled
   (CLEAR/FREE to the target cell).
-- **cell_addr**: which cell this deferred read is waiting on. compared
-  against incoming WRITE addresses to detect satisfaction.
-- **return_routing**: the 16 bits from the original READ's flit 2. used
-  to construct the result token when the deferred read is satisfied.
+- **cell_addr**: which cell this deferred read is waiting on (10-bit
+  address for 1024-cell range). Compared against incoming WRITE addresses
+  to detect satisfaction.
+- **return_routing**: the 16 bits from the original READ's flit 2 (the
+  pre-formed CM token template). Used as flit 1 of the result token
+  when the deferred read is satisfied.
 
 ### Deferred Read Satisfaction
 
 On every WRITE, the SM checks: `valid == 1 AND write_addr == cell_addr`.
-if true:
+If true:
 
 1. Store the write data in the cell (normal WRITE behaviour).
 2. Transition cell state to FULL.
-3. Construct result token using saved return_routing + written data.
-4. Emit result token via DN.
-5. Clear the deferred read register (valid = 0).
+3. Emit result token: flit 1 = saved return_routing, flit 2 = written data.
+4. Clear the deferred read register (valid = 0).
 
-Hardware cost: one 9-bit comparator (cell_addr vs write_addr), one AND
-gate (valid AND addr_match), one 26-bit register. trivial — maybe 3-4
+Hardware cost: one 10-bit comparator (cell_addr vs write_addr), one AND
+gate (valid AND addr_match), one 27-bit register. Trivial — maybe 3-4
 TTL chips total.
 
 ### Depth-1 Limitation and Backpressure
···
 
 ### Bus Encoding (flit 1: variable-width opcode)
 
-On the 16-bit bus, flit 1 of a type-10 token is:
+On the 16-bit bus, flit 1 of an SM token is:
 
 ```
-  [type:2=10][SM_id:2][op_base:3][addr/op_ext:1][addr:8]  = 16 bits
+  [1][SM_id:2][op_base:3][op_ext/addr:2][addr:8]           = 16 bits
 ```
 
-The interpretation of bit[8] depends on op_base[2:1] (the top two bits
-of the 3-bit base opcode):
+15 bits available after the SM discriminator. SM_id (2 bits) selects the
+target SM. The remaining 13 bits encode opcode and address using
+variable-width encoding.
+
+The interpretation of the 2 bits after op_base depends on op_base[2:1]:
 
 ```
-op_base[2:1] = 00, 01, or 10:
-  bit[8] is part of the address. opcode = 3 bits, address = 9 bits (512 cells).
+op[2:1] != 11:
+  3-bit opcode, 10-bit addr (1024 cells).
+  The 2 extension bits are the high address bits.
 
-op_base[2:1] = 11:
-  bit[8] is an opcode extension. opcode = 4 bits, address = 8 bits (256 cells).
+op[2:1] == 11:
+  Extends to 5-bit opcode, 8-bit payload (256 cells or inline data).
+  The 2 extension bits are opcode extension.
 ```
 
-Decode signal: `op_base[2] AND op_base[1]` — one gate.
+Decode signal: `op[2] AND op[1]` — one gate.
 
 ### Opcode Table (bus encoding)
 
 ```
-op_base  bit[8]  bus opcode  internal op  addr bits  name
-─────────────────────────────────────────────────────────────
-  000      a        000       0000         9 (512)   READ
-  001      a        001       0001         9          WRITE
-  010      a        010       0010         9          ALLOC
-  011      a        011       0011         9          FREE
-  100      a        100       0100         9          CLEAR
-  101      a        101       0101         9          (spare)
-  110      0        1100      0110         8 (256)   READ_INC
-  110      1        1101      0111         8          READ_DEC
-  111      0        1110      1000         8          CAS
-  111      1        1111      1001         8          (spare)
+op_base  ext   bus opcode  internal op  addr bits  name
+─────────────────────────────────────────────────────────────────
+  000     aa      000       0000        10 (1024)  READ
+  001     aa      001       0001        10          WRITE
+  010     aa      010       0010        10          ALLOC
+  011     aa      011       0011        10          FREE
+  100     aa      100       0100        10          CLEAR
+  101     aa      101       0101        10          EXT (3-flit mode)
+  110     00      11000     0110         8 (256)   READ_INC
+  110     01      11001     0111         8          READ_DEC
+  110     10      11010     1000         8          CAS
+  110     11      11011     1001         8          RAW_READ
+  111     00      11100     1010         8          EXEC
+  111     01      11101     1011         8          SET_PAGE
+  111     10      11110     1100         8          WRITE_IMM
+  111     11      11111     1101         8          (spare)
 ```
 
-'a' = address bit (part of 9-bit address).
+'aa' = address bits (part of 10-bit address).
 
-**Rationale for restricted-address ops**: READ_INC, READ_DEC, and CAS are
-atomic operations typically used on specific cells (refcounts, semaphores,
-locks) that the compiler places deliberately. restricting them to the
-lower 256 cells per SM is acceptable — the compiler knows this and
-allocates atomic-access cells in the lower range.
+**Tier 1 ops (3-bit, full address range):** READ, WRITE, ALLOC, FREE,
+CLEAR reach the full 1024-cell address space. EXT signals a 3-flit
+token for extended addressing (external RAM, wide addresses).
+
+**Tier 2 ops (5-bit, restricted address/payload):** atomic operations
+(READ_INC, READ_DEC, CAS) are restricted to 256 cells — the compiler
+places atomic-access cells in the lower range. EXEC, SET_PAGE, and
+WRITE_IMM use the 8-bit payload field for non-address data (length,
+page register value, small immediate).
 
-Full-address ops (READ, WRITE, ALLOC, FREE, CLEAR) need to reach the
-entire address space since they manage all cells.
+**Key insight for variable-width encoding:** not all SM ops are
+`op(address)`. Some are `op(config_value)` or `op()` with no cell
+operand. The 8-bit payload in the restricted tier can be inline data,
+config values, or range counts depending on the opcode:
 
-One spare slot in each range for future expansion. the full-address spare
-(101) could become RAW_READ (non-blocking, non-deferring read — returns
-data or empty indicator without registering a deferred read) if needed.
-not committed for v0 but the slot is reserved.
+- EXEC: payload = length/count (base addr in config register)
+- SET_PAGE: payload = page register value
+- WRITE_IMM: 8-bit addr, flit 2 carries immediate data
+- RAW_READ: non-blocking read, returns data or empty indicator without
+  registering a deferred read. Useful for polling and diagnostics.
 
 ### Direct Path Encoding (future)
 
···
 a direct path is added, the bus adapter and direct path adapter both
 feed into the same internal command bus via a mux.
 
-### Extended Bus Encoding (3-flit type-10)
+### Extended Bus Encoding (3-flit SM token via EXT opcode)
 
 For operations that need wider addresses or additional data (CAS with
-both expected and new values), 3-flit type-10 tokens carry the full
+both expected and new values), 3-flit SM tokens (via EXT opcode) carry the full
 4-bit opcode in the extra flit:
 
 ```
···
 ### Banking
 
 - Start with 2 banks (1 address bit selects bank) for v0
-- 9-bit address = 512 cells per SM = 1KB at 16-bit data width
+- 10-bit address = 1024 cells per SM = 2KB at 16-bit data width
 - Each bank is one SRAM chip with room to spare
 - Banking allows pipelining: one bank can be reading while another is
   being written (for RMW ops, or overlapping independent requests)
···
 enough for the atomic operations. hardware cost: 16-bit incrementer +
 16-bit comparator + mux. ~10-15 TTL chips.
 
-**Presence state SRAM**: 2 bits per cell. 512 cells = 128 bytes. one small
-SRAM chip or a section of a larger SRAM, addressed in parallel with the
-data SRAM. must support half-clock read-modify-write (read state in first
-half, write new state in second half) for single-cycle operation.
+**Presence metadata SRAM**: 4 bits per cell (presence:2 + is_wide:1 +
+spare:1). 1024 cells = 512 bytes. One small SRAM chip addressed in
+parallel with the data SRAM. Must support half-clock read-modify-write
+(read state in first half, write new state in second half) for
+single-cycle operation.
 
-**Deferred read register**: one 26-bit register (valid:1 + cell_addr:9 +
-return_routing:16). one 9-bit comparator for addr matching against
+**Deferred read register**: one 27-bit register (valid:1 + cell_addr:10 +
+return_routing:16). One 10-bit comparator for addr matching against
 incoming WRITEs. ~3-4 TTL chips total.
 
-**Result formatter**: extracts return routing from the original request's
-flit 2 (or from the deferred read register for deferred reads), combines
-with read data, constructs a 2-flit type 00/01 result token. this is
-where the SM-to-DN format conversion happens. Output serialiser splits
-the formed token into flits for bus transmission.
+**Result formatter**: latches the pre-formed CM token template from the
+original request's flit 2 (or from the deferred read register for deferred
+reads), emits it as flit 1 of the result, and appends read data as flit 2.
+The SM does not parse or modify the template — it is an opaque blob. Output
+serialiser splits the formed token into flits for bus transmission.
 
 ## Address Space Extension
 
-The 9-bit address in the compact structure token (type 10) gives only
-512 cells per SM. three mechanisms to extend it:
+The 10-bit address in the standard SM token gives 1024 cells per SM for
+tier-1 ops (3-bit opcode). Three mechanisms extend this further:
 
-### 1. Page Register (recommended for v0)
+### 1. Page Register
 
-- SM has a writable config register: "page base" (8-16 bits)
-- 9-bit token address is treated as offset, added to page base
+- SM has a writable config register set via SET_PAGE opcode
+- 10-bit token address is treated as offset, added to page base
 - Gives up to 64K+ addressable cells per SM
-- CM sets the page with a WRITE to a reserved config address before
-  issuing a burst of reads/writes to a region
+- CM sets the page before issuing a burst of reads/writes to a region
 - Hardware cost: ~3 chips (latch for page register + adder)
 - Programming model: familiar bank-switching, like 8-bit micros
 - Tradeoff: page switch costs one extra token; compiler batches accesses
···
 
 ### 2. Banking as Implicit Address Bits
 
-- SM_id field (2 bits) gives 4 SMs = 4 x 512 = 2K cells system-wide
+- SM_id field (2 bits) gives 4 SMs = 4 x 1024 = 4K cells system-wide
 - Not contiguous from a programming perspective, but compiler can
   distribute data structures across SMs for both capacity and parallelism
 - Essentially free — already in the token format
 - Combine with page registers for 4 x 64K = 256K cells system-wide
 
-### 3. Extended Structure Tokens (via type 10 3-flit or type 11)
+### 3. Extended SM Tokens (3-flit via EXT opcode)
 
-- Use 3-flit type-10 tokens (see request format above) or type-11 (system)
-  packets with a structure-extended subtype for structure ops needing wide
-  addresses
-- Full 16-24 bit address space, at the cost of one extra flit cycle
-- Use for: large heap, external RAM chip, memory-mapped I/O space
-- Compact 2-flit type-10 tokens remain the fast path for common/local
-  accesses
+- The EXT opcode (3-bit tier) signals a 3-flit SM token with full 16-bit
+  address in flit 2, data/return-routing in flit 3
+- Full 16-bit address space per SM, at the cost of one extra flit cycle
+- Use for: large heap, external RAM, memory-mapped IO address ranges
+- Standard 2-flit tokens remain the fast path for common/local accesses
 
 ### Practical Address Space with All Three Combined
 
-- Fast path (type 10 + page register): 64K per SM, 2-flit token
-- Medium path (type 10 across SMs): 4 x 64K = 256K, 2-flit token
-- Slow path (3-flit type 10 or type 11 extended): up to 16M+ with wide
-  addresses, 3-flit token
+- Fast path (standard + page register): 64K per SM, 2-flit token
+- Medium path (across SMs): 4 x 64K = 256K, 2-flit token
+- Slow path (3-flit EXT): up to 64K per SM with wide addresses, 3-flit
 
 ## V0 Test Plan
 
···
       result token emitted)
     - WRITE on FULL cell: verify overwrite + diagnostic indicator
   - **Variable opcode decode tests**:
-    - Verify READ/WRITE/ALLOC/FREE/CLEAR reach full 512-cell range
-    - Verify READ_INC/READ_DEC/CAS restricted to lower 256 cells
-    - Verify op_base[2:1]=11 decode correctly separates opcode
-      extension from address
+    - Verify READ/WRITE/ALLOC/FREE/CLEAR reach full 1024-cell range
+    - Verify READ_INC/READ_DEC/CAS/EXEC etc. restricted to lower 256 cells
+    - Verify op[2:1]=11 decode correctly separates opcode extension
+      from address
+
+---
+
+## Memory Tiers
+
+SM address space supports regions with different semantics, selectable by
+address range. The tier is not encoded in the token — it is determined by
+the target address within the SM.
+
+### Tier 0: Raw Memory
+
+No presence bits. SRAM read/write only. Suitable for bulk data that does
+not need synchronisation (image buffers, DMA staging areas, ROM).
+
+- READ always returns immediately (no deferral)
+- WRITE always succeeds
+- Presence metadata bits are ignored / not maintained
+- Allocated by compiler or loader, not by ALLOC/FREE
+- Address range: configurable, typically the top of the SM address space
+
+### Tier 1: I-Structure Memory
+
+Standard I-structure semantics with presence tracking. This is the default
+operating mode described throughout this document.
+
+- READ on EMPTY/RESERVED cell defers until WRITE
+- WRITE transitions cell to FULL
+- ALLOC/FREE manage the free list
+- Full presence metadata (4 bits per cell)
+- Address range: configurable, typically the bulk of SM address space
+
+### Tier 2: Wide/Bulk Memory
+
+Extends tier 1 with wide pointer support. Cells tagged with `is_wide=1`
+in presence metadata are treated as the base of a (pointer, length) pair:
+the cell itself holds the data pointer, the next cell holds the length.
+
+- READ checks `is_wide` and returns either 1 cell (normal) or 2 cells
+  (wide pointer pair — requires 3-flit result token or two result tokens)
+- WRITE to a wide cell writes both pointer and length
+- Enables ITERATE, COPY_RANGE, and EXEC to take wide pointers as arguments
+- Address range: overlaps with tier 1 (any tier 1 cell can be marked wide)
+
+### Tier Boundary Configuration
+
+- Boundaries are set by config registers (SET_PAGE or a dedicated config
+  mechanism) during bootstrap
+- The SM's address decoder checks the incoming address against tier
+  boundaries to select behaviour
+- Hardware cost: 1-2 comparators + a mux on the presence metadata path
+- v0 can use a fixed split (e.g., lower 768 = tier 1, upper 256 = tier 0)
+  and defer runtime-configurable boundaries
+
+> **Design status:** tiers are directionally decided. Exact address range
+> splits, tier 2 wide-read mechanics, and interaction between tiers and
+> page registers are still being refined.
+
+---
+
+## Wide Pointers and Bulk Operations
+
+### Wide Pointer Format
+
+A wide pointer occupies 2 consecutive SM cells:
+
+```
+Cell N:     [data_pointer:16]   (base address in SM or external memory)
+Cell N+1:  [length:16]          (element count)
+```
+
+Cell N has `is_wide=1` in its presence metadata. The SM knows to read
+both cells when servicing a READ on a wide cell.
+
+Wide pointers are the parameter format for bulk operations. A CM does not
+iterate over SM contents directly — it sends an SM operation with a wide
+pointer, and the SM's sequencer engine handles the iteration internally.
+
+### EXEC
+
+EXEC reads pre-formed tokens from a contiguous region of SM and pushes
+them onto the bus. The SM becomes a token source — effectively an
+autonomous injector.
+
+```
+EXEC request:
+  flit 1: [...EXEC opcode...][count:8]
+  flit 2: [base_addr from config register or wide pointer]
+```
+
+The SM's sequencer reads `count` 2-cell entries starting at `base_addr`.
+Each entry is a pre-formed 2-flit token (flit 1 in cell N, flit 2 in
+cell N+1). The sequencer emits them onto the bus in order.
+
+**Bootstrap use:** on system reset, SM00 is wired to execute EXEC on a
+predetermined ROM address. The ROM contents are pre-formed IRAM write
+tokens and seed tokens — everything needed to load the system. No external
+microcontroller needed for self-hosted boot. See "SM00 Bootstrap" below.
+
+**Hardware reuse:** the EXEC sequencer (address counter, limit comparator,
+increment logic, output path to bus) is the same hardware needed for
+ITERATE and COPY_RANGE. Building EXEC for bootstrap gives bulk operations
+nearly for free.
+
+### ITERATE
+
+Reads each cell in a range and emits a result token for each. Takes a
+wide pointer (base + length). The SM's sequencer walks the range,
+constructing result tokens using a pre-loaded return routing template.
+
+### COPY_RANGE
+
+Copies a contiguous range of cells from one SM region to another (or to
+a different SM). Takes source wide pointer and destination base. Useful
+for structure copying, GC compaction.
+
+> **Design status:** ITERATE and COPY_RANGE are directionally committed.
+> Exact token format for range parameters, interaction with deferred reads
+> in the target range, and atomicity guarantees are still being refined.
+
+---
+
+## SM00 Bootstrap
+
+### Reset Behaviour
+
+SM00 has dedicated wiring to the system reset signal. On reset:
+
+1. SM00's sequencer triggers EXEC on a predetermined ROM base address
+2. The ROM region contains pre-formed tokens: IRAM write tokens to load
+   PE instruction memories, followed by seed tokens to start execution
+3. SM00 emits these tokens onto the bus in order
+4. PEs receive IRAM writes and load their instruction memories
+5. Seed tokens fire and execution begins
+
+This is the only hardware specialisation of SM00 — the reset vector
+wiring. At runtime, SM00 behaves as a standard SM with standard opcodes.
+
+### ROM Mapping
+
+The bootstrap ROM is mapped into SM00's address space (tier 0 — raw
+memory, no presence bits). It can be:
+
+- Physical ROM/EEPROM on SM00's address bus
+- A region of SM00's SRAM pre-loaded by an external microcontroller
+  (development/prototyping)
+- Flash memory accessed via page register for larger images
+
+### Future Specialisation (not committed)
+
+SM00 could be further specialised for IO:
+
+- Atomic/alloc opcodes could be repurposed for IO-specific operations
+  (e.g., READ_INC becomes "read UART with auto-acknowledge")
+- Memory-mapped IO devices occupy a reserved address range within SM00
+- SM00 could have additional interrupt-sensing hardware that triggers
+  token emission on external events
+
+This is documented as a design option but **not committed for v0**. The
+standard SM opcodes are sufficient for basic IO via I-structure semantics:
+READ from an IO-mapped address defers until the IO device writes data.
+
+---
+
+## Presence-Bit Guided IRAM Writes
+
+The matching store's presence bitmap provides information about whether
+any dyadic instruction slot has a pending (half-matched) operand. During
+IRAM writes, the PE can check the presence bits for the IRAM page being
+overwritten:
+
+- If all presence bits for slots in that page are clear, no tokens are
+  pending — the page can be safely overwritten without drain delay
+- If any presence bit is set, the PE knows tokens are in flight for
+  that instruction and can either wait or discard the stale operand
+
+This enables more targeted IRAM replacement than the blanket drain
+protocol. Instead of draining the entire PE, only the affected page needs
+attention. The valid-bit page protection mechanism
+(`bus-architecture-and-width-decoupling.md`) remains the safety net, but
+presence-bit checking can eliminate unnecessary stalls.
+
+---
 
 ## Open Design Questions
 
 1. **CAS multi-flit handling** — how does the request FIFO handle 3-flit
-   ops? does it buffer all flits before dispatching, or pipeline them?
+   ops? Does it buffer all flits before dispatching, or pipeline them?
    CAS needs expected_value, new_value, AND return routing — that's 48
    bits of payload beyond the opcode/address. 3 flits minimum.
 2. **Page register per-CM or global?** — if multiple CMs access the same
    SM, do they share a page register (contention) or each have their own
-   (more hardware, more config)? probably global for v0.
+   (more hardware, more config)? Probably global for v0.
 3. **Banking vs pipeline depth** — with 2 banks, can we overlap a read to
-   bank 0 with a write to bank 1? worth the control complexity for v0?
-   presence state SRAM complicates this — is presence per-bank or shared?
-   if shared, it serialises cross-bank operations. if per-bank, each bank
-   needs its own presence SRAM. probably shared for v0 (simpler).
+   bank 0 with a write to bank 1? Worth the control complexity for v0?
+   Presence state SRAM complicates this — is presence per-bank or shared?
+   If shared, it serialises cross-bank operations. If per-bank, each bank
+   needs its own presence SRAM. Probably shared for v0 (simpler).
 4. **SRAM chip selection** — specific part numbers, speed grades, package.
-   needs to match the target clock frequency. presence state SRAM needs
+   Needs to match the target clock frequency. Presence metadata SRAM needs
    to be at least as fast as data SRAM (same access path).
-5. **RAW_READ** — non-blocking read that returns data or empty indicator
-   without registering a deferred read. useful for polling and diagnostics.
-   opcode slot reserved (internal 0101) but not committed. implement if
-   needed during testing.
-6. **Atomic ops on non-FULL cells** — READ_INC/READ_DEC/CAS on EMPTY or
-   WAITING cells is currently undefined. options: error, stall, or treat
-   as zero. error is safest for v0.
-7. **Direct path input mux** — when direct path is added, the SM needs a
-    mux between bus input and direct input feeding the internal command
-    bus. arbitration policy TBD (direct path priority? round-robin?).
+5. **Atomic ops on non-FULL cells** — READ_INC/READ_DEC/CAS on EMPTY or
+   WAITING cells is currently undefined. Options: error, stall, or treat
+   as zero. Error is safest for v0.
+6. **Direct path input mux** — when direct path is added, the SM needs a
+   mux between bus input and direct input feeding the internal command
+   bus. Arbitration policy TBD (direct path priority? round-robin?).
+7. **Wide pointer read format** — does a READ on a wide cell return two
+   separate result tokens or one 3-flit result token? Two tokens is
+   simpler (reuse existing result formatter), 3-flit is more atomic.
+8. **Tier boundary mechanism** — fixed at build time, config register,
+   or address-range comparator? Fixed is simplest for v0.
+9. **ITERATE return template** — how is the return routing template
+   supplied for iterated results? Pre-loaded config register? Part of
+   the ITERATE request? Template per element or shared?
+10. **SM00 ROM size and mapping** — how large is the bootstrap ROM? What
+    address range? How does it interact with the page register?

design-notes/token-format-migration.md

···
+# Token Format Migration Reference
+
+Reference for migrating the emulator and assembler from the old 2-bit type
+field token format to the 1-bit SM/CM split with prefix encoding.
+
+## Old → New Token Type Mapping
+
+| Old Type | Old Format | New Prefix | New Format |
+|----------|-----------|------------|------------|
+| type 00, W=1 (dyadic wide) | `[00][PE:2][W:1=1][offset:4][ctx:4][port:1][gen:2]` | 00 | `[00][PE:2][offset:5][ctx:4][port:1][gen:2]` |
+| type 00, W=0 (dyadic narrow) | `[00][PE:2][W:1=0][offset:5][ctx:4][spare:2]` | 011+00 | `[011][PE:2][00][offset:5][ctx:4]` |
+| type 01, I=0 (monadic normal) | `[01][PE:2][I:1=0][offset:7][ctx:4]` | 010 | `[010][PE:2][offset:7][ctx:4]` |
+| type 01, I=1 (monadic inline) | `[01][PE:2][I:1=1][offset:4][ctx:4][spare:3]` | 011+10 | `[011][PE:2][10][offset:4][ctx:4][spare:1]` |
+| type 10 (structure) | `[10][SM_id:2][op:3][addr:9]` | 1 | `[1][SM_id:2][op:3-5][addr:8-10]` |
+| type 11, sub 00 (IO) | `[11][00][device:3][register:4][R/W:1][pad:4]` | 1 (SM token to IO-mapped SM) | standard SM token to SM00 IO-mapped address |
+| type 11, sub 01 (config write / IRAM load) | `[11][01][target_PE:2][flags:2][addr:8]` | 011+01 | `[011][PE:2][01][iram_addr:7][flags:2]` |
+
+## Key Changes
+
+### Dyadic Wide: offset widened from 4 to 5 bits
+- Old: 16 dyadic slots per context
+- New: 32 dyadic slots per context
+- Matching store grows from 256 cells (8-bit addr) to 512 cells (9-bit addr)
+
+### SM Tokens: 1-bit prefix, variable opcode width
+- Old: type=10 (2-bit), 3-bit op, 9-bit addr
+- New: bit[15]=1, 3-bit op + 10-bit addr (common) or 5-bit op + 8-bit addr (rare)
+- Extra opcode slot gained: 15 bits available vs old 12
+
+### SysToken / CfgToken / IOToken: eliminated
+- `SysToken` → removed entirely
+- `CfgToken` → IRAM write functionality moves to CM misc-bucket (prefix 011+01)
+- `LoadInstToken` → absorbed into IRAM write token handling in PE
+- `RouteSetToken` → absorbed into IRAM write token handling (or deferred)
+- `IOToken` → IO operations become standard SM tokens to SM00
+
+### SM Opcode Table: variable 3/5 encoding
+- Old: 3-bit fixed with 1-bit addr/ext split → 4-bit max, 8 or 9-bit addr
+- New: 3-bit (10-bit addr) or 5-bit (8-bit addr), discriminated by op[2:1]
+- New opcodes available: EXEC, SET_PAGE, WRITE_IMM, RAW_READ
+
+### SM Presence Metadata: widened to 4 bits
+- Old: 2-bit (presence only)
+- New: 4-bit (presence:2 + is_wide:1 + spare:1)
+
+## Emulator Changes Required
+
+### tokens.py
+- Remove `SysToken`, `CfgToken`, `LoadInstToken`, `RouteSetToken`, `IOToken`
+- Update `SMToken` to support variable opcode width
+- Consider adding `IRAMWriteToken` as a `CMToken` subclass
+
+### emu/pe.py
+- Handle IRAM write tokens as a CM token subclass instead of CfgToken
+- Update matching store sizing if testing with 5-bit offset
+
+### emu/sm.py
+- Add new opcodes (EXEC, SET_PAGE, WRITE_IMM, RAW_READ)
+- Widen presence metadata to 4 bits
+- Add is_wide support
+
+### emu/network.py
+- Update `System.inject()` / `System.send()` routing to use 1-bit SM/CM
+  split instead of isinstance checks on SysToken/CfgToken
+- Remove IOToken routing
+
+### cm_inst.py
+- Add new SM opcodes to `MemOp` enum
+- Remove `CfgOp` enum if CfgToken is eliminated
+
+## Assembler Changes Required
+
+### asm/codegen.py
+- Update token stream generation to use new prefix encoding
+- Replace CfgToken generation with IRAM write token generation
+- Update SM token generation for variable opcode width
+
+### asm/ir.py
+- May need to represent IRAM write operations differently

docs/design-plans/2026-02-26-token-migration.md

···
+# Token Format Migration Design
+
+## Summary
+
+This design plan migrates the OR1 dataflow CPU emulator and assembler from an older token encoding scheme to a cleaner one. In the old scheme, the system used a 2-bit type field to distinguish four categories of token: CM (computation), SM (structure memory), IO, and a "system" catch-all that handled IRAM loading, routing configuration, and other control operations. That system category is being eliminated. IO is folded into the SM address space (the IO module becomes a memory-mapped region on SM0), and IRAM loading becomes a new CM token subtype called `IRAMWriteToken`. The result is a simpler 1-bit discriminator: a token is either headed for a Structure Memory unit or a Computation Module, with no special cases in the network router.
+
+Alongside the routing simplification, the Structure Memory gains a two-tier address model. Addresses below a configurable boundary (default 256) retain the existing I-structure semantics — presence tracking, deferred reads, write-once enforcement, and atomic operations. Addresses at or above that boundary become raw shared storage (T0): no presence checking, no deferral, and a single store shared across all SM instances. A new EXEC opcode reads pre-formed tokens from T0 and injects them directly into the network, providing both the system bootstrap path (loading programs from ROM at reset) and a runtime mechanism for bulk token emission. The migration is implemented bottom-up — type definitions first, then emulator core, then assembler and tools, then test updates — with each phase building on the previous.
+
+## Definition of Done
+
+Migrate the OR1 emulator, assembler, and supporting tools from the old 2-bit type field token format to the 1-bit SM/CM split with prefix encoding, as specified in the updated design notes. The old token hierarchy (SysToken, CfgToken, LoadInstToken, RouteSetToken, IOToken) is eliminated. SM gains memory tier support (T0 shared raw storage, T1 per-SM I-structure) and new opcodes. All existing tests pass (updated as needed) and new tests cover the changed functionality.
+
+Specifically:
+
+- **tokens.py**: Remove SysToken, CfgToken, IOToken, LoadInstToken, RouteSetToken. Add IRAMWriteToken as a CMToken subclass. DyadToken retains `wide: bool` field.
+- **cm_inst.py**: Remove CfgOp enum. Extend MemOp with new opcodes (EXEC, SET_PAGE, WRITE_IMM, RAW_READ, EXT) as a flat internal enum (no encoding tier enforcement).
+- **emu/sm.py**: T0/T1 memory tier split. T0 is a shared `list[Token]` across all SMs, with a configurable boundary (default: address 256). New SM opcodes implemented (at minimum EXEC for bootstrap, RAW_READ). Presence metadata widened to 4 bits (presence:2 + is_wide:1 + spare:1).
+- **emu/pe.py**: Handle IRAMWriteToken instead of CfgToken/LoadInstToken. Remove RouteSetToken handling.
+- **emu/network.py**: Simplify routing to 1-bit SM/CM isinstance check. Remove IOToken/CfgToken routing.
+- **asm/**: Update codegen to emit IRAMWriteToken. Remove all CfgOp references. Add T0 boundary awareness for SM address allocation.
+- **dfgraph/**: Update CfgOp category handling.
+- **All tests pass.**
+
+## Acceptance Criteria
+
+### token-migration.AC1: Old token types removed
+- **token-migration.AC1.1 Success:** `tokens.py` has no SysToken, CfgToken, IOToken, LoadInstToken, or RouteSetToken classes
+- **token-migration.AC1.2 Success:** `cm_inst.py` has no CfgOp enum
+- **token-migration.AC1.3 Success:** No module in the codebase imports any deleted type
+
+### token-migration.AC2: IRAMWriteToken works
+- **token-migration.AC2.1 Success:** IRAMWriteToken routes to target PE via network (isinstance CMToken)
+- **token-migration.AC2.2 Success:** PE receives IRAMWriteToken and writes instructions to IRAM at the specified offset
+- **token-migration.AC2.3 Success:** PE executes instructions loaded via IRAMWriteToken correctly
+- **token-migration.AC2.4 Failure:** IRAMWriteToken with invalid target PE raises or is dropped
+
+### token-migration.AC3: MemOp enum updated
+- **token-migration.AC3.1 Success:** MemOp contains EXEC, EXT, SET_PAGE, WRITE_IMM, RAW_READ, CLEAR with correct tier grouping
+- **token-migration.AC3.2 Success:** ALLOC, FREE remain in tier 1 (3-bit); CLEAR in tier 2 (5-bit)
+- **token-migration.AC3.3 Success:** Assembler mnemonic mapping includes all new opcodes
+
+### token-migration.AC4: SM T0/T1 tier split
+- **token-migration.AC4.1 Success:** SM operations on addresses below tier_boundary use I-structure semantics (presence tracking, deferred reads)
+- **token-migration.AC4.2 Success:** SM WRITE to T0 address stores data without presence checking
+- **token-migration.AC4.3 Success:** SM READ on T0 address returns immediately (no deferral)
+- **token-migration.AC4.4 Success:** T0 storage is shared — all SMs reference the same T0 store
+- **token-migration.AC4.5 Failure:** I-structure ops (CLEAR, ALLOC, FREE, atomics) on T0 address produce error
+- **token-migration.AC4.6 Edge:** Tier boundary is configurable via SMConfig; default is 256
+
+### token-migration.AC5: EXEC opcode
+- **token-migration.AC5.1 Success:** EXEC reads Token objects from T0 starting at given address and injects them into the network
+- **token-migration.AC5.2 Success:** Injected tokens are processed normally by target PEs/SMs
+- **token-migration.AC5.3 Success:** EXEC can load a program (IRAM writes + seed tokens) from T0 that executes correctly
+- **token-migration.AC5.4 Edge:** EXEC on empty T0 region is a no-op
+
+### token-migration.AC6: Presence metadata widened
+- **token-migration.AC6.1 Success:** SMCell has is_wide field (default False)
+- **token-migration.AC6.2 Success:** Existing I-structure behaviour unchanged (is_wide=False path)
+
+### token-migration.AC7: Assembler updated
+- **token-migration.AC7.1 Success:** Token stream mode emits IRAMWriteToken (not LoadInstToken)
+- **token-migration.AC7.2 Success:** Token stream mode does not emit RouteSetToken
+- **token-migration.AC7.3 Success:** Direct mode (PEConfig/SMConfig) still works
+- **token-migration.AC7.4 Success:** Assembler round-trip (serialize -> parse -> assemble) works with updated types
+
+### token-migration.AC8: All tests pass
+- **token-migration.AC8.1 Success:** `python -m pytest tests/ -v` exits with zero failures
+
+## Glossary
+
+- **Token**: The fundamental unit of data and control in OR1. Carries a value and a destination address; computation fires when all required tokens for an instruction arrive.
+- **CM (Computation Module)**: A processing element in the dataflow array. Receives tokens, matches operand pairs, executes IRAM instructions, and emits result tokens.
+- **SM (Structure Memory)**: A memory controller with I-structure semantics. Manages presence state per cell, handles deferred reads, and coordinates producer-consumer synchronisation without locks.
+- **DyadToken / MonadToken**: The two standard CM token subtypes. Dyadic instructions require two operands (matched before firing); monadic require one.
+- **IRAMWriteToken**: New CM token subtype introduced by this migration. Carries a block of instructions and a target IRAM address. Replaces LoadInstToken.
+- **IRAM**: Instruction RAM. Each PE has a small local memory storing the instructions it executes when a matching pair fires. Loaded at startup or patched at runtime via IRAMWriteToken.
+- **SysToken / CfgToken / LoadInstToken / RouteSetToken / IOToken**: The old token types being deleted. Together they formed the "system" category (type-11 in the old 2-bit encoding).
+- **I-structure**: A single-assignment memory cell with four states: EMPTY, RESERVED, FULL, WAITING. A READ on an empty cell defers until a WRITE arrives.
+- **T0 (tier 0)**: Raw shared storage in the SM address space. No presence bits, no deferred reads. Shared across all SM instances. Used for program storage and the EXEC bootstrap region.
+- **T1 (tier 1)**: The per-SM I-structure region of SM address space, below the tier boundary. Full presence tracking and deferred-read semantics.
+- **EXEC opcode**: A new SM operation that reads Token objects from a T0 region and injects them into the network. Used for system bootstrap and runtime bulk token emission.
+- **Tier boundary**: A configurable address (default: 256) that divides T0 from T1 within an SM's address space.
+- **MemOp**: The enum in `cm_inst.py` listing all SM opcodes. This migration adds EXEC, SET_PAGE, WRITE_IMM, RAW_READ, and EXT.
+- **CfgOp**: The enum being deleted. Listed configuration opcodes (LOAD_INST, ROUTE_SET) that backed the old CfgToken mechanism.
+- **Matching store**: The per-PE 2D array that holds one half of a dyadic token pair while waiting for the other. Indexed by context slot and IRAM offset.
+- **SimPy**: A Python discrete-event simulation library. OR1's emulator is implemented as SimPy processes communicating via SimPy Stores.
+- **Frozen dataclass**: A Python dataclass with `frozen=True`, making instances immutable and hashable. All token types use this pattern.
+- **Lark**: A Python parsing toolkit used to implement the dfasm grammar.
+- **dfasm**: The assembly language for OR1 dataflow graphs. Translated by the assembler into emulator configuration and token streams.
+- **dfgraph**: The interactive graph renderer for dfasm files. FastAPI server with TypeScript/Cytoscape.js frontend.
+
+## Architecture
+
+Bottom-up migration: change type definitions first (`tokens.py`, `cm_inst.py`),
+then fix all consumers (emulator, assembler, graph renderer, tests).
+
+### Token Hierarchy (new)
+
+```
+Token(target: int)
+├── CMToken(Token) — offset, ctx, data
+│   ├── DyadToken(CMToken) — port, gen, wide
+│   ├── MonadToken(CMToken) — inline
+│   └── IRAMWriteToken(CMToken) — instructions: tuple[ALUInst | SMInst, ...]
+└── SMToken(Token) — addr, op, flags, data, ret
+```
+
+`IRAMWriteToken` inherits `CMToken` so network routing (`isinstance(token, CMToken)`)
+sends it to PEs without special cases. The `offset` field serves as `iram_addr`;
+`ctx` and `data` are set to 0 (unused but satisfying the frozen dataclass contract).
+
+`SysToken`, `CfgToken`, `LoadInstToken`, `RouteSetToken`, `IOToken` are deleted.
+`DyadToken` retains `wide: bool` — the prefix distinction (dyadic wide vs narrow)
+is an encoding detail, not a semantic one at the emulator level.
+
+### MemOp Enum (new)
+
+Flat sequential enum. The tier 1 / tier 2 grouping documents the intended hardware
+encoding but is not enforced in the emulator:
+
+```
+Tier 1 (3-bit opcode, 10-bit addr — full 1024-cell range):
+  READ=0, WRITE=1, EXEC=2, ALLOC=3, FREE=4, EXT=5
+
+Tier 2 (5-bit opcode, 8-bit payload — 256-cell range):
+  CLEAR=6, RD_INC=7, RD_DEC=8, CMP_SW=9, RAW_READ=10,
+  SET_PAGE=11, WRITE_IMM=12
+```
+
+EXEC is in the 3-bit tier because it needs full address range to reach T0 at high
+addresses. CLEAR is in the 5-bit tier because it is purely an I-structure operation
+(presence state reset) that only applies to T1 cells in lower address space.
+
+`CfgOp` enum is deleted entirely. IRAM writes are identified by
+`isinstance(token, IRAMWriteToken)`.
+
+### SM Memory Tier Model
+
+SM address space splits into two tiers at a configurable boundary (default: 256):
+
+- **T1 (below boundary):** Per-SM I-structure cells with presence tracking, deferred
+  reads, atomic ops. SM_id is conceptually part of the address — each SM owns its
+  own T1 space independently. Current `list[SMCell]` model, unchanged.
+
+- **T0 (at/above boundary):** Shared raw storage across all SMs. No presence tracking,
+  no deferred reads. Modelled as a single `list[Token]` referenced by all SM instances.
+  T0 is the same physical address space regardless of which SM receives the request.
+
+T0 is initially a list of Token objects (not bytes/words) to avoid encoding/decoding
+in the emulator. EXEC iterates T0 and injects tokens into the network. Future work
+will swap T0 to `list[int]` (16-bit words) when modelling programs that access T0
+as normal data.
+
+**T0 operations:** WRITE stores into T0 (no presence check). EXEC reads from T0 and
+injects tokens. All I-structure-specific operations (CLEAR, ALLOC, FREE, atomics)
+on T0 addresses are errors. READ on T0 returns immediately (no deferral).
+
+**EXEC flow:** SM receives `SMToken(op=EXEC, addr=start)`, iterates `t0_store[start:]`,
+calls `system.send(token)` for each entry. SM holds a reference to the `System` object
+(set by `build_topology()`).
+
+### Presence Metadata
+
+`SMCell` gains `is_wide: bool = False` for the widened 4-bit presence metadata
+(presence:2 + is_wide:1 + spare:1). The spare bit is unused. `Presence` enum values
+are unchanged (EMPTY/RESERVED/FULL/WAITING).
+
+### Network Routing
+
+`System._target_store()` simplifies to:
+
+```
+SMToken  → sms[token.target].input_store
+CMToken  → pes[token.target].input_store
+```
+
+No special cases for CfgToken, IOToken, or any other subtype. `IRAMWriteToken`
+routes to PEs automatically as a CMToken subclass.
+
+### PE Token Handling
+
+The PE's `_run()` loop replaces:
+```
+isinstance(token, CfgToken) → _handle_cfg()
+```
+with:
+```
+isinstance(token, IRAMWriteToken) → _handle_iram_write()
+```
+
+`_handle_iram_write` writes `token.instructions` into IRAM at `token.offset`.
+`RouteSetToken` handling is deleted (route restriction dropped; full mesh is the
+v0 default). Route restriction will return later via a different mechanism when
+multi-cluster topologies are needed.
+
+### Assembler Token Emission
+
+`asm/codegen.py` token stream mode currently emits:
+`SM init → ROUTE_SET → LOAD_INST → seeds`
+
+New ordering:
+`SM init → IRAM writes → seeds`
+
+`RouteSetToken` emission is removed. `LoadInstToken` emission becomes
+`IRAMWriteToken` emission with `target=pe_id`, `offset=iram_addr`, `ctx=0`,
+`data=0`, `instructions=(...)`.
+
+All `CfgOp` references removed from `asm/opcodes.py`, `asm/lower.py`, and
+`asm/codegen.py`. New MemOp members added to mnemonic mapping in `opcodes.py`.
+
+### dfgraph Category Handling
+
+`dfgraph/categories.py` removes `isinstance(op, CfgOp)` branch from `categorise()`.
+New MemOp values (EXEC, SET_PAGE, etc.) either fall into the existing SM category
+or a new "control" subcategory.
+
+## Existing Patterns
+
+Investigation found the following patterns in the codebase:
+
+- **Token hierarchy** follows frozen dataclass inheritance (`tokens.py`). New
+  `IRAMWriteToken` follows the same pattern.
+- **SM operations** use `match token.op:` dispatch in `_run()` loop (`emu/sm.py`).
+  New opcodes follow this pattern.
+- **Network routing** uses `isinstance` dispatch (`emu/network.py`). Simplified
+  routing follows the same pattern with fewer branches.
+- **PE config handling** uses `isinstance` dispatch for token subtypes (`emu/pe.py`).
+  `IRAMWriteToken` replaces `CfgToken` in this dispatch.
+- **Assembler codegen** constructs token objects directly (`asm/codegen.py`).
+  `IRAMWriteToken` replaces `LoadInstToken`/`RouteSetToken` construction.
+- **Config types** use frozen dataclasses (`emu/types.py`). `SMConfig` gains
+  `tier_boundary` field following the same pattern.
+
+No new patterns are introduced. All changes follow existing conventions.
+
+## Implementation Phases
+
+<!-- START_PHASE_1 -->
+### Phase 1: Type Definitions
+
+**Goal:** Update token hierarchy and instruction set enums to the new format.
+
+**Components:**
+- `tokens.py` — delete SysToken/CfgToken/IOToken/LoadInstToken/RouteSetToken; add IRAMWriteToken
+- `cm_inst.py` — delete CfgOp enum; update MemOp with new opcodes and sequential values
+- `sm_mod.py` — add `is_wide: bool` field to SMCell
+
+**Dependencies:** None (first phase).
+
+**Done when:** Type definitions compile. Importing `tokens` and `cm_inst` does not
+error. All downstream breakage is expected and addressed in subsequent phases.
+<!-- END_PHASE_1 -->
+
+<!-- START_PHASE_2 -->
+### Phase 2: Emulator Core
+
+**Goal:** Update emulator to use new token types and add SM memory tier support.
+
+**Components:**
+- `emu/types.py` — add `tier_boundary: int = 256` to SMConfig
+- `emu/sm.py` — T0/T1 dispatch based on address vs tier_boundary; T0 operations (WRITE, READ, EXEC); accept `t0_store` and `system` references; add EXEC implementation; unimplemented new opcodes raise error
+- `emu/pe.py` — replace CfgToken/LoadInstToken/RouteSetToken handling with IRAMWriteToken; remove `_handle_cfg`; add `_handle_iram_write`
+- `emu/network.py` — simplify `_target_store` to SMToken/CMToken isinstance; create shared T0 store in `build_topology`; pass T0 store and System reference to all SMs
+- `emu/__init__.py` — update exports if needed
+
+**Dependencies:** Phase 1 (type definitions).
+
+**Done when:** Emulator processes IRAMWriteToken correctly. SM handles T0/T1 split.
+EXEC reads from T0 and injects tokens. Existing emulator behaviour for T1 operations
+is preserved. Tests covering these behaviours pass.
+<!-- END_PHASE_2 -->
+
+<!-- START_PHASE_3 -->
+### Phase 3: Assembler and Tools
+
+**Goal:** Update assembler and dfgraph to use new types.
+
+**Components:**
+- `asm/codegen.py` — emit IRAMWriteToken instead of LoadInstToken/RouteSetToken; remove ROUTE_SET from token stream ordering; remove CfgOp import
+- `asm/opcodes.py` — remove CfgOp from MNEMONIC_TO_OP and type-aware containers; add new MemOp mnemonics (exec, set_page, write_imm, raw_read, ext, clear updated value)
+- `asm/lower.py` — remove CfgOp from opcode() return type
+- `dfgraph/categories.py` — remove CfgOp isinstance branch; handle new MemOp values
+
+**Dependencies:** Phase 1 (type definitions).
+
+**Done when:** Assembler produces IRAMWriteToken in token stream mode. All assembler
+pipeline stages work with updated types. dfgraph categorises new opcodes. Tests pass.
+<!-- END_PHASE_3 -->
+
+<!-- START_PHASE_4 -->
+### Phase 4: Test Updates and New Coverage
+
+**Goal:** Update all broken tests and add coverage for new functionality.
+
+**Components:**
+- `tests/test_pe.py` — delete RouteSetToken tests; update LoadInstToken tests to IRAMWriteToken
+- `tests/test_codegen.py` — update CfgToken/RouteSetToken/LoadInstToken assertions to IRAMWriteToken
+- `tests/test_integration.py` — update TestTask5CfgTokenLoadInst to use IRAMWriteToken
+- `tests/test_e2e.py` — update CfgToken isinstance check to IRAMWriteToken
+- `tests/test_opcodes.py` — remove CfgOp assertions; add new MemOp assertions
+- `tests/test_dfgraph_categories.py` — remove TestCategoriseCfgOp; add new MemOp tests
+- `tests/conftest.py` — update Hypothesis strategies if they generate old token types
+- New tests for: T0/T1 tier split, EXEC opcode, IRAMWriteToken routing, T0 boundary enforcement
+
+**Dependencies:** Phases 2 and 3 (emulator and assembler updated).
+
+**Done when:** `python -m pytest tests/ -v` passes with zero failures. New tests
+cover T0/T1 split, EXEC, and IRAMWriteToken routing.
+<!-- END_PHASE_4 -->
+
+<!-- START_PHASE_5 -->
+### Phase 5: Documentation
+
+**Goal:** Update project documentation to reflect new token format.
+
+**Components:**
+- `CLAUDE.md` — update Token Hierarchy, Architecture Contracts, and Module Dependency Graph sections
+- `asm/CLAUDE.md` — update Dependencies and Invariants sections (remove CfgOp/RouteSetToken/LoadInstToken references, add IRAMWriteToken)
+- `dfgraph/CLAUDE.md` — update category references if present
+
+**Dependencies:** Phase 4 (all code changes complete and tested).
+
+**Done when:** CLAUDE.md files accurately describe the current codebase state. No
+references to deleted types remain in documentation.
+<!-- END_PHASE_5 -->
+
+## Additional Considerations
+
+**Route restriction (deferred):** RouteSetToken and route restriction are removed in
+this migration. Route restriction will return in a future design when multi-cluster
+(4-CM cluster) topologies are needed, likely as a misc-bucket subtype (011+11) or a
+PE config register mechanism.
+
+**T0 evolution:** T0 is initially modelled as `list[Token]` for simplicity. When
+programs need to access T0 as normal data (framebuffers, lookup tables), T0 will
+migrate to `list[int]` (16-bit words) with token serialisation/deserialisation.
+This is a separate future design.
+
+**Unimplemented opcodes:** SET_PAGE, WRITE_IMM, RAW_READ, and EXT exist as MemOp
+enum members but raise NotImplementedError if they reach the SM's run loop. They are
+placeholders for future SM features and ensure the assembler can parse them.

tokens.py

···
 from dataclasses import dataclass
-+from typing import Optional
+from typing import Optional
 
 from cm_inst import ALUInst, CfgOp, MemOp, Port, SMInst