oscura 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

oscura/workflows/complete_re.py

@@ -386,8 +386,21 @@ def _step_5_infer_structure(
         if hasattr(re_result, "frames") and re_result.frames:
             structure = _infer_message_structure(re_result.frames)
             results.partial_results["structure"] = structure
-            if structure.get("fields"):
-                protocol_spec.fields = structure["fields"]
+            # Only update fields if protocol_spec has no fields yet
+            # (don't overwrite existing FieldSpec objects with dicts)
+            if structure.get("fields") and not protocol_spec.fields:
+                # Convert dict fields to FieldSpec objects
+                from oscura.workflows.reverse_engineering import FieldSpec
+
+                protocol_spec.fields = [
+                    FieldSpec(
+                        name=f"field_{field['offset']}",
+                        offset=field["offset"],
+                        size=field["length"],
+                        field_type=field.get("field_type", "bytes"),
+                    )
+                    for field in structure["fields"]
+                ]
     except Exception as e:
         msg = f"Structure inference failed: {e}"
         results.warnings.append(msg)
@@ -732,7 +745,7 @@ def _load_captures(capture_dict: dict[str, str]) -> dict[str, WaveformTrace]:
         # Auto-detect format based on extension
         if suffix in (".bin", ".dat"):
             # Binary files - try to infer structure
-            trace = loaders.load_binary(str(path))  # type: ignore[attr-defined]
+            trace = loaders.load_binary(str(path))
         elif suffix == ".wfm":
             trace = loaders.load_tektronix(str(path))  # type: ignore[attr-defined]
         elif suffix == ".vcd":
@@ -779,21 +792,79 @@ def _detect_protocol(
 def _differential_analysis(traces: dict[str, WaveformTrace]) -> dict[str, Any]:
     """Perform differential analysis between multiple captures.
 
+    Compares byte streams across captures to identify constant vs variable fields
+    using variance analysis and correlation.
+
     Args:
-        traces: Multiple labeled captures.
+        traces: Multiple labeled captures (key: label, value: WaveformTrace).
 
     Returns:
-        Dict with differential analysis results.
+        Dict with differential analysis results including constant_fields and variable_fields.
     """
-    # Placeholder for differential analysis
-    # Would compare traces to identify state-dependent fields
-    results = {
+    import numpy as np
+
+    if not traces or len(traces) < 2:
+        return {
+            "trace_count": len(traces),
+            "differences": [],
+            "constant_fields": [],
+            "variable_fields": [],
+        }
+
+    # Convert traces to byte arrays for analysis
+    byte_arrays = []
+    for trace in traces.values():
+        if hasattr(trace, "data"):
+            # Convert analog data to bytes (threshold at 0)
+            if hasattr(trace.data, "dtype") and np.issubdtype(trace.data.dtype, np.floating):
+                digital = (trace.data > 0).astype(np.uint8)
+                byte_arrays.append(digital)
+            else:
+                byte_arrays.append(np.asarray(trace.data, dtype=np.uint8))
+
+    if not byte_arrays:
+        return {
+            "trace_count": len(traces),
+            "differences": [],
+            "constant_fields": [],
+            "variable_fields": [],
+        }
+
+    # Find minimum length to compare
+    min_len = min(len(arr) for arr in byte_arrays)
+    if min_len == 0:
+        return {
+            "trace_count": len(traces),
+            "differences": [],
+            "constant_fields": [],
+            "variable_fields": [],
+        }
+
+    # Truncate all arrays to same length
+    aligned_arrays = [arr[:min_len] for arr in byte_arrays]
+    stacked = np.stack(aligned_arrays, axis=0)
+
+    # Calculate variance across captures for each byte position
+    variances = np.var(stacked, axis=0)
+
+    # Identify constant fields (low variance) vs variable fields (high variance)
+    constant_threshold = 0.1
+    constant_fields = []
+    variable_fields = []
+
+    for i, variance in enumerate(variances):
+        if variance < constant_threshold:
+            constant_fields.append({"position": int(i), "variance": float(variance)})
+        else:
+            variable_fields.append({"position": int(i), "variance": float(variance)})
+
+    return {
         "trace_count": len(traces),
         "differences": [],
-        "constant_fields": [],
-        "variable_fields": [],
+        "constant_fields": constant_fields,
+        "variable_fields": variable_fields,
+        "analyzed_length": int(min_len),
     }
-    return results
 
 
 def _enhance_spec_with_differential(spec: ProtocolSpec, diff_results: dict[str, Any]) -> None:
@@ -813,10 +884,53 @@ def _infer_message_structure(frames: list[Any]) -> dict[str, Any]:
         frames: List of decoded frames.
 
     Returns:
-        Dict with inferred structure details.
+        Dict with inferred structure including fields and patterns.
     """
-    # Placeholder for structure inference
-    return {"fields": [], "patterns": []}
+    from oscura.analyzers.patterns.reverse_engineering import ReverseEngineer
+
+    if not frames:
+        return {"fields": [], "patterns": []}
+
+    # Convert frames to bytes messages for structure inference
+    messages = []
+    for frame in frames:
+        if hasattr(frame, "raw_bytes") and frame.raw_bytes:
+            # Ensure bytes format
+            if isinstance(frame.raw_bytes, bytes):
+                messages.append(frame.raw_bytes)
+            elif isinstance(frame.raw_bytes, (list, tuple)):
+                # Convert to bytes if it's a list/tuple
+                messages.append(bytes(frame.raw_bytes))
+
+    if not messages:
+        return {"fields": [], "patterns": []}
+
+    # Use ReverseEngineer to infer protocol structure
+    try:
+        re_tool = ReverseEngineer()
+        structure = re_tool.infer_protocol_structure(messages, min_field_size=1)
+
+        # Convert ProtocolStructure to dict format
+        fields_list = [
+            {
+                "offset": field.offset,
+                "length": field.length,
+                "field_type": field.field_type,
+                "entropy": field.entropy,
+                "is_constant": field.is_constant,
+            }
+            for field in structure.fields
+        ]
+
+        return {
+            "fields": fields_list,
+            "patterns": [],
+            "is_fixed_length": structure.message_length > 0,
+            "message_length": structure.message_length,
+        }
+    except Exception:
+        # If inference fails, return empty structure
+        return {"fields": [], "patterns": []}
 
 
 def _detect_crypto_regions(frames: list[Any]) -> list[dict[str, Any]]:
@@ -879,10 +993,22 @@ def _recover_crc(frames: list[Any], checksum_types: list[str] | None = None) ->
         checksum_types: Optional list of checksum types to try.
 
     Returns:
-        Dict with CRC recovery results.
+        Dict with CRC recovery results including checksum_type, position, and confidence.
     """
-    # Placeholder - would use existing checksum detection from reverse_engineer_signal
-    return {"checksum_type": None, "position": None, "confidence": 0.0}
+    from oscura.workflows.reverse_engineering import _detect_checksum
+
+    # Default checksum types to try
+    if checksum_types is None:
+        checksum_types = ["xor", "sum8", "crc8", "crc16", "crc32"]
+
+    # Detect checksum using existing function
+    checksum_type, position, confidence = _detect_checksum(frames, checksum_types)
+
+    return {
+        "checksum_type": checksum_type,
+        "position": position,
+        "confidence": float(confidence),
+    }
 
 
 def _extract_state_machine(frames: list[Any]) -> dict[str, Any]:
@@ -892,10 +1018,64 @@ def _extract_state_machine(frames: list[Any]) -> dict[str, Any]:
         frames: List of decoded frames.
 
     Returns:
-        Dict with state machine representation.
+        Dict with state machine representation including states, transitions, and initial_state.
     """
-    # Placeholder for state machine extraction using RPNI or similar
-    return {"states": [], "transitions": [], "initial_state": None}
+    from oscura.inference.state_machine import infer_rpni
+
+    if not frames:
+        return {"states": [], "transitions": [], "initial_state": None}
+
+    # Convert frames to sequences of message types/IDs for RPNI
+    # Extract first byte as message type identifier
+    sequences = []
+    for frame in frames:
+        if hasattr(frame, "raw_bytes") and frame.raw_bytes:
+            # Use first byte as message type
+            msg_type = (
+                frame.raw_bytes[0]
+                if isinstance(frame.raw_bytes[0], int)
+                else ord(frame.raw_bytes[0])
+            )
+            sequences.append([msg_type])
+
+    if not sequences:
+        return {"states": [], "transitions": [], "initial_state": None}
+
+    # Infer state machine using RPNI algorithm
+    try:
+        # Cast sequences to the expected type
+        sequences_typed: list[list[str | int]] = [[int(x) for x in seq] for seq in sequences]
+        automaton = infer_rpni(sequences_typed)
+
+        # Convert to dict format
+        states_list = [
+            {
+                "id": state.id,
+                "name": state.name,
+                "is_initial": state.is_initial,
+                "is_accepting": state.is_accepting,
+            }
+            for state in automaton.states
+        ]
+
+        transitions_list = [
+            {
+                "source": trans.source,
+                "target": trans.target,
+                "symbol": trans.symbol,
+            }
+            for trans in automaton.transitions
+        ]
+
+        return {
+            "states": states_list,
+            "transitions": transitions_list,
+            "initial_state": automaton.initial_state,
+            "accepting_states": list(automaton.accepting_states),
+        }
+    except Exception:
+        # If RPNI fails, return empty state machine
+        return {"states": [], "transitions": [], "initial_state": None}
 
 
 def _generate_wireshark_dissector(spec: ProtocolSpec, output_path: Path) -> None:
@@ -1097,20 +1277,68 @@ def _generate_report(
 def _replay_validation(spec: ProtocolSpec, target_device: str, frames: list[Any]) -> dict[str, Any]:
     """Perform replay validation on target hardware.
 
+    Implements dry-run mode with structural validation. Hardware replay is optional
+    and documented for future implementation.
+
     Args:
         spec: Protocol specification.
-        target_device: Device path for validation.
+        target_device: Device path for validation (use "dry-run" for structural validation only).
         frames: Frames to replay.
 
     Returns:
-        Dict with validation results.
+        Dict with validation results including replayed count and success rate.
     """
-    # Placeholder for replay validation
+    if not frames:
+        return {
+            "replayed": 0,
+            "successful": 0,
+            "failed": 0,
+            "success_rate": 0.0,
+            "mode": "none",
+        }
+
+    # Dry-run mode: structural validation only
+    if target_device == "dry-run" or target_device is None:
+        replayed = 0
+        successful = 0
+        failed = 0
+
+        for frame in frames:
+            replayed += 1
+
+            # Structural validation: check if frame matches spec
+            if hasattr(frame, "raw_bytes") and frame.raw_bytes:
+                # Check length matches spec if fixed-length
+                if spec.frame_length and spec.frame_length > 0:
+                    if len(frame.raw_bytes) == spec.frame_length:
+                        successful += 1
+                    else:
+                        failed += 1
+                else:
+                    # Variable length - just count as successful if has data
+                    successful += 1
+            else:
+                failed += 1
+
+        success_rate = successful / replayed if replayed > 0 else 0.0
+
+        return {
+            "replayed": replayed,
+            "successful": successful,
+            "failed": failed,
+            "success_rate": success_rate,
+            "mode": "dry-run",
+        }
+
+    # Hardware mode (future implementation)
+    # Would connect to target_device and replay frames
     return {
         "replayed": 0,
         "successful": 0,
         "failed": 0,
         "success_rate": 0.0,
+        "mode": "hardware",
+        "error": "Hardware replay not yet implemented. Use 'dry-run' for structural validation.",
     }
 
 

oscura/workflows/digital.py

@@ -131,6 +131,27 @@ def characterize_buffer(
     return result
 
 
+def _extract_measurement_value(result: Any) -> float:
+    """Extract numeric value from measurement result.
+
+    Handles both MeasurementResult dicts and simple numeric values (for tests).
+
+    Args:
+        result: MeasurementResult dict or numeric value.
+
+    Returns:
+        Extracted float value, or 0.0 if not applicable.
+    """
+    if isinstance(result, dict):
+        # Handle MeasurementResult dict
+        if not result.get("applicable", True):
+            return 0.0
+        value = result.get("value", 0.0)
+        return float(value) if value is not None else 0.0
+    # Handle simple numeric value (from mocks)
+    return float(result) if isinstance(result, (int, float)) else 0.0
+
+
 def _determine_logic_family(
     trace: WaveformTrace, logic_family: str | None
 ) -> tuple[str, float, float, float]:
@@ -176,8 +197,9 @@ def _measure_timing_params(trace: WaveformTrace) -> tuple[float, float]:
     try:
         t_rise_raw = rise_time(trace)
         t_fall_raw = fall_time(trace)
-        t_rise: float = float(t_rise_raw)
-        t_fall: float = float(t_fall_raw)
+        # Handle both MeasurementResult dict and simple float (for mocks)
+        t_rise = _extract_measurement_value(t_rise_raw)
+        t_fall = _extract_measurement_value(t_fall_raw)
     except Exception as e:
         raise AnalysisError(f"Failed to measure rise/fall time: {e}") from e
 
@@ -201,8 +223,9 @@ def _measure_overshoots(
 
     v_overshoot_raw = overshoot(trace)
     v_undershoot_raw = undershoot(trace)
-    v_overshoot: float = float(v_overshoot_raw)
-    v_undershoot: float = float(v_undershoot_raw)
+    # Handle both MeasurementResult dict and simple float (for mocks)
+    v_overshoot = _extract_measurement_value(v_overshoot_raw)
+    v_undershoot = _extract_measurement_value(v_undershoot_raw)
 
     swing = voh - vol
     if swing > 0:

oscura/workflows/multi_trace.py

@@ -310,9 +310,8 @@ class MultiTraceWorkflow:
     def _measure_sequential(self, measurements: tuple[str, ...]) -> None:
         """Measure sequentially."""
         # Progress tracking
-        progress = create_progress_tracker(  # type: ignore[call-arg]
+        progress = create_progress_tracker(
             total=len(self.results.trace_ids),
-            description="Measuring traces",
         )
 
         for trace_id, trace in self._iter_traces(lazy=True):
@@ -367,18 +366,57 @@ class MultiTraceWorkflow:
     def _perform_measurement(self, trace: Any, measurement: str) -> Any:
         """Perform a single measurement.
 
+        Dispatches measurement name to appropriate function from oscura.analyzers.waveform.measurements.
+
         Args:
-            trace: Trace object
-            measurement: Measurement name
+            trace: Trace object (WaveformTrace or MockTrace)
+            measurement: Measurement name (rise_time, fall_time, frequency, amplitude, rms, duty_cycle, period, pulse_width)
+
+        Returns:
+            MeasurementResult dict with value, unit, applicable, reason, and display fields.
 
         Raises:
             OscuraError: If measurement not available
         """
-        # Placeholder - would call actual measurement functions
-        # from oscura.analyzers.measurements
-        raise OscuraError(
-            f"Measurement '{measurement}' not yet implemented in multi-trace workflow"
-        )
+        from collections.abc import Callable
+        from typing import TYPE_CHECKING
+
+        from oscura.analyzers.waveform import measurements
+        from oscura.core.types import TraceMetadata, WaveformTrace
+
+        if TYPE_CHECKING:
+            from oscura.core.types import MeasurementResult
+
+        # Convert MockTrace or other formats to WaveformTrace if needed
+        if not isinstance(trace, WaveformTrace):
+            # Handle MockTrace or similar objects with data and sample_rate attributes
+            if hasattr(trace, "data") and hasattr(trace, "sample_rate"):
+                metadata = TraceMetadata(sample_rate=trace.sample_rate)
+                trace = WaveformTrace(data=trace.data, metadata=metadata)
+            else:
+                raise OscuraError(f"Invalid trace object: {type(trace)}")
+
+        # Map measurement name to function
+        measurement_functions: dict[str, Callable[[Any], MeasurementResult]] = {
+            "rise_time": measurements.rise_time,
+            "fall_time": measurements.fall_time,
+            "frequency": measurements.frequency,
+            "amplitude": measurements.amplitude,
+            "rms": measurements.rms,
+            "duty_cycle": measurements.duty_cycle,
+            "period": measurements.period,
+            "pulse_width": measurements.pulse_width,
+        }
+
+        func = measurement_functions.get(measurement)
+        if func is None:
+            raise OscuraError(
+                f"Measurement '{measurement}' not available. "
+                f"Supported: {', '.join(measurement_functions.keys())}"
+            )
+
+        # Perform measurement and return result
+        return func(trace)
 
     def aggregate(self) -> MultiTraceResults:
         """Compute aggregate statistics across traces.
@@ -462,24 +500,105 @@ class MultiTraceWorkflow:
     def _export_pdf(self, filename: str) -> None:
         """Export results to PDF.
 
+        Creates a comprehensive PDF report with measurement tables and statistics.
+
         Args:
-            filename: Output filename
+            filename: Output filename (with .pdf extension)
 
         Raises:
-            OscuraError: PDF export not yet implemented
+            ImportError: If reportlab is not installed
         """
-        raise OscuraError("PDF export not yet implemented")
+        from pathlib import Path
+
+        from oscura.reporting.core import Report, ReportConfig
+        from oscura.reporting.pdf import generate_pdf_report
+
+        # Create report with results
+        config = ReportConfig(title="Multi-Trace Analysis Results")
+        report = Report(config=config)
+
+        # Add measurement results - aggregate across all traces
+        if self.results.measurements:
+            report.add_section("Measurement Results", level=2)
+            # Collect measurement values by name across all traces
+            measurement_data: dict[str, list[float]] = {}
+            for trace_results in self.results.measurements.values():
+                for meas_name, meas_result in trace_results.items():
+                    # Only aggregate applicable numeric measurements
+                    if isinstance(meas_result, dict) and meas_result.get("applicable", False):
+                        try:
+                            value = float(meas_result["value"])
+                            if meas_name not in measurement_data:
+                                measurement_data[meas_name] = []
+                            measurement_data[meas_name].append(value)
+                        except (ValueError, TypeError, KeyError):
+                            # Skip non-numeric or missing values
+                            pass
+
+            # Add aggregated measurements to report
+            for measurement_name, values in measurement_data.items():
+                if values:
+                    report.add_measurements(
+                        f"{measurement_name.replace('_', ' ').title()}",
+                        {"mean": sum(values) / len(values), "count": len(values)},
+                        level=3,
+                    )
+
+        # Generate PDF
+        pdf_bytes = generate_pdf_report(report)
+
+        # Write to file
+        Path(filename).write_bytes(pdf_bytes)
 
     def _export_html(self, filename: str) -> None:
         """Export results to HTML.
 
-        Args:
-            filename: Output filename
+        Creates a modern HTML report with interactive features.
 
-        Raises:
-            OscuraError: HTML export not yet implemented
+        Args:
+            filename: Output filename (with .html extension)
         """
-        raise OscuraError("HTML export not yet implemented")
+        from pathlib import Path
+
+        from oscura.reporting.core import Report, ReportConfig
+        from oscura.reporting.html import generate_html_report
+
+        # Create report with results
+        config = ReportConfig(title="Multi-Trace Analysis Results")
+        report = Report(config=config)
+
+        # Add measurement results - aggregate across all traces
+        if self.results.measurements:
+            report.add_section("Measurement Results", level=2)
+            # Collect measurement values by name across all traces
+            measurement_data: dict[str, list[float]] = {}
+            for trace_results in self.results.measurements.values():
+                for meas_name, meas_result in trace_results.items():
+                    # Only aggregate applicable numeric measurements
+                    if isinstance(meas_result, dict) and meas_result.get("applicable", False):
+                        try:
+                            value = float(meas_result["value"])
+                            if meas_name not in measurement_data:
+                                measurement_data[meas_name] = []
+                            measurement_data[meas_name].append(value)
+                        except (ValueError, TypeError, KeyError):
+                            # Skip non-numeric or missing values
+                            pass
+
+            # Add aggregated measurements to report
+            for measurement_name, values in measurement_data.items():
+                if values:
+                    report.add_measurements(
+                        f"{measurement_name.replace('_', ' ').title()}",
+                        {"mean": sum(values) / len(values), "count": len(values)},
+                        level=3,
+                    )
+
+        # Generate HTML
+        html_content = generate_html_report(report, interactive=True)
+
+        # Write to file
+        Path(filename).write_text(html_content, encoding="utf-8")
 
 
 def load_all(pattern: str, lazy: bool = True) -> list[Any]:

oscura/workflows/waveform.py

@@ -545,16 +545,21 @@ def analyze_complete(
             },
         )
 
-        # Add basic measurement sections - handle BOTH formats
+        # Add basic measurement sections - handle MeasurementResult format
         for analysis_name, analysis_results in results.items():
-            # Extract measurements in both formats:
-            # 1. Unified format: {"value": float, "unit": str}
-            # 2. Legacy format: flat float/int values
+            # Extract measurements from MeasurementResult format:
+            # MeasurementResult: {"value": float|None, "unit": str, "applicable": bool, ...}
+            # Only include applicable measurements in the report
             measurements = {}
 
             for k, v in analysis_results.items():
-                if isinstance(v, dict) and "value" in v:
-                    # Unified format - extract value for reporting
+                if isinstance(v, dict) and "value" in v and "applicable" in v:
+                    # MeasurementResult format - only include if applicable
+                    if v["applicable"] and v["value"] is not None:
+                        measurements[k] = v["value"]
+                    # Skip inapplicable measurements (they'll show as N/A in detailed views)
+                elif isinstance(v, dict) and "value" in v:
+                    # Legacy unified format (for compatibility)
                     measurements[k] = v["value"]
                 elif isinstance(v, (int, float)) and not isinstance(v, bool):
                     # Legacy flat format