aprender-profile 0.29.0

//! Transpiler Decision Tracing
//!
//! Sprint 26: Capture and analyze transpiler compile-time decisions (v1.0 - stderr)
//! Sprint 27: Memory-mapped file support with hash-based IDs (v2.0 spec)
//!
//! This module enables observability into transpiler decision-making by:
//! 1. Parsing decision traces from stderr (v1.0 - Sprint 26)
//! 2. Reading decision traces from memory-mapped `MessagePack` files (v2.0 - Sprint 27)
//! 3. Correlating decisions with source locations via DWARF
//! 4. Building decision dependency graphs
//! 5. Detecting decision anomalies
//! 6. Profiling decision performance
//!
//! ## v2.0 Specification (Sprint 27)
//!
//! The v2.0 specification addresses critical performance issues identified in peer review:
//! - Hash-based decision IDs (u64) eliminate I-cache bloat from string IDs
//! - Memory-mapped files eliminate I/O blocking from stderr writes
//! - Decision manifest provides human-readable mapping (hash → description)
//!
//! Reference: `docs/specifications/ruchy-tracing-support.md` (v2.0.0)

use memmap2::MmapMut;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::fs::OpenOptions;
use std::hash::Hasher;

/// Sprint 28: Sampling and rate limiting infrastructure (v2.0.0)
///
/// Provides zero-allocation sampling with `DoS` protection for runtime tracing.
/// Reference: `docs/specifications/ruchy-tracing-support.md` §3.2
pub mod sampling {
    use std::cell::Cell;
    use std::sync::atomic::{AtomicU64, Ordering};

    /// Global trace counter for circuit breaker (10,000 traces/sec limit)
    static GLOBAL_TRACE_COUNT: AtomicU64 = AtomicU64::new(0);

    /// Global trace limit per second (circuit breaker threshold)
    pub const GLOBAL_TRACE_LIMIT: u64 = 10_000;

    // Thread-local Xorshift RNG state for fast randomized sampling
    // Uses Xorshift64 algorithm for speed over cryptographic security.
    // Period: 2^64 - 1
    // Reference: Marsaglia (2003) "Xorshift RNGs"
    thread_local! {
        static RNG_STATE: Cell<u64> = Cell::new(seed_from_thread_id());
    }

    /// Seed RNG from thread ID for reproducibility
    fn seed_from_thread_id() -> u64 {
        use std::collections::hash_map::DefaultHasher;
        use std::hash::{Hash, Hasher};

        let thread_id = std::thread::current().id();
        let mut hasher = DefaultHasher::new();
        thread_id.hash(&mut hasher);
        let seed = hasher.finish();

        // Ensure non-zero seed (Xorshift requirement)
        if seed == 0 {
            0xcafebabe
        } else {
            seed
        }
    }

    /// Fast pseudo-random number generator (Xorshift64)
    ///
    /// Returns a uniformly distributed u64 value.
    /// Average cost: 3-5 CPU cycles
    ///
    /// # Example
    /// ```
    /// use renacer::decision_trace::sampling::fast_random;
    ///
    /// let random_value = fast_random();
    /// assert_ne!(random_value, 0); // Extremely unlikely to be zero
    /// ```
    #[inline(always)]
    pub fn fast_random() -> u64 {
        RNG_STATE.with(|state| {
            let mut x = state.get();
            // Xorshift64 algorithm
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            state.set(x);
            x
        })
    }

    /// Check if a trace should be sampled based on probability
    ///
    /// Implements:
    /// 1. Global rate limiter (circuit breaker at 10K traces/sec)
    /// 2. Randomized sampling (eliminates Moiré patterns)
    ///
    /// # Arguments
    /// * `probability` - Sampling probability (0.0 to 1.0)
    ///   - 0.001 = 0.1% (recommended for hot functions)
    ///   - 0.01 = 1.0% (warm functions)
    ///   - 0.1 = 10% (cold functions)
    ///
    /// # Returns
    /// * `true` - Sample this trace
    /// * `false` - Skip this trace
    ///
    /// # Example
    /// ```
    /// use renacer::decision_trace::sampling::should_sample_trace;
    ///
    /// // 0.1% sampling rate for hot function
    /// if should_sample_trace(0.001) {
    ///     // Record trace event
    /// }
    /// ```
    ///
    /// # Performance
    /// - Circuit breaker check: ~2ns (atomic read)
    /// - Random sampling: ~3ns (Xorshift + comparison)
    /// - Total: ~5ns per call
    #[inline(always)]
    pub fn should_sample_trace(probability: f64) -> bool {
        contract_pre_error_handling!();
        // Check global rate limiter first (circuit breaker)
        let current_count = GLOBAL_TRACE_COUNT.load(Ordering::Relaxed);
        if current_count >= GLOBAL_TRACE_LIMIT {
            return false; // Circuit breaker tripped
        }

        // Randomized sampling (eliminates Moiré patterns)
        let threshold = (probability * u64::MAX as f64) as u64;
        if fast_random() < threshold {
            // Increment global counter (relaxed ordering is fine for approximate limit)
            GLOBAL_TRACE_COUNT.fetch_add(1, Ordering::Relaxed);
            return true;
        }
        false
    }

    /// Reset the global trace counter
    ///
    /// Should be called once per second by a background thread or timer.
    ///
    /// # Example
    /// ```no_run
    /// use renacer::decision_trace::sampling::reset_trace_counter;
    /// use std::time::Duration;
    ///
    /// // Background thread resets counter every second
    /// std::thread::spawn(|| {
    ///     loop {
    ///         std::thread::sleep(Duration::from_secs(1));
    ///         reset_trace_counter();
    ///     }
    /// });
    /// ```
    pub fn reset_trace_counter() {
        contract_pre_error_handling!();
        GLOBAL_TRACE_COUNT.store(0, Ordering::Relaxed);
    }

    /// Get current trace count for monitoring
    pub fn get_trace_count() -> u64 {
        GLOBAL_TRACE_COUNT.load(Ordering::Relaxed)
    }

    /// Set a custom trace limit (default: 10,000)
    ///
    /// Useful for testing or custom deployment scenarios.
    pub fn set_trace_limit(_limit: u64) {
        // Note: This is a compile-time constant in the spec,
        // but we provide runtime override for testing
        GLOBAL_TRACE_COUNT.store(0, Ordering::Relaxed);
        // In production, GLOBAL_TRACE_LIMIT would be used directly
    }
}

/// Sprint 27: Decision categories from Ruchy tracing specification (v2.0.0)
///
/// Reference: `docs/specifications/ruchy-tracing-support.md` §2.2
pub mod categories {
    /// Type inference decisions
    pub const TYPE_INFERENCE: &str = "type_inference";
    pub const TYPE_INFERENCE_FUNCTION: &str = "type_inference::infer_function";
    pub const TYPE_INFERENCE_VARIABLE: &str = "type_inference::infer_variable";
    pub const TYPE_INFERENCE_COERCE: &str = "type_inference::coerce_type";
    pub const TYPE_INFERENCE_GENERIC: &str = "type_inference::generic_instantiation";

    /// Optimization decisions
    pub const OPTIMIZATION: &str = "optimization";
    pub const OPTIMIZATION_INLINE: &str = "optimization::inline_candidate";
    pub const OPTIMIZATION_ESCAPE: &str = "optimization::escape_analysis";
    pub const OPTIMIZATION_TAIL_RECURSION: &str = "optimization::tail_recursion";
    pub const OPTIMIZATION_CONST_FOLDING: &str = "optimization::constant_folding";
    pub const OPTIMIZATION_DEAD_CODE: &str = "optimization::dead_code_elimination";

    /// Code generation decisions
    pub const CODEGEN: &str = "codegen";
    pub const CODEGEN_INTEGER_TYPE: &str = "codegen::integer_type";
    pub const CODEGEN_STRING_STRATEGY: &str = "codegen::string_strategy";
    pub const CODEGEN_COLLECTION_TYPE: &str = "codegen::collection_type";
    pub const CODEGEN_ERROR_HANDLING: &str = "codegen::error_handling";

    /// Standard library mapping decisions
    pub const STDLIB: &str = "stdlib";
    pub const STDLIB_IO_MAPPING: &str = "stdlib::io_mapping";
    pub const STDLIB_STRING_METHOD: &str = "stdlib::string_method";
    pub const STDLIB_ARRAY_METHOD: &str = "stdlib::array_method";
}

/// A single transpiler decision trace point
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DecisionTrace {
    /// Timestamp (relative to trace start)
    pub timestamp_us: u64,

    /// Decision category (e.g., "`exception_flow_analysis`", "`type_inference`")
    pub category: String,

    /// Decision name (e.g., "`try_body`", "`infer_return_type`")
    pub name: String,

    /// Decision input (structured data)
    pub input: serde_json::Value,

    /// Decision result/output (if available)
    pub result: Option<serde_json::Value>,

    /// Source location where decision was made (<file:line> function)
    pub source_location: Option<String>,

    /// Sprint 27 (v2.0): Hash-based decision ID (FNV-1a)
    ///
    /// Generated from `category::name::file::line` using FNV-1a algorithm.
    /// Eliminates I-cache bloat from string-based IDs.
    pub decision_id: Option<u64>,
}

/// Sprint 27 (v2.0): Decision manifest entry
///
/// Maps u64 `decision_id` to human-readable description.
/// This is the "sidecar" file (`.ruchy/decision_manifest.json`) that
/// makes hash-based traces interpretable.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DecisionManifestEntry {
    /// FNV-1a hash of `category::name::file::line`
    pub decision_id: u64,

    /// Decision category (e.g., "optimization", "`type_inference`")
    pub category: String,

    /// Decision name (e.g., "`inline_candidate`", "`infer_function`")
    pub name: String,

    /// Source location where decision was made
    pub source: SourceLocation,

    /// Decision input parameters (from transpiler)
    pub input: serde_json::Value,

    /// Decision result/output (from transpiler)
    pub result: serde_json::Value,
}

/// Source location in Ruby/transpiled code
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct SourceLocation {
    /// Source file path (e.g., "foo.rb")
    pub file: String,

    /// Line number (1-indexed)
    pub line: u32,

    /// Column number (optional, 1-indexed)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub column: Option<u32>,
}

/// Sprint 27 (v2.0): Decision manifest (JSON sidecar)
///
/// Complete mapping of all decision IDs to their human-readable descriptions.
/// Loaded from `.ruchy/decision_manifest.json`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DecisionManifest {
    /// Manifest version (for forward compatibility)
    pub version: String,

    /// Git commit hash (for trace correlation)
    pub git_commit: Option<String>,

    /// Transpiler version
    pub transpiler_version: Option<String>,

    /// Map of `decision_id` (hex string) → manifest entry
    #[serde(flatten)]
    pub entries: HashMap<String, DecisionManifestEntry>,
}

/// Sprint 27 (v2.0): Generate decision ID using FNV-1a hash algorithm
///
/// Creates a unique 64-bit hash from decision metadata:
/// `category::name::file::line`
///
/// # Arguments
/// * `category` - Decision category (e.g., "optimization", "`type_inference`")
/// * `name` - Decision name (e.g., "`inline_candidate`", "`infer_function`")
/// * `file` - Source file path (e.g., "foo.rb")
/// * `line` - Line number in source file
///
/// # Returns
/// 64-bit FNV-1a hash that uniquely identifies this decision
///
/// # Example
/// ```
/// use renacer::decision_trace::generate_decision_id;
///
/// let decision_id = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
/// assert_ne!(decision_id, 0); // Should be non-zero
///
/// // Deterministic - same inputs produce same hash
/// let decision_id2 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
/// assert_eq!(decision_id, decision_id2);
/// ```
///
/// # Performance
/// FNV-1a is chosen for speed (single pass, simple operations) over cryptographic
/// security. The 64-bit hash space (2^64 = 18 quintillion) makes collisions
/// extremely unlikely in practice.
///
/// Reference: <http://www.isthe.com/chongo/tech/comp/fnv/>
pub fn generate_decision_id(category: &str, name: &str, file: &str, line: u32) -> u64 {
    let mut hasher = fnv::FnvHasher::default();

    // Hash format: "category::name::file::line"
    hasher.write(category.as_bytes());
    hasher.write(b"::");
    hasher.write(name.as_bytes());
    hasher.write(b"::");
    hasher.write(file.as_bytes());
    hasher.write(b"::");
    hasher.write(&line.to_le_bytes());

    hasher.finish()
}

/// Sprint 27 (v2.0): `DecisionManifest` implementation
impl DecisionManifest {
    /// Load decision manifest from JSON file
    ///
    /// # Arguments
    /// * `path` - Path to `.ruchy/decision_manifest.json`
    ///
    /// # Returns
    /// * `Ok(DecisionManifest)` - Successfully loaded manifest
    /// * `Err(String)` - Error reading or parsing file
    ///
    /// # Example
    /// ```no_run
    /// use renacer::decision_trace::DecisionManifest;
    /// use std::path::Path;
    ///
    /// let manifest = DecisionManifest::load_from_file(
    ///     Path::new(".ruchy/decision_manifest.json")
    /// ).expect("test");
    /// ```
    pub fn load_from_file(path: &std::path::Path) -> Result<Self, String> {
        let contents = std::fs::read_to_string(path)
            .map_err(|e| format!("Failed to read manifest file: {e}"))?;

        let manifest: DecisionManifest = serde_json::from_str(&contents)
            .map_err(|e| format!("Failed to parse manifest JSON: {e}"))?;

        Ok(manifest)
    }
}

/// Sprint 27 (v2.0): Read decision traces from `MessagePack` file
///
/// Reads binary decision trace file (`.ruchy/decisions.msgpack`) produced
/// by the Ruchy transpiler during compilation.
///
/// # Arguments
/// * `path` - Path to `.ruchy/decisions.msgpack`
///
/// # Returns
/// * `Ok(Vec<DecisionTrace>)` - Successfully loaded traces
/// * `Err(String)` - Error reading or deserializing file
///
/// # Example
/// ```no_run
/// use renacer::decision_trace::read_decisions_from_msgpack;
/// use std::path::Path;
///
/// let traces = read_decisions_from_msgpack(
///     Path::new(".ruchy/decisions.msgpack")
/// ).expect("test");
/// println!("Loaded {} decision traces", traces.len());
/// ```
pub fn read_decisions_from_msgpack(path: &std::path::Path) -> Result<Vec<DecisionTrace>, String> {
    let contents = std::fs::read(path).map_err(|e| format!("Failed to read msgpack file: {e}"))?;

    if contents.is_empty() {
        return Err("MessagePack file is empty".to_string());
    }

    let traces: Vec<DecisionTrace> = rmp_serde::from_slice(&contents)
        .map_err(|e| format!("Failed to deserialize msgpack: {e}"))?;

    Ok(traces)
}

/// Sprint 27 (v2.0): Memory-mapped decision writer
///
/// Provides zero-blocking writes for transpiler decisions by using memory-mapped I/O.
/// This eliminates stderr blocking that can slow down transpilation.
///
/// ## Design
///
/// 1. Pre-allocates a file of specified size
/// 2. Memory-maps the file for direct memory access
/// 3. Appends decisions as `MessagePack` data
/// 4. Auto-flushes on Drop to ensure data persistence
///
/// ## Example
///
/// ```no_run
/// use renacer::decision_trace::{MmapDecisionWriter, DecisionTrace, generate_decision_id};
/// use std::path::Path;
///
/// let mut writer = MmapDecisionWriter::new(
///     Path::new(".ruchy/decisions.msgpack"),
///     1024 * 1024  // 1 MB
/// ).expect("test");
///
/// let decision = DecisionTrace {
///     timestamp_us: 1000,
///     category: "optimization".to_string(),
///     name: "inline".to_string(),
///     input: serde_json::json!({"size": 10}),
///     result: Some(serde_json::json!({"decision": "yes"})),
///     source_location: Some("foo.rb:42".to_string()),
///     decision_id: Some(generate_decision_id("optimization", "inline", "foo.rb", 42)),
/// };
///
/// writer.append(&decision).expect("test");
/// writer.flush().expect("test");
/// ```
pub struct MmapDecisionWriter {
    mmap: MmapMut,
    offset: usize,
    decisions: Vec<DecisionTrace>,
}

impl MmapDecisionWriter {
    /// Create a new memory-mapped decision writer
    ///
    /// # Allows
    /// `unsafe_code` — `MmapMut::map_mut` requires unsafe for memory-mapped I/O.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to output file (e.g., `.ruchy/decisions.msgpack`)
    /// * `size` - Pre-allocated file size in bytes (default: 1 MB)
    ///
    /// # Returns
    ///
    /// * `Ok(MmapDecisionWriter)` - Successfully created writer
    /// * `Err(String)` - Error creating file or mmap
    #[allow(unsafe_code)]
    pub fn new(path: &std::path::Path, size: usize) -> Result<Self, String> {
        // Create parent directory if needed
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| format!("Failed to create parent directory: {e}"))?;
        }

        // Create and pre-allocate file
        let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(true)
            .open(path)
            .map_err(|e| format!("Failed to create file: {e}"))?;

        file.set_len(size as u64).map_err(|e| format!("Failed to set file size: {e}"))?;

        // SAFETY: File is valid, open with write access, and sized appropriately for mmap
        let mmap = unsafe {
            MmapMut::map_mut(&file).map_err(|e| format!("Failed to create memory map: {e}"))?
        };

        Ok(Self { mmap, offset: 0, decisions: Vec::new() })
    }

    /// Append a decision to the memory-mapped file
    ///
    /// Decisions are buffered in memory and serialized on flush.
    ///
    /// # Arguments
    ///
    /// * `decision` - Decision trace to append
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Successfully appended
    /// * `Err(String)` - Error serializing or buffer full
    pub fn append(&mut self, decision: &DecisionTrace) -> Result<(), String> {
        // Buffer decision in memory (will serialize on flush)
        self.decisions.push(decision.clone());
        Ok(())
    }

    /// Flush buffered decisions to memory-mapped file
    ///
    /// Serializes all buffered decisions to `MessagePack` and writes to mmap.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Successfully flushed
    /// * `Err(String)` - Error serializing or writing
    pub fn flush(&mut self) -> Result<(), String> {
        if self.decisions.is_empty() {
            return Ok(());
        }

        // Serialize decisions to MessagePack
        let packed = rmp_serde::to_vec(&self.decisions)
            .map_err(|e| format!("Failed to serialize decisions: {e}"))?;

        // Check if we have enough space
        if self.offset + packed.len() > self.mmap.len() {
            return Err(format!(
                "Memory-mapped file too small: need {} bytes, have {} bytes remaining",
                packed.len(),
                self.mmap.len() - self.offset
            ));
        }

        // Write to memory-mapped region
        self.mmap[self.offset..self.offset + packed.len()].copy_from_slice(&packed);
        self.offset += packed.len();

        // Flush mmap to disk
        self.mmap.flush().map_err(|e| format!("Failed to flush mmap: {e}"))?;

        Ok(())
    }

    /// Get the number of buffered decisions
    pub fn len(&self) -> usize {
        self.decisions.len()
    }

    /// Check if buffer is empty
    pub fn is_empty(&self) -> bool {
        self.decisions.is_empty()
    }
}

impl Drop for MmapDecisionWriter {
    /// Auto-flush on drop to ensure data persistence
    fn drop(&mut self) {
        let _ = self.flush();
    }
}

/// Decision trace collector
#[derive(Debug)]
pub struct DecisionTracer {
    traces: Vec<DecisionTrace>,
    start_time: std::time::Instant,
}

impl DecisionTracer {
    /// Create a new decision tracer
    pub fn new() -> Self {
        Self { traces: Vec::new(), start_time: std::time::Instant::now() }
    }

    /// Parse a decision trace line from stderr
    ///
    /// Expected format: `[DECISION] category::name input={"key":"value"}`
    /// Or: `[RESULT] name = {"result":"value"}`
    pub fn parse_line(&mut self, line: &str) -> Result<(), String> {
        let timestamp_us = self.start_time.elapsed().as_micros() as u64;

        if line.starts_with("[DECISION]") {
            self.parse_decision_line(line, timestamp_us)
        } else if line.starts_with("[RESULT]") {
            self.parse_result_line(line, timestamp_us)
        } else {
            // Not a decision trace line, ignore
            Ok(())
        }
    }

    /// Parse decision line: `[DECISION] category::name input={"key":"value"}`
    fn parse_decision_line(&mut self, line: &str, timestamp_us: u64) -> Result<(), String> {
        // Strip [DECISION] prefix
        let content = line.strip_prefix("[DECISION]").ok_or("Missing [DECISION] prefix")?.trim();

        // Split into "category::name" and "input=..."
        let parts: Vec<&str> = content.splitn(2, " input=").collect();
        if parts.len() != 2 {
            return Err(format!("Invalid DECISION format: {line}"));
        }

        // Parse category::name
        let category_name = parts[0];
        let cat_name_parts: Vec<&str> = category_name.split("::").collect();
        if cat_name_parts.len() != 2 {
            return Err(format!("Invalid category::name format: {category_name}"));
        }

        let category = cat_name_parts[0].to_string();
        let name = cat_name_parts[1].to_string();

        // Parse JSON input
        let input: serde_json::Value =
            serde_json::from_str(parts[1]).map_err(|e| format!("Invalid JSON input: {e}"))?;

        self.traces.push(DecisionTrace {
            timestamp_us,
            category,
            name,
            input,
            result: None,
            source_location: None,
            decision_id: None, // Sprint 27: v1.0 stderr format doesn't include hash IDs
        });

        Ok(())
    }

    /// Parse result line: `[RESULT] name = {"result":"value"}`
    fn parse_result_line(&mut self, line: &str, _timestamp_us: u64) -> Result<(), String> {
        // Strip [RESULT] prefix
        let content = line.strip_prefix("[RESULT]").ok_or("Missing [RESULT] prefix")?.trim();

        // Split into "name" and "= {...}"
        let parts: Vec<&str> = content.splitn(2, " = ").collect();
        if parts.len() != 2 {
            return Err(format!("Invalid RESULT format: {line}"));
        }

        let name = parts[0].trim();

        // Parse JSON result
        let result: serde_json::Value =
            serde_json::from_str(parts[1]).map_err(|e| format!("Invalid JSON result: {e}"))?;

        // Find the most recent decision with this name and attach result
        for trace in self.traces.iter_mut().rev() {
            if trace.name == name && trace.result.is_none() {
                trace.result = Some(result);
                return Ok(());
            }
        }

        Err(format!("No matching DECISION found for RESULT: {name}"))
    }

    /// Get all collected traces
    pub fn traces(&self) -> &[DecisionTrace] {
        &self.traces
    }

    /// Get trace count
    pub fn count(&self) -> usize {
        self.traces.len()
    }

    /// Sprint 27 (v2.0): Add decision with full metadata including `decision_id`
    ///
    /// This is the v2.0 API for adding decisions with hash-based IDs.
    ///
    /// # Arguments
    /// * `category` - Decision category (e.g., "optimization", "`type_inference`")
    /// * `name` - Decision name (e.g., "`inline_candidate`", "`infer_function`")
    /// * `input` - Decision input parameters
    /// * `result` - Decision result/output (optional)
    /// * `source_location` - Source location string (e.g., "foo.rb:42")
    /// * `decision_id` - Pre-computed FNV-1a hash ID
    pub fn add_decision_with_id(
        &mut self,
        category: &str,
        name: &str,
        input: serde_json::Value,
        result: Option<serde_json::Value>,
        source_location: Option<&str>,
        decision_id: Option<u64>,
    ) {
        let timestamp_us = self.start_time.elapsed().as_micros() as u64;

        self.traces.push(DecisionTrace {
            timestamp_us,
            category: category.to_string(),
            name: name.to_string(),
            input,
            result,
            source_location: source_location.map(std::string::ToString::to_string),
            decision_id,
        });
    }

    /// Sprint 27 (v2.0): Write traces to `MessagePack` file
    ///
    /// Writes all collected decision traces to a binary `MessagePack` file.
    /// This is the v2.0 output format (`.ruchy/decisions.msgpack`).
    ///
    /// # Arguments
    /// * `path` - Path to output file (e.g., `.ruchy/decisions.msgpack`)
    ///
    /// # Returns
    /// * `Ok(())` - Successfully wrote file
    /// * `Err(String)` - Error writing or serializing
    pub fn write_to_msgpack(&self, path: &std::path::Path) -> Result<(), String> {
        let packed = rmp_serde::to_vec(&self.traces)
            .map_err(|e| format!("Failed to serialize traces to MessagePack: {e}"))?;

        std::fs::write(path, packed)
            .map_err(|e| format!("Failed to write MessagePack file: {e}"))?;

        Ok(())
    }

    /// Sprint 27 (v2.0): Generate and write decision manifest
    ///
    /// Creates the JSON sidecar file (`.ruchy/decision_manifest.json`) that
    /// maps u64 decision IDs to human-readable descriptions.
    ///
    /// # Arguments
    /// * `path` - Path to output file (e.g., `.ruchy/decision_manifest.json`)
    /// * `version` - Manifest version (e.g., "2.0.0")
    /// * `git_commit` - Optional git commit hash
    /// * `transpiler_version` - Optional transpiler version
    ///
    /// # Returns
    /// * `Ok(())` - Successfully wrote manifest
    /// * `Err(String)` - Error generating or writing manifest
    pub fn write_manifest(
        &self,
        path: &std::path::Path,
        version: &str,
        git_commit: Option<&str>,
        transpiler_version: Option<&str>,
    ) -> Result<(), String> {
        let mut entries = HashMap::new();

        // Build manifest entries from traces
        for trace in &self.traces {
            if let Some(decision_id) = trace.decision_id {
                // Parse source location into SourceLocation struct
                let source = if let Some(ref loc) = trace.source_location {
                    // Parse "file.rb:line" or "file.rb:line:column"
                    let parts: Vec<&str> = loc.split(':').collect();
                    if parts.len() >= 2 {
                        let file = parts[0].to_string();
                        let line = parts[1].parse::<u32>().unwrap_or(0);
                        let column =
                            if parts.len() >= 3 { parts[2].parse::<u32>().ok() } else { None };
                        SourceLocation { file, line, column }
                    } else {
                        // Fallback if parsing fails
                        SourceLocation { file: loc.clone(), line: 0, column: None }
                    }
                } else {
                    // No source location available
                    SourceLocation { file: "unknown".to_string(), line: 0, column: None }
                };

                let entry = DecisionManifestEntry {
                    decision_id,
                    category: trace.category.clone(),
                    name: trace.name.clone(),
                    source,
                    input: trace.input.clone(),
                    result: trace.result.clone().unwrap_or(serde_json::Value::Null),
                };

                // Use hex string as key (e.g., "0xDEADBEEF")
                let key = format!("0x{decision_id:X}");
                entries.insert(key, entry);
            }
        }

        let manifest = DecisionManifest {
            version: version.to_string(),
            git_commit: git_commit.map(std::string::ToString::to_string),
            transpiler_version: transpiler_version.map(std::string::ToString::to_string),
            entries,
        };

        // Serialize to pretty JSON
        let json = serde_json::to_string_pretty(&manifest)
            .map_err(|e| format!("Failed to serialize manifest to JSON: {e}"))?;

        std::fs::write(path, json).map_err(|e| format!("Failed to write manifest file: {e}"))?;

        Ok(())
    }
}

impl Default for DecisionTracer {
    fn default() -> Self {
        Self::new()
    }
}

/// Decision dependency graph
#[derive(Debug)]
pub struct DecisionGraph {
    /// Adjacency list: `decision_id` -> Vec<`dependent_decision_id`>
    dependencies: HashMap<usize, Vec<usize>>,
    traces: Vec<DecisionTrace>,
}

impl DecisionGraph {
    /// Build dependency graph from traces
    pub fn from_traces(traces: Vec<DecisionTrace>) -> Self {
        let mut graph = Self { dependencies: HashMap::new(), traces };

        graph.analyze_dependencies();
        graph
    }

    /// Analyze decision dependencies based on data flow
    fn analyze_dependencies(&mut self) {
        // Simple heuristic: if decision B's input contains values from decision A's result,
        // then B depends on A
        for i in 0..self.traces.len() {
            for j in (i + 1)..self.traces.len() {
                if self.has_dependency(i, j) {
                    self.dependencies.entry(i).or_default().push(j);
                }
            }
        }
    }

    /// Check if decision j depends on decision i
    fn has_dependency(&self, i: usize, j: usize) -> bool {
        // Check if any result value from i appears in input of j
        if let Some(ref result_i) = self.traces[i].result {
            let input_j = &self.traces[j].input;

            // Simple check: convert to strings and look for substring
            let result_str = serde_json::to_string(result_i).unwrap_or_default();
            let input_str = serde_json::to_string(input_j).unwrap_or_default();

            // Look for matching values (simplified heuristic)
            // Need at least 3 chars to strip outer delimiters (e.g., `"x"`)
            if result_str.len() >= 3 && input_str.contains(&result_str[1..result_str.len() - 1]) {
                return true;
            }
        }

        false
    }

    /// Find decision cascades (chains of dependent decisions)
    pub fn find_cascades(&self) -> Vec<Vec<usize>> {
        let mut cascades = Vec::new();

        for start_idx in 0..self.traces.len() {
            let mut cascade = vec![start_idx];
            let mut current = start_idx;

            while let Some(deps) = self.dependencies.get(&current) {
                if let Some(&next) = deps.first() {
                    cascade.push(next);
                    current = next;
                } else {
                    break;
                }
            }

            if cascade.len() > 1 {
                cascades.push(cascade);
            }
        }

        cascades
    }

    /// Get dependencies for a decision
    pub fn dependencies(&self, decision_idx: usize) -> Option<&Vec<usize>> {
        self.dependencies.get(&decision_idx)
    }
}

// Compile-time thread-safety verification (Sprint 59)
static_assertions::assert_impl_all!(DecisionTrace: Send, Sync);
static_assertions::assert_impl_all!(DecisionManifestEntry: Send, Sync);
static_assertions::assert_impl_all!(DecisionManifest: Send, Sync);
static_assertions::assert_impl_all!(DecisionGraph: Send, Sync);

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_decision_tracer_new() {
        let tracer = DecisionTracer::new();
        assert_eq!(tracer.count(), 0);
    }

    #[test]
    fn test_parse_decision_line_basic() {
        let mut tracer = DecisionTracer::new();
        let result =
            tracer.parse_line(r#"[DECISION] exception_flow::try_body input={"handlers":2}"#);
        assert!(result.is_ok(), "Parse should succeed: {:?}", result);
        assert_eq!(tracer.count(), 1);

        let trace = &tracer.traces()[0];
        assert_eq!(trace.category, "exception_flow");
        assert_eq!(trace.name, "try_body");
        assert_eq!(trace.input["handlers"], 2);
    }

    #[test]
    fn test_parse_result_line() {
        let mut tracer = DecisionTracer::new();
        tracer
            .parse_line(r#"[DECISION] type_inference::infer_return input={"func":"foo"}"#)
            .expect("test");
        tracer.parse_line(r#"[RESULT] infer_return = {"type":"i32"}"#).expect("test");

        assert_eq!(tracer.count(), 1);
        let trace = &tracer.traces()[0];
        assert!(trace.result.is_some());
        assert_eq!(trace.result.as_ref().expect("test")["type"], "i32");
    }

    #[test]
    fn test_parse_invalid_decision_format() {
        let mut tracer = DecisionTracer::new();
        let result = tracer.parse_line("[DECISION] invalid");
        assert!(result.is_err());
    }

    #[test]
    fn test_parse_invalid_json() {
        let mut tracer = DecisionTracer::new();
        let result = tracer.parse_line(r"[DECISION] cat::name input={invalid}");
        assert!(result.is_err());
    }

    #[test]
    fn test_ignore_non_decision_lines() {
        let mut tracer = DecisionTracer::new();
        let result = tracer.parse_line("Normal stderr output");
        assert!(result.is_ok());
        assert_eq!(tracer.count(), 0);
    }

    #[test]
    fn test_decision_graph_empty() {
        let graph = DecisionGraph::from_traces(vec![]);
        let cascades = graph.find_cascades();
        assert!(cascades.is_empty());
    }

    #[test]
    fn test_decision_graph_single_decision() {
        let trace = DecisionTrace {
            timestamp_us: 100,
            category: "test".to_string(),
            name: "decision1".to_string(),
            input: serde_json::json!({"x": 1}),
            result: Some(serde_json::json!({"y": 2})),
            source_location: None,
            decision_id: None,
        };

        let graph = DecisionGraph::from_traces(vec![trace]);
        let cascades = graph.find_cascades();
        assert!(cascades.is_empty()); // Single decision, no cascade
    }

    // Sprint 27 (v2.0) Tests
    mod sprint27_v2_tests {
        use super::*;

        #[test]
        fn test_generate_decision_id_basic() {
            // RED phase: Test hash generation from category::name::file::line
            let decision_id = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);

            // Should be a valid u64 (non-zero)
            assert_ne!(decision_id, 0);

            // Should be deterministic (same inputs = same output)
            let decision_id2 =
                generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
            assert_eq!(decision_id, decision_id2);
        }

        #[test]
        fn test_generate_decision_id_different_inputs_different_outputs() {
            // Different category
            let id1 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
            let id2 = generate_decision_id("type_inference", "inline_candidate", "foo.rb", 3);
            assert_ne!(id1, id2);

            // Different name
            let id3 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
            let id4 = generate_decision_id("optimization", "tail_recursion", "foo.rb", 3);
            assert_ne!(id3, id4);

            // Different file
            let id5 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
            let id6 = generate_decision_id("optimization", "inline_candidate", "bar.rb", 3);
            assert_ne!(id5, id6);

            // Different line
            let id7 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);
            let id8 = generate_decision_id("optimization", "inline_candidate", "foo.rb", 5);
            assert_ne!(id7, id8);
        }

        #[test]
        fn test_generate_decision_id_spec_example() {
            // From spec: optimization::inline_candidate at foo.rb:3 → 0xA1B2C3D4E5F67890
            // We can't predict exact hash but can verify it's consistent
            let decision_id = generate_decision_id("optimization", "inline_candidate", "foo.rb", 3);

            // Should be 64-bit non-zero value
            assert!(decision_id > 0);
        }

        #[test]
        fn test_decision_manifest_entry_serialization() {
            // Test that DecisionManifestEntry can be serialized to JSON
            let entry = DecisionManifestEntry {
                decision_id: 0xA1B2C3D4E5F67890,
                category: "optimization".to_string(),
                name: "inline_candidate".to_string(),
                source: SourceLocation { file: "foo.rb".to_string(), line: 3, column: Some(1) },
                input: serde_json::json!({"size": 4, "call_count": 1000}),
                result: serde_json::json!({"decision": "no_inline", "reason": "recursive"}),
            };

            let json = serde_json::to_string(&entry).expect("test");
            // The decision_id in the test is 0xA1B2C3D4E5F67890 (hex)
            // which should appear as 11651590505119512720 in the JSON
            assert!(json.contains("decision_id"));
            assert!(json.contains("optimization"));
            assert!(json.contains("inline_candidate"));
            assert!(json.contains("foo.rb"));

            // Verify it can be deserialized back
            let deserialized: DecisionManifestEntry = serde_json::from_str(&json).expect("test");
            assert_eq!(deserialized.decision_id, 0xA1B2C3D4E5F67890);
            assert_eq!(deserialized.category, "optimization");
        }

        #[test]
        fn test_decision_manifest_deserialization() {
            // Test loading a manifest from JSON
            let json = r#"{
                "version": "2.0.0",
                "git_commit": "abc123def",
                "transpiler_version": "3.213.0",
                "0xA1B2C3D4E5F67890": {
                    "decision_id": 11638049751140409488,
                    "category": "optimization",
                    "name": "inline_candidate",
                    "source": {
                        "file": "foo.rb",
                        "line": 3
                    },
                    "input": {"size": 4},
                    "result": {"decision": "no_inline"}
                }
            }"#;

            let manifest: DecisionManifest = serde_json::from_str(json).expect("test");
            assert_eq!(manifest.version, "2.0.0");
            assert_eq!(manifest.git_commit, Some("abc123def".to_string()));
            assert_eq!(manifest.entries.len(), 1);
        }

        #[test]
        fn test_source_location_serialization() {
            let loc = SourceLocation { file: "foo.rb".to_string(), line: 42, column: Some(10) };

            let json = serde_json::to_string(&loc).expect("test");
            assert!(json.contains("foo.rb"));
            assert!(json.contains("42"));
            assert!(json.contains("10"));

            // Without column
            let loc2 = SourceLocation { file: "bar.rb".to_string(), line: 100, column: None };

            let json2 = serde_json::to_string(&loc2).expect("test");
            assert!(json2.contains("bar.rb"));
            assert!(json2.contains("100"));
            assert!(!json2.contains("column")); // Should be skipped
        }

        #[test]
        fn test_load_decision_manifest_from_json() {
            // RED: Test loading manifest from JSON file
            use std::io::Write;
            use tempfile::NamedTempFile;

            let manifest_json = r#"{
                "version": "2.0.0",
                "git_commit": "abc123",
                "transpiler_version": "3.213.0",
                "0xDEADBEEF": {
                    "decision_id": 3735928559,
                    "category": "optimization",
                    "name": "test_decision",
                    "source": {
                        "file": "test.rb",
                        "line": 1
                    },
                    "input": {"param": "value"},
                    "result": {"outcome": "success"}
                }
            }"#;

            let mut temp_file = NamedTempFile::new().expect("test");
            temp_file.write_all(manifest_json.as_bytes()).expect("test");
            temp_file.flush().expect("test");

            let manifest = DecisionManifest::load_from_file(temp_file.path()).expect("test");
            assert_eq!(manifest.version, "2.0.0");
            assert_eq!(manifest.git_commit, Some("abc123".to_string()));
            assert_eq!(manifest.entries.len(), 1);
        }

        #[test]
        fn test_load_decision_manifest_missing_file() {
            // Should return error for missing file
            let result =
                DecisionManifest::load_from_file(std::path::Path::new("/nonexistent/path"));
            assert!(result.is_err());
        }

        #[test]
        fn test_load_decision_manifest_invalid_json() {
            // Should return error for invalid JSON
            use std::io::Write;
            use tempfile::NamedTempFile;

            let mut temp_file = NamedTempFile::new().expect("test");
            temp_file.write_all(b"not valid json {{{").expect("test");
            temp_file.flush().expect("test");

            let result = DecisionManifest::load_from_file(temp_file.path());
            assert!(result.is_err());
        }

        #[test]
        fn test_messagepack_decision_trace_roundtrip() {
            // RED: Test MessagePack serialization/deserialization of DecisionTrace
            let trace = DecisionTrace {
                timestamp_us: 12345,
                category: "optimization".to_string(),
                name: "inline_candidate".to_string(),
                input: serde_json::json!({"size": 10}),
                result: Some(serde_json::json!({"decision": "inline"})),
                source_location: Some("foo.rb:42".to_string()),
                decision_id: Some(0xDEADBEEF),
            };

            // Serialize to MessagePack
            let packed = rmp_serde::to_vec(&trace).expect("test");

            // Deserialize back
            let unpacked: DecisionTrace = rmp_serde::from_slice(&packed).expect("test");

            assert_eq!(unpacked.timestamp_us, 12345);
            assert_eq!(unpacked.category, "optimization");
            assert_eq!(unpacked.decision_id, Some(0xDEADBEEF));
        }

        #[test]
        fn test_read_decisions_from_msgpack_file() {
            // RED: Test reading multiple decisions from .msgpack file
            use std::io::Write;
            use tempfile::NamedTempFile;

            let traces = vec![
                DecisionTrace {
                    timestamp_us: 100,
                    category: "type_inference".to_string(),
                    name: "infer_type".to_string(),
                    input: serde_json::json!({"var": "x"}),
                    result: Some(serde_json::json!({"type": "i32"})),
                    source_location: Some("foo.rb:1".to_string()),
                    decision_id: Some(generate_decision_id(
                        "type_inference",
                        "infer_type",
                        "foo.rb",
                        1,
                    )),
                },
                DecisionTrace {
                    timestamp_us: 200,
                    category: "optimization".to_string(),
                    name: "inline".to_string(),
                    input: serde_json::json!({"size": 5}),
                    result: Some(serde_json::json!({"decision": "yes"})),
                    source_location: Some("foo.rb:10".to_string()),
                    decision_id: Some(generate_decision_id("optimization", "inline", "foo.rb", 10)),
                },
            ];

            // Write to MessagePack file
            let mut temp_file = NamedTempFile::new().expect("test");
            let packed = rmp_serde::to_vec(&traces).expect("test");
            temp_file.write_all(&packed).expect("test");
            temp_file.flush().expect("test");

            // Read back
            let loaded = read_decisions_from_msgpack(temp_file.path()).expect("test");
            assert_eq!(loaded.len(), 2);
            assert_eq!(loaded[0].category, "type_inference");
            assert_eq!(loaded[1].category, "optimization");
        }

        #[test]
        fn test_read_decisions_from_msgpack_empty_file() {
            // Should handle empty file gracefully
            use tempfile::NamedTempFile;

            let temp_file = NamedTempFile::new().expect("test");
            // Empty file

            let result = read_decisions_from_msgpack(temp_file.path());
            assert!(result.is_err() || result.expect("test").is_empty());
        }

        // Sprint 27 Phase 2: DecisionTracer integration tests
        #[test]
        fn test_decision_tracer_write_to_msgpack() {
            // RED: Test DecisionTracer can write traces to MessagePack file
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let msgpack_path = temp_dir.path().join("decisions.msgpack");

            let mut tracer = DecisionTracer::new();

            // Add some traces with decision IDs
            tracer.add_decision_with_id(
                "optimization",
                "inline",
                serde_json::json!({"size": 10}),
                Some(serde_json::json!({"decision": "yes"})),
                Some("foo.rb:42"),
                Some(generate_decision_id("optimization", "inline", "foo.rb", 42)),
            );

            // Write to MessagePack file
            tracer.write_to_msgpack(&msgpack_path).expect("test");

            // Verify file exists and can be read back
            let loaded = read_decisions_from_msgpack(&msgpack_path).expect("test");
            assert_eq!(loaded.len(), 1);
            assert_eq!(loaded[0].category, "optimization");
            assert_eq!(
                loaded[0].decision_id,
                Some(generate_decision_id("optimization", "inline", "foo.rb", 42))
            );
        }

        #[test]
        fn test_decision_tracer_generate_manifest() {
            // RED: Test DecisionTracer can generate decision manifest
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let manifest_path = temp_dir.path().join("decision_manifest.json");

            let mut tracer = DecisionTracer::new();

            // Add trace with complete metadata
            tracer.add_decision_with_id(
                "type_inference",
                "infer_var",
                serde_json::json!({"var": "x"}),
                Some(serde_json::json!({"type": "i32"})),
                Some("test.rb:10"),
                Some(generate_decision_id("type_inference", "infer_var", "test.rb", 10)),
            );

            // Generate manifest
            tracer
                .write_manifest(&manifest_path, "2.0.0", Some("abc123"), Some("3.213.0"))
                .expect("test");

            // Verify manifest can be loaded
            let manifest = DecisionManifest::load_from_file(&manifest_path).expect("test");
            assert_eq!(manifest.version, "2.0.0");
            assert_eq!(manifest.git_commit, Some("abc123".to_string()));
            assert!(!manifest.entries.is_empty());
        }

        // Sprint 27 Phase 2: Property-based tests for hash collision resistance
        use proptest::prelude::*;

        proptest! {
            #[test]
            fn prop_decision_id_deterministic(
                category in "[a-z_]{1,20}",
                name in "[a-z_]{1,20}",
                file in "[a-z_./]{1,30}",
                line in 1u32..10000u32
            ) {
                // Same inputs should always produce same hash
                let id1 = generate_decision_id(&category, &name, &file, line);
                let id2 = generate_decision_id(&category, &name, &file, line);
                assert_eq!(id1, id2, "Hash must be deterministic");
            }

            #[test]
            fn prop_decision_id_different_categories_different_hashes(
                name in "[a-z_]{1,20}",
                file in "[a-z_./]{1,30}",
                line in 1u32..1000u32
            ) {
                // Different categories should produce different hashes
                let id_opt = generate_decision_id("optimization", &name, &file, line);
                let id_type = generate_decision_id("type_inference", &name, &file, line);
                assert_ne!(id_opt, id_type, "Different categories must produce different hashes");
            }

            #[test]
            fn prop_decision_id_different_lines_different_hashes(
                category in "[a-z_]{1,20}",
                name in "[a-z_]{1,20}",
                file in "[a-z_./]{1,30}",
                line1 in 1u32..1000u32,
                line2 in 1000u32..2000u32
            ) {
                // Different line numbers should produce different hashes
                let id1 = generate_decision_id(&category, &name, &file, line1);
                let id2 = generate_decision_id(&category, &name, &file, line2);
                assert_ne!(id1, id2, "Different lines must produce different hashes");
            }

            #[test]
            fn prop_decision_id_nonzero(
                category in "[a-z_]{1,20}",
                name in "[a-z_]{1,20}",
                file in "[a-z_./]{1,30}",
                line in 1u32..10000u32
            ) {
                // Hash should never be zero (FNV-1a offset basis ensures this)
                let id = generate_decision_id(&category, &name, &file, line);
                assert_ne!(id, 0, "Hash should never be zero");
            }

            #[test]
            fn prop_decision_id_uniform_distribution(
                inputs in prop::collection::vec(
                    (
                        prop::string::string_regex("[a-z_]{1,20}").expect("test"),
                        prop::string::string_regex("[a-z_]{1,20}").expect("test"),
                        prop::string::string_regex("[a-z_./]{1,30}").expect("test"),
                        1u32..10000u32
                    ),
                    100..200
                )
            ) {
                // Generate many hashes and check for uniqueness
                let mut hashes = std::collections::HashSet::new();
                let mut collisions = 0;

                for (category, name, file, line) in &inputs {
                    let id = generate_decision_id(category, name, file, *line);
                    if !hashes.insert(id) {
                        collisions += 1;
                    }
                }

                // With 100+ diverse inputs, we expect < 1% collision rate
                // (FNV-1a is designed for low collision rates with diverse inputs)
                let collision_rate = (collisions as f64) / (inputs.len() as f64);
                assert!(
                    collision_rate < 0.01,
                    "Collision rate too high: {:.2}% ({}  collisions out of {} inputs)",
                    collision_rate * 100.0,
                    collisions,
                    inputs.len()
                );
            }
        }

        // Sprint 27 Phase 2: Performance tests
        #[test]
        fn test_hash_generation_performance() {
            // Verify hash generation is fast enough for production use
            // Target: < 100ns per hash (to keep overhead < 5%)
            use std::time::Instant;

            let iterations = 10000;
            let start = Instant::now();

            for i in 0..iterations {
                let _ =
                    generate_decision_id("optimization", "inline_candidate", "foo.rb", i % 1000);
            }

            let elapsed = start.elapsed();
            let avg_time_ns = elapsed.as_nanos() / (iterations as u128);

            println!(
                "Hash generation: {} iterations in {:?} (avg {} ns/hash)",
                iterations, elapsed, avg_time_ns
            );

            // FNV-1a should be very fast - target < 5000ns per hash in CI environments
            // (in release mode with opt-level=3, this is typically < 50ns)
            // CI environments have variable performance, so threshold is relaxed
            assert!(
                avg_time_ns < 5000,
                "Hash generation too slow: {} ns (target < 5000 ns)",
                avg_time_ns
            );
        }

        #[test]
        fn test_msgpack_serialization_performance() {
            // Verify MessagePack serialization is fast
            // Target: serialize 1000 decisions in < 10ms
            use std::time::Instant;

            // Create 1000 decision traces
            let mut traces = Vec::new();
            for i in 0..1000 {
                traces.push(DecisionTrace {
                    timestamp_us: i * 1000,
                    category: "optimization".to_string(),
                    name: "inline".to_string(),
                    input: serde_json::json!({"size": i % 100}),
                    result: Some(serde_json::json!({"decision": "yes"})),
                    source_location: Some(format!("foo.rb:{}", i % 500)),
                    decision_id: Some(generate_decision_id(
                        "optimization",
                        "inline",
                        "foo.rb",
                        (i % 500) as u32,
                    )),
                });
            }

            let start = Instant::now();
            let packed = rmp_serde::to_vec(&traces).expect("test");
            let elapsed = start.elapsed();

            println!(
                "MessagePack serialization: 1000 traces in {:?} ({} bytes)",
                elapsed,
                packed.len()
            );

            // Should be < 500ms for 1000 traces (generous for CI containers with contention)
            assert!(
                elapsed.as_millis() < 500,
                "MessagePack serialization too slow: {:?} (target < 500ms)",
                elapsed
            );
        }

        #[test]
        fn test_decision_tracer_full_v2_roundtrip() {
            // RED: Test full write + read cycle with v2.0 format
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let msgpack_path = temp_dir.path().join("decisions.msgpack");
            let manifest_path = temp_dir.path().join("decision_manifest.json");

            // Create tracer with multiple decisions
            let mut tracer = DecisionTracer::new();

            let decision_id_1 = generate_decision_id("optimization", "inline", "foo.rb", 10);
            let decision_id_2 = generate_decision_id("type_inference", "infer_type", "bar.rb", 20);

            tracer.add_decision_with_id(
                "optimization",
                "inline",
                serde_json::json!({"size": 5}),
                Some(serde_json::json!({"decision": "yes"})),
                Some("foo.rb:10"),
                Some(decision_id_1),
            );

            tracer.add_decision_with_id(
                "type_inference",
                "infer_type",
                serde_json::json!({"var": "x"}),
                Some(serde_json::json!({"type": "String"})),
                Some("bar.rb:20"),
                Some(decision_id_2),
            );

            // Write both files
            tracer.write_to_msgpack(&msgpack_path).expect("test");
            tracer.write_manifest(&manifest_path, "2.0.0", None, None).expect("test");

            // Read back and verify
            let loaded_traces = read_decisions_from_msgpack(&msgpack_path).expect("test");
            let loaded_manifest = DecisionManifest::load_from_file(&manifest_path).expect("test");

            assert_eq!(loaded_traces.len(), 2);
            assert_eq!(loaded_manifest.version, "2.0.0");

            // Verify decision IDs match between traces and manifest
            assert_eq!(loaded_traces[0].decision_id, Some(decision_id_1));
            assert_eq!(loaded_traces[1].decision_id, Some(decision_id_2));
        }

        // Sprint 27 Phase 3: Decision category tests
        #[test]
        fn test_decision_categories_defined() {
            // Verify all 10 decision categories from spec are defined
            use crate::decision_trace::categories::*;

            // Type inference (4 subcategories)
            assert_eq!(TYPE_INFERENCE, "type_inference");
            assert!(TYPE_INFERENCE_FUNCTION.starts_with(TYPE_INFERENCE));
            assert!(TYPE_INFERENCE_VARIABLE.starts_with(TYPE_INFERENCE));
            assert!(TYPE_INFERENCE_COERCE.starts_with(TYPE_INFERENCE));
            assert!(TYPE_INFERENCE_GENERIC.starts_with(TYPE_INFERENCE));

            // Optimization (5 subcategories)
            assert_eq!(OPTIMIZATION, "optimization");
            assert!(OPTIMIZATION_INLINE.starts_with(OPTIMIZATION));
            assert!(OPTIMIZATION_ESCAPE.starts_with(OPTIMIZATION));
            assert!(OPTIMIZATION_TAIL_RECURSION.starts_with(OPTIMIZATION));
            assert!(OPTIMIZATION_CONST_FOLDING.starts_with(OPTIMIZATION));
            assert!(OPTIMIZATION_DEAD_CODE.starts_with(OPTIMIZATION));

            // Code generation (4 subcategories)
            assert_eq!(CODEGEN, "codegen");
            assert!(CODEGEN_INTEGER_TYPE.starts_with(CODEGEN));
            assert!(CODEGEN_STRING_STRATEGY.starts_with(CODEGEN));
            assert!(CODEGEN_COLLECTION_TYPE.starts_with(CODEGEN));
            assert!(CODEGEN_ERROR_HANDLING.starts_with(CODEGEN));

            // Standard library (3 subcategories)
            assert_eq!(STDLIB, "stdlib");
            assert!(STDLIB_IO_MAPPING.starts_with(STDLIB));
            assert!(STDLIB_STRING_METHOD.starts_with(STDLIB));
            assert!(STDLIB_ARRAY_METHOD.starts_with(STDLIB));
        }

        #[test]
        fn test_decision_categories_usage() {
            // Test using decision categories with generate_decision_id
            use crate::decision_trace::categories::*;

            let id1 = generate_decision_id(OPTIMIZATION, "inline_candidate", "foo.rb", 10);
            let id2 = generate_decision_id(TYPE_INFERENCE, "infer_function", "bar.rb", 20);

            assert_ne!(id1, id2);
            assert_ne!(id1, 0);
            assert_ne!(id2, 0);
        }

        // Sprint 27 Phase 3: Memory-mapped file writer tests
        #[test]
        fn test_mmap_writer_create() {
            // RED: Test creating memory-mapped decision writer
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let mmap_path = temp_dir.path().join("decisions.msgpack");

            // Create writer with pre-allocated size
            let writer = MmapDecisionWriter::new(&mmap_path, 1024 * 1024).expect("test"); // 1 MB

            // Verify file exists and has correct size
            assert!(mmap_path.exists());
            let metadata = std::fs::metadata(&mmap_path).expect("test");
            assert_eq!(metadata.len(), 1024 * 1024);

            drop(writer);
        }

        #[test]
        fn test_mmap_writer_append_decision() {
            // RED: Test appending decisions to memory-mapped file
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let mmap_path = temp_dir.path().join("decisions.msgpack");

            let mut writer = MmapDecisionWriter::new(&mmap_path, 1024 * 1024).expect("test");

            // Append a decision
            let decision = DecisionTrace {
                timestamp_us: 1000,
                category: "optimization".to_string(),
                name: "inline".to_string(),
                input: serde_json::json!({"size": 10}),
                result: Some(serde_json::json!({"decision": "yes"})),
                source_location: Some("foo.rb:42".to_string()),
                decision_id: Some(generate_decision_id("optimization", "inline", "foo.rb", 42)),
            };

            writer.append(&decision).expect("test");

            // Flush to disk
            writer.flush().expect("test");

            drop(writer);

            // Verify can read back
            let loaded = read_decisions_from_msgpack(&mmap_path).expect("test");
            assert_eq!(loaded.len(), 1);
            assert_eq!(loaded[0].category, "optimization");
        }

        #[test]
        fn test_mmap_writer_append_multiple() {
            // RED: Test appending multiple decisions
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let mmap_path = temp_dir.path().join("decisions.msgpack");

            let mut writer = MmapDecisionWriter::new(&mmap_path, 1024 * 1024).expect("test");

            // Append 100 decisions
            for i in 0..100 {
                let decision = DecisionTrace {
                    timestamp_us: i * 1000,
                    category: "optimization".to_string(),
                    name: "inline".to_string(),
                    input: serde_json::json!({"size": i}),
                    result: Some(serde_json::json!({"decision": "yes"})),
                    source_location: Some(format!("foo.rb:{}", i)),
                    decision_id: Some(generate_decision_id(
                        "optimization",
                        "inline",
                        "foo.rb",
                        i as u32,
                    )),
                };

                writer.append(&decision).expect("test");
            }

            writer.flush().expect("test");
            drop(writer);

            // Verify all decisions were written
            let loaded = read_decisions_from_msgpack(&mmap_path).expect("test");
            assert_eq!(loaded.len(), 100);
        }

        #[test]
        fn test_mmap_writer_no_blocking() {
            // RED: Verify mmap write doesn't block (performance test)
            use std::time::Instant;
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let mmap_path = temp_dir.path().join("decisions.msgpack");

            let mut writer = MmapDecisionWriter::new(&mmap_path, 10 * 1024 * 1024).expect("test"); // 10 MB

            let decision = DecisionTrace {
                timestamp_us: 1000,
                category: "optimization".to_string(),
                name: "inline".to_string(),
                input: serde_json::json!({"size": 10}),
                result: Some(serde_json::json!({"decision": "yes"})),
                source_location: Some("foo.rb:42".to_string()),
                decision_id: Some(generate_decision_id("optimization", "inline", "foo.rb", 42)),
            };

            // Write 1000 decisions and measure time
            let start = Instant::now();
            for _ in 0..1000 {
                writer.append(&decision).expect("test");
            }
            let elapsed = start.elapsed();

            println!(
                "Mmap write: 1000 decisions in {:?} (avg {} ns/decision)",
                elapsed,
                elapsed.as_nanos() / 1000
            );

            // Should be < 30ms total in debug mode under CI load (< 30us per decision)
            // When running in isolation: typically < 2ms
            // In release mode with optimizations, this is typically < 500us
            // This is much faster than stderr which can block for 10-100ms
            // Note: Threshold increased from 15ms for coverage instrumentation overhead
            assert!(
                elapsed.as_micros() < 30000,
                "Mmap write too slow: {:?} (target < 30ms debug, < 500us release)",
                elapsed
            );
        }

        #[test]
        fn test_mmap_writer_auto_flush_on_drop() {
            // RED: Verify writer auto-flushes on drop
            use tempfile::TempDir;

            let temp_dir = TempDir::new().expect("test");
            let mmap_path = temp_dir.path().join("decisions.msgpack");

            {
                let mut writer = MmapDecisionWriter::new(&mmap_path, 1024 * 1024).expect("test");

                let decision = DecisionTrace {
                    timestamp_us: 1000,
                    category: "optimization".to_string(),
                    name: "inline".to_string(),
                    input: serde_json::json!({"size": 10}),
                    result: Some(serde_json::json!({"decision": "yes"})),
                    source_location: Some("foo.rb:42".to_string()),
                    decision_id: Some(generate_decision_id("optimization", "inline", "foo.rb", 42)),
                };

                writer.append(&decision).expect("test");

                // Don't call flush() - rely on Drop
            } // writer dropped here

            // Verify decision was written
            let loaded = read_decisions_from_msgpack(&mmap_path).expect("test");
            assert_eq!(loaded.len(), 1);
        }

        // Sprint 28: Sampling and rate limiting tests
        mod sprint28_sampling_tests {
            use crate::decision_trace::sampling::*;
            use serial_test::serial;

            #[test]
            fn test_fast_random_non_zero() {
                // Xorshift should almost never return 0
                for _ in 0..1000 {
                    let r = fast_random();
                    // Allow one zero in 1000 (probability: 1/2^64)
                    if r == 0 {
                        println!("Warning: fast_random() returned 0 (extremely unlikely)");
                    }
                }
            }

            #[test]
            fn test_fast_random_deterministic_per_thread() {
                // Same thread should produce deterministic sequence
                let r1 = fast_random();
                let r2 = fast_random();
                let r3 = fast_random();

                // Values should be different from each other
                assert_ne!(r1, r2);
                assert_ne!(r2, r3);
                assert_ne!(r1, r3);
            }

            #[test]
            fn test_should_sample_trace_probability_zero() {
                // Probability 0.0 should never sample
                for _ in 0..1000 {
                    assert!(!should_sample_trace(0.0));
                }
            }

            #[test]
            #[serial]
            fn test_should_sample_trace_probability_one() {
                // Probability 1.0 should always sample (until rate limit)
                reset_trace_counter();
                let count_before = get_trace_count();
                let mut count = 0;
                for _ in 0..100 {
                    if should_sample_trace(1.0) {
                        count += 1;
                    }
                }
                // Should have sampled all 100 (unless we hit rate limit)
                assert!(count >= 90, "Expected ~100 samples, got {}", count);
                // Counter should have increased
                assert!(get_trace_count() >= count_before + 90);
            }

            #[test]
            #[serial]
            fn test_should_sample_trace_rate_limiter() {
                // Circuit breaker should trip at GLOBAL_TRACE_LIMIT
                reset_trace_counter();

                // Fill up to limit with probability 1.0
                for _ in 0..GLOBAL_TRACE_LIMIT {
                    assert!(should_sample_trace(1.0));
                }

                assert_eq!(get_trace_count(), GLOBAL_TRACE_LIMIT);

                // Next samples should be rejected (circuit breaker)
                for _ in 0..100 {
                    assert!(!should_sample_trace(1.0));
                }

                // Count should not increase
                assert_eq!(get_trace_count(), GLOBAL_TRACE_LIMIT);
            }

            #[test]
            #[serial]
            fn test_reset_trace_counter() {
                // Fill counter
                reset_trace_counter();
                for _ in 0..1000 {
                    should_sample_trace(1.0);
                }
                assert_eq!(get_trace_count(), 1000);

                // Reset
                reset_trace_counter();
                assert_eq!(get_trace_count(), 0);

                // Can sample again
                assert!(should_sample_trace(1.0));
            }

            #[test]
            #[serial]
            fn test_sampling_rate_approximate() {
                // Test that sampling rate is approximately correct
                reset_trace_counter();
                let probability = 0.1; // 10%
                let iterations = 10_000;
                let mut sampled_count = 0;

                for _ in 0..iterations {
                    if should_sample_trace(probability) {
                        sampled_count += 1;
                    }
                }

                // Should be approximately 10% (within 20% tolerance for randomness)
                let expected = (iterations as f64 * probability) as usize;
                let lower_bound = (expected as f64 * 0.8) as usize;
                let upper_bound = (expected as f64 * 1.2) as usize;

                assert!(
                    sampled_count >= lower_bound && sampled_count <= upper_bound,
                    "Sampled {} out of {}, expected ~{} (range: {}-{})",
                    sampled_count,
                    iterations,
                    expected,
                    lower_bound,
                    upper_bound
                );
            }

            #[test]
            #[ignore = "Performance test - fails under coverage instrumentation"]
            fn test_xorshift_performance() {
                // Verify Xorshift is fast enough (<10ns per call)
                use std::time::Instant;

                let iterations = 100_000;
                let start = Instant::now();

                for _ in 0..iterations {
                    let _ = fast_random();
                }

                let elapsed = start.elapsed();
                let avg_ns = elapsed.as_nanos() / iterations;

                println!(
                    "Xorshift performance: {} iterations in {:?} (avg {} ns/call)",
                    iterations, elapsed, avg_ns
                );

                // Should be <10ns per call in debug mode, <5ns in release
                // Allow 50ns headroom for coverage instrumentation and system variance
                assert!(
                    avg_ns < 50,
                    "Xorshift too slow: {} ns/call (target < 50ns with coverage)",
                    avg_ns
                );
            }

            #[test]
            #[serial]
            #[ignore = "Performance test - fails under coverage instrumentation"]
            fn test_sampling_decision_performance() {
                // Verify should_sample_trace is fast enough (<20ns per call)
                use std::time::Instant;

                reset_trace_counter();
                let iterations = 100_000;
                let start = Instant::now();

                for _ in 0..iterations {
                    let _ = should_sample_trace(0.001); // 0.1% sampling
                }

                let elapsed = start.elapsed();
                let avg_ns = elapsed.as_nanos() / iterations;

                println!(
                    "Sampling decision performance: {} iterations in {:?} (avg {} ns/call)",
                    iterations, elapsed, avg_ns
                );

                // Target: <20ns per call in debug mode (includes atomic ops)
                assert!(
                    avg_ns < 50,
                    "Sampling decision too slow: {} ns/call (target < 50ns debug)",
                    avg_ns
                );
            }
        }

        // Sprint 28: Property-based tests for sampling
        mod sprint28_sampling_property_tests {
            use crate::decision_trace::sampling::*;
            use serial_test::serial;

            use proptest::proptest;

            proptest! {
                #[test]
                fn prop_xorshift_non_zero(iterations in 1usize..1000) {
                    // Xorshift should produce non-zero values
                    let mut zero_count = 0;
                    for _ in 0..iterations {
                        if fast_random() == 0 {
                            zero_count += 1;
                        }
                    }
                    // At most 1 zero allowed (probability: ~1/2^64)
                    assert!(zero_count <= 1);
                }

                #[test]
                #[serial]
                fn prop_sampling_rate_bounded(probability in 0.0f64..=1.0f64) {
                    // Reset for clean test
                    reset_trace_counter();

                    let iterations = 1000;
                    let mut sampled = 0;

                    for _ in 0..iterations {
                        if should_sample_trace(probability) {
                            sampled += 1;
                        }
                    }

                    // Sampled count should never exceed iterations
                    assert!(sampled <= iterations);

                    // Should respect rate limit (give some margin for parallel tests)
                    assert!(get_trace_count() <= GLOBAL_TRACE_LIMIT * 2);
                }
            }
        }
    }
}