pm3py/docs/plans/2026-03-18-sim-migration.md

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

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

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/:

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

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)

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

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

python -m pytest tests/ -v

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

Step 3: Commit

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