oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/exploratory/sync.py

@@ -1,384 +0,0 @@
-"""Fuzzy synchronization pattern search for corrupted data.
-
-
-This module provides fuzzy pattern matching for finding sync words and markers
-in noisy or corrupted logic analyzer captures, with configurable bit error
-tolerance using Hamming distance.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from enum import Enum
-from typing import Literal
-
-import numpy as np
-from numpy.typing import NDArray
-
-
-class RecoveryStrategy(Enum):
-    """Error recovery strategies for corrupted packets.
-
-    Attributes:
-        NEXT_SYNC: Skip to next sync word when corruption detected
-        SKIP_BYTES: Skip fixed byte count and retry parsing
-        HEURISTIC: Use statistical packet length model for recovery
-    """
-
-    NEXT_SYNC = "next_sync"
-    SKIP_BYTES = "skip_bytes"
-    HEURISTIC = "heuristic"
-
-
-@dataclass
-class SyncMatch:
-    """Result from fuzzy sync pattern search.
-
-    Attributes:
-        index: Starting position of match in bits or bytes
-        matched_value: The actual value that matched (may differ from pattern)
-        hamming_distance: Number of bit errors in the match
-        confidence: Match confidence (1.0 - bit_errors/pattern_length)
-        pattern_length: Length of pattern in bits
-    """
-
-    index: int
-    matched_value: int
-    hamming_distance: int
-    confidence: float
-    pattern_length: int
-
-
-@dataclass
-class PacketParseResult:
-    """Result from robust packet parsing.
-
-    Attributes:
-        packets: List of successfully parsed packet data
-        valid: List of validity flags for each packet
-        errors: List of error types ('length_corruption', 'sync_lost', None)
-        error_positions: Byte positions where errors occurred
-        recovery_count: Number of times recovery was triggered
-    """
-
-    packets: list[bytes]
-    valid: list[bool]
-    errors: list[str | None]
-    error_positions: list[int]
-    recovery_count: int
-
-
-def hamming_distance(a: int, b: int, pattern_bits: int) -> int:
-    """Calculate Hamming distance between two integers.
-
-    Args:
-        a: First integer
-        b: Second integer
-        pattern_bits: Number of bits to compare (8, 16, 32, or 64)
-
-    Returns:
-        Number of differing bits
-
-    Examples:
-        >>> hamming_distance(0b10101010, 0b10101011, 8)
-        1
-        >>> hamming_distance(0xAA55, 0xAA54, 16)
-        1
-    """
-    # XOR gives 1s where bits differ
-    diff = a ^ b
-    # Mask to pattern length
-    mask = (1 << pattern_bits) - 1
-    diff &= mask
-    # Count set bits (population count)
-    return (diff).bit_count()
-
-
-def fuzzy_sync_search(
-    data: NDArray[np.uint8],
-    pattern: int,
-    *,
-    pattern_bits: Literal[8, 16, 32, 64] = 8,
-    max_errors: int = 2,
-    min_confidence: float = 0.85,
-) -> list[SyncMatch]:
-    """Find sync patterns with bit error tolerance using Hamming distance.
-
-    : Searches for sync words even with bit errors,
-    essential for recovering corrupted logic analyzer captures.
-
-    Performance targets (DAQ-001):
-    - ≥10 MB/s for max_errors=2
-    - ≥5 MB/s for max_errors=4
-    - ≥1 MB/s for max_errors=8
-
-    Confidence scoring (DAQ-001):
-    - ≥0.95 (0-1 bit errors): Highly reliable
-    - 0.85-0.95 (2-4 bit errors): Reliable
-    - <0.85 (>4 bit errors): Verify manually
-
-    Args:
-        data: Input byte array to search
-        pattern: Sync pattern to find (e.g., 0xAA55F0F0 for 32-bit)
-        pattern_bits: Pattern length in bits (8, 16, 32, or 64)
-        max_errors: Maximum tolerable bit errors (0-8)
-        min_confidence: Minimum confidence threshold (0.0-1.0)
-
-    Returns:
-        List of SyncMatch objects with position, matched value, distance,
-        and confidence score
-
-    Raises:
-        ValueError: If pattern_bits not in [8, 16, 32, 64]
-        ValueError: If max_errors < 0 or > 8
-        ValueError: If min_confidence not in [0.0, 1.0]
-
-    Examples:
-        >>> data = np.array([0xAA, 0x55, 0xF0, 0xF0, 0xFF], dtype=np.uint8)
-        >>> # Find exact match
-        >>> matches = fuzzy_sync_search(data, 0xAA55, pattern_bits=16)
-        >>> print(matches[0].confidence)
-        1.0
-
-        >>> # Find with 1 bit error (0xAA54 instead of 0xAA55)
-        >>> data = np.array([0xAA, 0x54, 0x00], dtype=np.uint8)
-        >>> matches = fuzzy_sync_search(data, 0xAA55, pattern_bits=16, max_errors=2)
-        >>> print(matches[0].hamming_distance)
-        1
-
-    References:
-        DAQ-001: Fuzzy Bit Pattern Search with Hamming Distance Tolerance
-    """
-    if pattern_bits not in (8, 16, 32, 64):
-        raise ValueError("pattern_bits must be 8, 16, 32, or 64")
-
-    if max_errors < 0 or max_errors > 8:
-        raise ValueError("max_errors must be in range [0, 8]")
-
-    if not 0.0 <= min_confidence <= 1.0:
-        raise ValueError("min_confidence must be in range [0.0, 1.0]")
-
-    pattern_bytes = pattern_bits // 8
-    if len(data) < pattern_bytes:
-        return []
-
-    matches: list[SyncMatch] = []
-
-    # Sliding window search
-    for i in range(len(data) - pattern_bytes + 1):
-        # Extract window and convert to integer
-        window = data[i : i + pattern_bytes]
-
-        # Convert bytes to integer (big-endian)
-        if pattern_bytes == 1:
-            value = int(window[0])
-        elif pattern_bytes == 2:
-            value = (int(window[0]) << 8) | int(window[1])
-        elif pattern_bytes == 4:
-            value = (
-                (int(window[0]) << 24)
-                | (int(window[1]) << 16)
-                | (int(window[2]) << 8)
-                | int(window[3])
-            )
-        else:  # 8 bytes
-            value = 0
-            for j in range(8):
-                value = (value << 8) | int(window[j])
-
-        # Calculate Hamming distance
-        dist = hamming_distance(value, pattern, pattern_bits)
-
-        # Check if within error tolerance
-        if dist <= max_errors:
-            confidence = 1.0 - (dist / pattern_bits)
-
-            if confidence >= min_confidence:
-                matches.append(
-                    SyncMatch(
-                        index=i,
-                        matched_value=value,
-                        hamming_distance=dist,
-                        confidence=confidence,
-                        pattern_length=pattern_bits,
-                    )
-                )
-
-    return matches
-
-
-def parse_variable_length_packets(
-    data: NDArray[np.uint8],
-    *,
-    sync_pattern: int | None = None,
-    sync_bits: Literal[8, 16, 32, 64] = 16,
-    length_offset: int = 2,
-    length_size: int = 2,
-    min_packet_size: int = 4,
-    max_packet_size: int = 1024,
-    recovery_strategy: RecoveryStrategy = RecoveryStrategy.NEXT_SYNC,
-    skip_bytes: int = 1,
-) -> PacketParseResult:
-    """Parse variable-length packets with error recovery.
-
-    : Robust parsing that continues after corruption,
-    falling back to sync word search when length fields are corrupted.
-
-    Error detection (DAQ-002):
-    - Invalid if: length=0, length>max_packet_size, or length&0xFF00=0xFF00
-    - Suspicious if: length < min_expected or length > 90th_percentile×2  # noqa: RUF002
-
-    Recovery strategies (DAQ-002):
-    - next_sync: Skip to next sync word (requires sync_pattern)
-    - skip_bytes: Skip fixed byte count and retry
-    - heuristic: Use statistical packet length model
-
-    Args:
-        data: Input byte array containing packets
-        sync_pattern: Optional sync word to search for on errors
-        sync_bits: Sync pattern length in bits
-        length_offset: Byte offset to length field from start
-        length_size: Length field size in bytes (1 or 2)
-        min_packet_size: Minimum valid packet size in bytes
-        max_packet_size: Maximum valid packet size in bytes
-        recovery_strategy: Strategy to use when corruption detected
-        skip_bytes: Number of bytes to skip for SKIP_BYTES strategy
-
-    Returns:
-        PacketParseResult with parsed packets and error information
-
-    Raises:
-        ValueError: If length_size not 1 or 2
-        ValueError: If recovery_strategy is NEXT_SYNC without sync_pattern
-
-    Examples:
-        >>> # Simple TLV parsing with sync word
-        >>> data = np.array([0xAA, 0x55, 0x00, 0x04, 0x01, 0x02], dtype=np.uint8)
-        >>> result = parse_variable_length_packets(
-        ...     data, sync_pattern=0xAA55, length_offset=2
-        ... )
-        >>> len(result.packets)
-        1
-
-    References:
-        DAQ-002: Robust Variable-Length Packet Parsing with Error Recovery
-    """
-    if length_size not in (1, 2):
-        raise ValueError("length_size must be 1 or 2")
-
-    if recovery_strategy == RecoveryStrategy.NEXT_SYNC and sync_pattern is None:
-        raise ValueError("NEXT_SYNC strategy requires sync_pattern")
-
-    packets: list[bytes] = []
-    valid: list[bool] = []
-    errors: list[str | None] = []
-    error_positions: list[int] = []
-    recovery_count = 0
-
-    # Track packet lengths for heuristic recovery
-    packet_lengths: list[int] = []
-
-    pos = 0
-    while pos < len(data):
-        # Try to parse packet at current position
-
-        # Check if we have enough data for header
-        if pos + length_offset + length_size > len(data):
-            break
-
-        # Extract length field
-        length_pos = pos + length_offset
-        if length_size == 1:
-            pkt_length = int(data[length_pos])
-        else:  # 2 bytes
-            pkt_length = (int(data[length_pos]) << 8) | int(data[length_pos + 1])
-
-        # Validate length field
-        is_valid_length = True
-        error_type = None
-
-        # Check for obviously corrupted lengths
-        if (
-            pkt_length == 0
-            or pkt_length > max_packet_size
-            or (length_size == 2 and (pkt_length & 0xFF00) == 0xFF00)
-            or pkt_length < min_packet_size
-        ):
-            is_valid_length = False
-            error_type = "length_corruption"
-
-        # Check suspiciously large length (heuristic)
-        if is_valid_length and len(packet_lengths) >= 10:
-            p90 = np.percentile(packet_lengths, 90)
-            if pkt_length > p90 * 2:
-                is_valid_length = False
-                error_type = "length_corruption"
-
-        if is_valid_length:
-            # Length looks good, try to extract packet
-            packet_end = pos + pkt_length
-
-            if packet_end <= len(data):
-                # Successfully extract packet
-                packet_data = bytes(data[pos:packet_end])
-                packets.append(packet_data)
-                valid.append(True)
-                errors.append(None)
-                packet_lengths.append(pkt_length)
-                pos = packet_end
-            else:
-                # Packet extends beyond data
-                errors.append("truncated")
-                error_positions.append(pos)
-                break
-        else:
-            # Length field corrupted - apply recovery
-            recovery_count += 1
-            error_positions.append(pos)
-
-            if recovery_strategy == RecoveryStrategy.NEXT_SYNC:
-                # Search for next sync word
-                assert sync_pattern is not None  # Validated at function start
-                search_start = pos + 1
-                search_data = data[search_start:]
-
-                if len(search_data) >= sync_bits // 8:
-                    matches = fuzzy_sync_search(
-                        search_data,
-                        sync_pattern,
-                        pattern_bits=sync_bits,
-                        max_errors=0,  # type: ignore[arg-type]
-                    )
-
-                    if matches:
-                        # Found sync, jump to it
-                        pos = search_start + matches[0].index
-                        errors.append("sync_lost")
-                    else:
-                        # No more syncs found
-                        break
-                else:
-                    break
-
-            elif recovery_strategy == RecoveryStrategy.SKIP_BYTES:
-                # Skip fixed bytes and retry
-                pos += skip_bytes
-                errors.append(error_type)
-
-            elif recovery_strategy == RecoveryStrategy.HEURISTIC:
-                # Use median packet length as guess
-                if packet_lengths:
-                    guess_length = int(np.median(packet_lengths))
-                    pos += guess_length
-                else:
-                    # No history, skip minimal amount
-                    pos += min_packet_size
-                errors.append(error_type)
-
-    return PacketParseResult(
-        packets=packets,
-        valid=valid,
-        errors=errors,
-        error_positions=error_positions,
-        recovery_count=recovery_count,
-    )