From 117f46efb992ea1586a17efede9b6671a9fd80b0 Mon Sep 17 00:00:00 2001
From: michael <operations@dangerousthings.com>
Date: Wed, 18 Mar 2026 19:49:20 -0700
Subject: [PATCH] refactor: create pm3py/trace/ for shared trace infrastructure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trace buffer parsing, protocol decoders, NDEF annotation, and
formatting are firmware-level features shared by sniff, sim, and
reader modes — not sniff-specific. Moves these from sniff/ into
trace/. sniff/ retains only SniffSession (orchestration) and
re-exports trace symbols for convenience.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 pm3py/core/hf_iso15.py                 | 10 +++++-----
 pm3py/sniff/__init__.py                | 14 +++++++++-----
 pm3py/sniff/session.py                 |  4 ++--
 pm3py/trace/__init__.py                | 12 ++++++++++++
 pm3py/{sniff => trace}/decode_iso15.py |  0
 pm3py/{sniff => trace}/format.py       |  0
 pm3py/{sniff => trace}/ndef.py         |  0
 pm3py/{sniff => trace}/trace.py        |  0
 8 files changed, 28 insertions(+), 12 deletions(-)
 create mode 100644 pm3py/trace/__init__.py
 rename pm3py/{sniff => trace}/decode_iso15.py (100%)
 rename pm3py/{sniff => trace}/format.py (100%)
 rename pm3py/{sniff => trace}/ndef.py (100%)
 rename pm3py/{sniff => trace}/trace.py (100%)

diff --git a/pm3py/core/hf_iso15.py b/pm3py/core/hf_iso15.py
index 0da8dff..1e5084a 100644
--- a/pm3py/core/hf_iso15.py
+++ b/pm3py/core/hf_iso15.py
@@ -3,13 +3,13 @@ import struct
 from .protocol import Cmd
 from .transport import PM3Transport, PM3Error
 
-# Re-export sniff symbols for backward compat with existing test imports
-from ..sniff.trace import parse_tracelog, TRACELOG_HDR_SIZE
-from ..sniff.decode_iso15 import (
+# Re-export trace symbols for backward compat with existing test imports
+from ..trace import (
+    parse_tracelog, TRACELOG_HDR_SIZE,
     decode_15693_request, decode_15693_response, decode_15693,
+    decode_ndef_annotation,
+    format_sniff_line,
 )
-from ..sniff.ndef import decode_ndef_annotation
-from ..sniff.format import format_sniff_line
 
 # ISO15 PM3 flags
 ISO15_CONNECT = 0x01
diff --git a/pm3py/sniff/__init__.py b/pm3py/sniff/__init__.py
index 4e62135..ec97f14 100644
--- a/pm3py/sniff/__init__.py
+++ b/pm3py/sniff/__init__.py
@@ -1,9 +1,13 @@
-"""pm3py.sniff — Sniff sessions, trace parsing, protocol decoders, formatting."""
+"""pm3py.sniff — Sniff sessions (orchestrate sniff → download → decode → format)."""
 from .session import SniffSession
-from .trace import parse_tracelog, TRACELOG_HDR_SIZE
-from .decode_iso15 import decode_15693, decode_15693_request, decode_15693_response
-from .ndef import decode_ndef_annotation
-from .format import format_sniff_line
+
+# Re-export trace symbols for convenience
+from ..trace import (
+    parse_tracelog, TRACELOG_HDR_SIZE,
+    decode_15693, decode_15693_request, decode_15693_response,
+    decode_ndef_annotation,
+    format_sniff_line,
+)
 
 __all__ = [
     "SniffSession",
diff --git a/pm3py/sniff/session.py b/pm3py/sniff/session.py
index 0d1d086..0ab1166 100644
--- a/pm3py/sniff/session.py
+++ b/pm3py/sniff/session.py
@@ -3,8 +3,8 @@ import sys
 
 from ..core.protocol import Cmd, PM3_CMD_DATA_SIZE
 from ..core.transport import PM3Transport, encode_ng_frame
-from .trace import parse_tracelog
-from .format import format_sniff_line
+from ..trace import parse_tracelog
+from ..trace.format import format_sniff_line
 
 
 class SniffSession:
diff --git a/pm3py/trace/__init__.py b/pm3py/trace/__init__.py
new file mode 100644
index 0000000..50fe345
--- /dev/null
+++ b/pm3py/trace/__init__.py
@@ -0,0 +1,12 @@
+"""pm3py.trace — Firmware trace buffer infrastructure (shared by sniff, sim, reader)."""
+from .trace import parse_tracelog, TRACELOG_HDR_SIZE
+from .decode_iso15 import decode_15693, decode_15693_request, decode_15693_response
+from .ndef import decode_ndef_annotation
+from .format import format_sniff_line
+
+__all__ = [
+    "parse_tracelog", "TRACELOG_HDR_SIZE",
+    "decode_15693", "decode_15693_request", "decode_15693_response",
+    "decode_ndef_annotation",
+    "format_sniff_line",
+]
diff --git a/pm3py/sniff/decode_iso15.py b/pm3py/trace/decode_iso15.py
similarity index 100%
rename from pm3py/sniff/decode_iso15.py
rename to pm3py/trace/decode_iso15.py
diff --git a/pm3py/sniff/format.py b/pm3py/trace/format.py
similarity index 100%
rename from pm3py/sniff/format.py
rename to pm3py/trace/format.py
diff --git a/pm3py/sniff/ndef.py b/pm3py/trace/ndef.py
similarity index 100%
rename from pm3py/sniff/ndef.py
rename to pm3py/trace/ndef.py
diff --git a/pm3py/sniff/trace.py b/pm3py/trace/trace.py
similarity index 100%
rename from pm3py/sniff/trace.py
rename to pm3py/trace/trace.py