nonbinary.computer
OR-1 dataflow CPU sketch
docs: add test plan for PE frame-based redesign
+79
+79
docs/test-plans/2026-03-06-pe-frame-redesign.md
+79
docs/test-plans/2026-03-06-pe-frame-redesign.md
···
1
+
# Human Test Plan: PE Frame-Based Redesign
2
+
3
+
## Prerequisites
4
+
5
+
- Python 3.12 environment with all dependencies installed (SimPy, Lark, FastAPI, uvicorn, watchdog, pytest, hypothesis)
6
+
- `python -m pytest tests/ -v` passing with zero failures (1277 tests)
7
+
- Working terminal with ANSI colour support
8
+
- Web browser (Chrome/Firefox) for WebSocket UI testing
9
+
10
+
## Phase 1: PE Architectural Invariant Review (AC2.4)
11
+
12
+
| Step | Action | Expected |
13
+
|------|--------|----------|
14
+
| 1 | Open `emu/pe.py` in an editor. | File opens, contains `ProcessingElement` class. |
15
+
| 2 | Search for `_process_token()`, `_match_frame()`, `_do_emit_new()`, `_emit_inherit()`, `_emit_sink()` methods. | All methods exist in the PE class. |
16
+
| 3 | In each method from step 2, verify there are no raw integer bit masking operations (`>>`, `<<`, `& 0x`, `\| 0x`) on instruction fields. | No bit manipulation on instruction fields. Fields accessed by name: `inst.output`, `inst.has_const`, `inst.fref`, `inst.dest_count`, `inst.wide`, `inst.opcode`. |
17
+
| 4 | Search for `pack_flit1` and `unpack_flit1` calls in `emu/pe.py`. | These calls appear ONLY in: (a) `_emit_change_tag`, (b) EXTRACT_TAG handler in `_process_token`, (c) `_handle_local_write()`. |
18
+
| 5 | Verify no `pack_instruction` or `unpack_instruction` calls exist in the main pipeline methods. | Encoding boundary calls only appear in side-path handlers. |
19
+
20
+
## Phase 2: REPL Frame State Display (AC7.2)
21
+
22
+
| Step | Action | Expected |
23
+
|------|--------|----------|
24
+
| 1 | Run `python -m monitor` from project root. | REPL starts with `(monitor)` prompt. |
25
+
| 2 | Type `load` followed by a valid dfasm file path. | REPL responds with "Loaded" message showing PE count, SM count, node count. |
26
+
| 3 | Type `pe 0`. | Output displays: (a) tag_store mapping (act_id → frame_id), (b) free_frames list, (c) frame slot contents per allocated frame, (d) IRAM entries. No references to "matching store" or "gen counters". |
27
+
| 4 | Type `step` several times, then `pe 0` again. | Frame state updates reflected: presence bits may change, frame slots may have data written. |
28
+
| 5 | Type `send 0 0 0 42` (target=0, offset=0, act_id=0, data=42). | "Sent" confirmation. The `act_id` parameter (third positional arg) is accepted. |
29
+
| 6 | Type `state`. | Summary shows PE and SM counts, simulation time, no legacy field names. |
30
+
| 7 | Type `quit`. | REPL exits cleanly. |
31
+
32
+
## Phase 3: Web UI Frame State and Events (AC7.2)
33
+
34
+
| Step | Action | Expected |
35
+
|------|--------|----------|
36
+
| 1 | Run `python -m monitor --web --port 8421`. | Server starts, prints URL. |
37
+
| 2 | Open http://localhost:8421 in browser. | Monitor UI loads. No JavaScript console errors. |
38
+
| 3 | Load a program via the UI. | Graph renders with nodes. State panel shows PE state. |
39
+
| 4 | Inspect PE state panel for PE 0. | Panel shows "frames", "tag_store", "free_frames". No "matching_store" or "gen_counters". |
40
+
| 5 | Step through execution. | Event log populates with TokenReceived, Matched, Executed, Emitted. |
41
+
| 6 | Trigger frame allocation (program with function calls). | Event log shows `FrameAllocated` with `act_id` and `frame_id` fields. |
42
+
| 7 | Trigger frame free (step past FREE_FRAME). | Event log shows `FrameFreed` with `act_id` and `frame_id`. Free_frames list updates. |
43
+
| 8 | Inject token with invalid act_id. | `TokenRejected` event in log. No crash. |
44
+
| 9 | Check for `FrameSlotWritten` events during frame setup. | Events appear with `frame_id`, `slot`, `value` fields. |
45
+
| 10 | Check browser console (F12 → Console). | No JavaScript errors. |
46
+
47
+
## Phase 4: CLAUDE.md Documentation Accuracy
48
+
49
+
| Step | Action | Expected |
50
+
|------|--------|----------|
51
+
| 1 | Open `CLAUDE.md`. | File opens. |
52
+
| 2 | Find "Token Hierarchy" section. | Describes PEToken-based hierarchy. No mention of `IRAMWriteToken`. |
53
+
| 3 | Find "Instruction Set" section. | Describes `Instruction` (not `ALUInst`/`SMInst`/`Addr`). Mentions `OutputStyle`, `FrameDest`, `TokenKind`, `FrameOp`. |
54
+
| 4 | Find "Processing Element" section. | Describes frame-based matching with `tag_store`, `presence`, `frames`. No "matching_store" or "gen_counters". |
55
+
| 5 | Find PEConfig or types section. | Lists `frame_count`, `frame_slots`, `matchable_offsets`. `iram` uses `dict[int, Instruction]`. |
56
+
| 6 | Find "Simulation Events" section. | Lists `FrameAllocated`, `FrameFreed`, `FrameSlotWritten`, `TokenRejected`. `Matched` shows `act_id` and `frame_id`. |
57
+
| 7 | Check freshness date. | Updated to 2026-03-07 or later. |
58
+
| 8 | Open `asm/CLAUDE.md`. | No references to `ALUInst`, `SMInst`, `Addr`, `ctx_slots`, `IRAMWriteToken`, `FREE_CTX`. |
59
+
60
+
## Traceability
61
+
62
+
| Acceptance Criterion | Automated Test | Manual Step |
63
+
|----------------------|----------------|-------------|
64
+
| AC1.1–AC1.6 | `test_foundation_types.py`, `test_network_routing.py`, `test_pe_frames.py` | — |
65
+
| AC2.1–AC2.3 | `test_foundation_types.py`, `test_encoding.py` | — |
66
+
| AC2.4 | `test_pe_frames.py` (integration) | Phase 1 |
67
+
| AC3.1–AC3.10 | `test_pe_frames.py` | — |
68
+
| AC4.1–AC4.4 | `test_sm_t0_raw.py`, `test_encoding.py` | — |
69
+
| AC5.1–AC5.8 | `test_allocate_frames.py` | — |
70
+
| AC6.1–AC6.6 | `test_codegen_frames.py` | — |
71
+
| AC7.1 | `test_e2e.py`, `test_integration.py` | — |
72
+
| AC7.2 (backend) | `test_backend.py` | — |
73
+
| AC7.2 (snapshot) | `test_snapshot.py` | — |
74
+
| AC7.2 (graph JSON) | `test_monitor_graph_json.py` | — |
75
+
| AC7.2 (REPL) | `test_repl.py` | Phase 2 |
76
+
| AC7.2 (Web UI) | `test_monitor_graph_json.py` | Phase 3 |
77
+
| AC7.3 | `test_migration_cleanup.py` | — |
78
+
| AC7.4 | Full test suite | — |
79
+
| CLAUDE.md accuracy | — | Phase 4 |