# Sim Framework Migration Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Migrate the sim framework (~7.8k LOC, 687 tests) from `.worktrees/sim-framework/` to master's `pm3py/sim/`, making all transponder models testable on master.

**Architecture:** Copy sim/ files as-is (preserving internal imports), fix 2 external imports that reference the old flat package layout (`..protocol` → `..core.protocol`, `..transport` → `..core.transport`). Copy 23 test files. Verify 687+ tests pass. The sim/ package keeps its flat internal structure — reorganization into `transponders/` and `reader/` sub-packages is a follow-up.

**Tech Stack:** Python 3.12, pytest, AsyncMock

---

## Context

### Dependency graph (acyclic, bottom-up)

**Foundation (no sim/ deps):** frame, memory, mcu_protocol, trace_fmt, crypto1, auth_aes, access_control/*

**Core abstractions:** transponder (←frame, memory), medium (←frame, transponder), reader (←frame, medium), auth_password (←frame)

**LF:** lf_base → em4100 → t5577, hid

**HF 14443-A:** iso14443a → mifare (+ crypto1), desfire, ndef

**HF 15693:** iso15693 → type5 → nxp_icode → icode_slix → icode_slix2 → icode3, icode_dna → ntag5_platform → ntag5_switch, ntag5_link → ntag5_boost

**Integration:** replay, fuzzer, table_compiler, relay, pm3medium, implants, sim_session, mcu_bridge, dual_session

### External imports (only 2 files)

- `pm3medium.py`: `from ..protocol import Cmd` and `from ..transport import PM3Transport`
- `sim_session.py`: `from ..protocol import Cmd` and `from ..transport import encode_ng_frame, decode_response_frame, RESP_PREAMBLE_MAGIC, RESP_PREAMBLE_SIZE, RESP_POSTAMBLE_SIZE`

### Overlap with trace/

`sim/trace_fmt.py` (560 lines) overlaps with `pm3py/trace/` but is more complete (has 14443-A decoders, NXP-specific decoders, TraceFormatter class). Keep both — sim references its own `trace_fmt.py` internally. Unify later.

---

### Task 1: Copy sim/ source files

**Files:**
- Source: `.worktrees/sim-framework/pm3py/sim/*.py` and `access_control/`
- Target: `pm3py/sim/`

**Step 1:** Copy all .py files from sim worktree into master's pm3py/sim/, overwriting the scaffold `__init__.py`

```bash
cp .worktrees/sim-framework/pm3py/sim/*.py pm3py/sim/
mkdir -p pm3py/sim/access_control
cp .worktrees/sim-framework/pm3py/sim/access_control/*.py pm3py/sim/access_control/
```

**Step 2:** Verify file count matches

```bash
find pm3py/sim -name '*.py' | wc -l
# Expected: ~40+ files
```

---

### Task 2: Fix external imports

**Files:**
- Modify: `pm3py/sim/pm3medium.py`
- Modify: `pm3py/sim/sim_session.py`

**Step 1:** In `pm3medium.py`, change:
- `from ..protocol import` → `from ..core.protocol import`
- `from ..transport import` → `from ..core.transport import`

**Step 2:** In `sim_session.py`, change:
- `from ..protocol import` → `from ..core.protocol import`
- `from ..transport import` → `from ..core.transport import`

**Step 3:** Verify no other files reference outside sim/:

```bash
grep -r "from \.\." pm3py/sim/ | grep -v "from \.\.core\." | grep -v "from \.\.trace"
```

Expected: no output (all external refs fixed).

---

### Task 3: Copy test files

**Files:**
- Source: `.worktrees/sim-framework/tests/test_sim_*.py` (23 files)
- Target: `tests/`

**Step 1:** Copy test files

```bash
cp .worktrees/sim-framework/tests/test_sim_*.py tests/
```

**Step 2:** Check if any test files import from old flat paths (like `from pm3py.protocol import`)

```bash
grep "from pm3py\." tests/test_sim_*.py | grep -v "from pm3py\.sim" | grep -v "from pm3py\.core"
```

Fix any that reference old flat layout.

---

### Task 4: Run tests — all green

**Step 1:** Run just sim tests first to isolate issues

```bash
python -m pytest tests/test_sim_*.py -v --tb=short 2>&1 | tail -30
```

Expected: 687 tests, 0 failures.

**Step 2:** Run full test suite

```bash
python -m pytest tests/ -v
```

Expected: 687 + 65 = 752 tests, 0 failures.

**Step 3:** Commit

```bash
git add pm3py/sim/ tests/test_sim_*.py
git commit -m "feat: migrate sim framework from worktree to master

Migrates all 41 sim modules and 23 test files (~7.8k LOC, 687 tests)
from .worktrees/sim-framework/ into pm3py/sim/. Only 2 import fixes
needed (pm3medium.py, sim_session.py) for the core/ package rename.
Internal sim/ imports unchanged.
"
```

---

### Task 5: Update docs

**Step 1:** Update `CLAUDE.md` package structure to show sim/ is populated
**Step 2:** Update `docs/plans/2026-03-18-refactor-progress.md`
**Step 3:** Commit docs