feat(protocol): implement v0.14.0 SUB 5A protocol rewrite with enhanced chunk handling and new helpers

test: add regression tests for v0.14.x SUB 5A protocol fixes
refactor(logging): change warning logs to debug for less verbosity in write_blastware_file

minimateplus/framing.py

@@ -111,14 +111,15 @@ def build_5a_frame(offset_word: int, raw_params: bytes) -> bytes:
     verified against this algorithm on 2026-04-02).
 
     Args:
-        offset_word: 16-bit offset (0x1004 for probe/chunks, 0x005A for term).
-        raw_params:  10 or 11 params bytes (from bulk_waveform_params or
-                     bulk_waveform_term_params). 0x10 bytes in params are
-                     written RAW — NOT DLE-stuffed. Confirmed 2026-04-06 by
-                     comparing wire bytes: BW sends bare `10 04` for chunk 1
-                     (counter=0x1004), not stuffed `10 10 04`. Device reads
-                     params at fixed byte positions; stuffing shifts the bytes
-                     and corrupts the counter, causing device to ignore the frame.
+        offset_word: 16-bit offset.  For probe/chunks/metadata pages this is
+                     `0x1002`.  For the proper TERM frame this is computed by
+                     `bulk_waveform_term_v2()` from the STRT-derived
+                     `end_offset`.
+        raw_params:  10, 11, or 12 params bytes (from `bulk_waveform_params`
+                     for probes/samples, `bulk_waveform_term_v2` for TERM, or
+                     a manually-built 12-byte block for the metadata pages
+                     0x1002 / 0x1004).  See gotcha #3 below — params region
+                     uses partial DLE stuffing of 0x10 bytes.
 
     Returns:
         Complete frame bytes: [ACK][STX][stuffed_section][chk][ETX]
@@ -433,21 +434,26 @@ def bulk_waveform_params(key4: bytes, counter: int, *, is_probe: bool = False) -
 
 def bulk_waveform_term_params(key4: bytes, counter: int) -> bytes:
     """
-    DEPRECATED 2026-05-01 — see bulk_waveform_term_v2().
+    ⛔ DEPRECATED — DO NOT USE IN NEW CODE.
 
-    Build the 10-byte params block for the SUB 5A termination request, OLD layout
-    (used in conjunction with the fixed offset_word=0x005A).  Kept for backward
-    compatibility — produces a tiny ~100-byte device-side terminator response
-    rather than the proper partial-last-chunk + footer payload that BW gets.
+    This is the v1 termination params helper, paired with the broken
+    `_BULK_TERM_OFFSET = 0x005A` magic offset_word.  Together they produce a
+    ~100-byte device-side terminator response that does NOT contain the
+    partial-last-chunk waveform tail or the 26-byte file footer.  Files
+    reconstructed using this terminator are missing their last ~512 bytes of
+    waveform data and have a synthesized footer that disagrees with what BW
+    would have written.
 
-      params[0]   = key4[0]
-      params[1]   = key4[1]
-      params[2]   = (counter >> 8) & 0xFF
-      params[3:]  = zeros
+    **For new code, use `bulk_waveform_term_v2(key4, end_offset, last_chunk_counter)`**
+    which computes the correct offset_word + params from the STRT-derived
+    `end_offset`.  v2 produces wire bytes that match BW exactly across all
+    tested events (4-27-26 / 5-1-26 / 5-4-26 captures).
 
-    Use bulk_waveform_term_v2() for new code — it computes the verified
-    offset_word + params from end_offset (extracted from STRT) and the last
-    chunk counter.
+    This function is retained ONLY for the defensive fallback path in
+    `read_bulk_waveform_stream()` that triggers when STRT parsing fails or no
+    chunks are fetched (= a malformed event or an unexpected device state).
+    The fallback already logs a WARNING when it activates; if you see that
+    warning, the bug is upstream — STRT should have been parseable.
     """
     if len(key4) != 4:
         raise ValueError(f"waveform key must be 4 bytes, got {len(key4)}")