llvm-native-core 0.1.13

//! X86 Stack Probing & Dynamic Stack Realignment — complete stack probing,
//! dynamic stack allocation, stack clash protection, and dynamic stack
//! realignment for X86/X86-64 targets.
//!
//! Phase 12 — LLVM.TARGET.X86.STACK_PROBING Court.
//!
//! This module provides:
//! - **Stack probing**: Touch each page of new stack space to ensure guard
//!   pages are hit before accessing stack memory beyond committed pages.
//!   Implements `__chkstk` (Windows), `__chkstk_ms` (Windows MSVC), and
//!   Linux-style guard page probing.
//! - **Dynamic stack allocation**: Lowering of `alloca` and
//!   `llvm.stacksave`/`llvm.stackrestore`/`DYNAMIC_STACKALLOC` intrinsics
//!   for variable-size stack frame objects.
//! - **Dynamic stack realignment**: Runtime alignment of the stack pointer
//!   to 32/64/128 bytes via `-mstackrealign`, using DRAP (Dynamic Realign
//!   Argument Pointer) register for frame pointer setup when the base
//!   pointer is unavailable.
//! - **Stack clash protection**: `-fstack-clash-protection` support with
//!   explicit probes at function entry for large static frames, and gap
//!   probing between dynamic allocations.
//! - **Stack frame layout**: Comprehensive modeling of fixed frame objects,
//!   variable frame objects, callee-saved spill area, return address slot,
//!   outgoing argument area, shadow space (Win64), and red zone (SysV AMD64).
//!
//! ## Motivation
//!
//! On modern operating systems, the stack is a grow-down region with guard
//! pages at the boundary. If a function allocates more stack space than the
//! guard region can cover in a single step (e.g., a large alloca), the
//! program may skip over the guard pages and crash with a segmentation fault
//! instead of expanding the stack. Stack probing mitigates this by
//! explicitly touching each page in the new allocation.
//!
//! ## Architecture
//!
//! ```text
//! ┌──────────────────────────────────────────────────────────────────────┐
//! │                        X86StackProbing                               │
//! │  ┌────────────────┐  ┌─────────────────┐  ┌──────────────────────┐  │
//! │  │ DynamicAlloca  │  │  StackProber    │  │  StackRealigner     │  │
//! │  │ alloca/VLA     │  │  chkstk/guard   │  │  mstackrealign      │  │
//! │  │ DYNAMIC_STACK  │  │  page probing   │  │  DRAP register      │  │
//! │  └────────────────┘  └─────────────────┘  └──────────────────────┘  │
//! │  ┌────────────────┐  ┌─────────────────┐                            │
//! │  │ StackClashProt │  │  FrameLayout    │                            │
//! │  │ entry/gap      │  │  fixed/variable │                            │
//! │  │ probes         │  │  spill/shadow   │                            │
//! │  └────────────────┘  └─────────────────┘                            │
//! └──────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Frame layout (System V AMD64 with dynamic alloca and probing)
//!
//! ```text
//!         +----------------------+  <- high address (previous frame)
//!         |   Return Address     |  (pushed by CALL)
//!   %rbp  +----------------------+
//!         |   Previous %rbp      |  (pushed by prologue)
//!   -8    +----------------------+
//!         |   Saved Registers    |  (RBX, R12-R15 as needed)
//!         +----------------------+
//!         |   Fixed Locals       |  (spill slots, small locals)
//!         +----------------------+
//!         |   Variable alloca    |  (dynamic size, aligned)
//!         |   (grows downward)   |
//!         +----------------------+
//!         |   Probe gap          |  (if stack-clash-protection)
//!         +----------------------+
//!         |   Outgoing Args      |  (for calls within this function)
//!         |   Shadow Space(Win64)|  (32 bytes on Windows x64)
//!   %rsp  +----------------------+  <- low address
//!         |   [Red Zone 128B]    |  (SysV AMD64 only, leaf functions)
//!         +----------------------+
//! ```
//!
//! Clean-room behavioral reconstruction from:
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//!   (volumes 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D)
//! - AMD64 Architecture Programmer's Manual (volumes 1-5)
//! - System V Application Binary Interface: AMD64 Architecture Processor Supplement
//! - Microsoft x64 Software Conventions
//! - Microsoft PE/COFF Specification (for __chkstk, __chkstk_ms)
//! - Linux kernel documentation: mm/mmap.c (guard page mechanism)
//! - GCC documentation: -fstack-clash-protection, -mstackrealign
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications, Intel/AMD manuals, ABI documents, and
//! black-box oracle interrogation of compiler output.
//!
//! ## References
//!
//! | Concept              | Source                                        |
//! |---------------------|-----------------------------------------------|
//! | `__chkstk`          | Microsoft PE/COFF Specification §5.2           |
//! | `__chkstk_ms`       | MSVC runtime library (chkstk.asm)              |
//! | Guard pages         | Linux kernel `mm/mmap.c`, `arch/x86/mm/fault.c`|
//! | Stack clash         | Qualys advisory (CVE-2017-1000364)             |
//! | `-mstackrealign`    | GCC manual §3.17.41 (i386 and x86-64 Options)  |
//! | Red zone            | SysV AMD64 ABI §3.2.2                          |
//! | Shadow space        | Microsoft x64 Software Conventions §4.1.1      |
//! | Probe interval      | GCC default: 4096 (one page)                    |
//!
//! # Safety
//!
//! This module contains low-level stack manipulation constructs. Functions
//! that emit probing loops or dynamic realignment code produce machine
//! instructions that directly modify the stack pointer. Callers must ensure
//! that the generated code is correct for the target ABI and that frame
//! setup/teardown is properly balanced.

#![allow(non_upper_case_globals, dead_code, non_snake_case)]

// ============================================================================
// Imports
// ============================================================================

use self::x86_opcodes::X86Opcode;
use crate::x86::x86_register_info::{EAX, R10, R11, RAX, RBP, RSP};
use std::fmt;
use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
use std::sync::{Arc, RwLock};

// ============================================================================
// Global Constants
// ============================================================================

/// Default probe interval size: one 4 KiB page.
/// This is the granularity at which stack guard pages are set up by the OS.
pub const DEFAULT_PROBE_INTERVAL: u64 = 4096;

/// Maximum probe interval: 16 pages (64 KiB).
/// Beyond this, guard page skipping becomes a realistic threat.
pub const MAX_PROBE_INTERVAL: u64 = 65536;

/// Minimum probe interval: 1 KiB.
/// Smaller than a page but can be used for aggressive protection.
pub const MIN_PROBE_INTERVAL: u64 = 1024;

/// Default stack alignment for System V AMD64: 16 bytes.
pub const STACK_ALIGNMENT_SYSV: u64 = 16;

/// Default stack alignment for Win64: 16 bytes.
pub const STACK_ALIGNMENT_WIN64: u64 = 16;

/// Maximum supported dynamic stack realignment: 128 bytes (for AVX-512 aligned spills).
pub const MAX_STACK_REALIGNMENT: u64 = 128;

/// Size of the System V AMD64 red zone (128 bytes below %rsp).
pub const RED_ZONE_SIZE_SYSV: u64 = 128;

/// Size of the Win64 shadow space (32 bytes above %rsp for home space of first 4 args).
pub const SHADOW_SPACE_WIN64: u64 = 32;

/// Default alignment for `alloca` / VLA allocations: 16 bytes.
pub const ALLOCA_DEFAULT_ALIGNMENT: u64 = 16;

/// Register used for DRAP (Dynamic Realign Argument Pointer).
/// On x86-64, typically R10 or R11 is used as a temporary.
pub const DRAP_REGISTER_X64: u16 = R10;

/// Alternative DRAP register on x86-64.
pub const DRAP_REGISTER_ALT_X64: u16 = R11;

/// DRAP register on IA-32 (typically EAX).
pub const DRAP_REGISTER_X32: u16 = EAX;

/// Maximum stack frame size without requiring a probe (if stack clash protection enabled).
/// Frames <= this size can skip the entry probe.
pub const MAX_FRAME_SIZE_WITHOUT_PROBE: u64 = 4096;

/// X86-64 register number for RBX.
const RBX_REG: u16 = 3;
/// X86-64 register number for R12.
const R12_REG: u16 = 12;
/// X86-64 register number for R13.
const R13_REG: u16 = 13;
/// X86-64 register number for R14.
const R14_REG: u16 = 14;
/// X86-64 register number for R15.
const R15_REG: u16 = 15;

/// X86-32 register number for EBX.
const EBX32_REG: u16 = 19;
/// X86-32 register number for ESI.
const ESI32_REG: u16 = 22;
/// X86-32 register number for EDI.
const EDI32_REG: u16 = 23;
/// X86-32 register number for EBP.
const EBP32_REG: u16 = 21;
/// X86-32 register number for ESP.
const ESP32_REG: u16 = 20;

/// Pseudo-register for flags/implicit uses.
const FLAGS_REG: u16 = 200;

// ============================================================================
// Enumerations
// ============================================================================

/// Operating system target for stack probing strategy selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TargetOS {
    /// Linux (any distribution).
    Linux,
    /// Windows (any version: 7, 8, 10, 11, Server).
    Windows,
    /// macOS / Darwin.
    MacOS,
    /// FreeBSD.
    FreeBSD,
    /// Generic Unix-like (Solaris, illumos, etc.).
    Unix,
    /// Unknown OS — probing disabled by default.
    Unknown,
}

impl TargetOS {
    /// Returns `true` if this is a Windows target.
    pub fn is_windows(self) -> bool {
        matches!(self, TargetOS::Windows)
    }

    /// Returns `true` if this is a Linux target (guard-page style probing).
    pub fn is_linux(self) -> bool {
        matches!(self, TargetOS::Linux)
    }

    /// Returns `true` if the red zone exists (SysV AMD64 only).
    pub fn has_red_zone(self) -> bool {
        matches!(
            self,
            TargetOS::Linux | TargetOS::MacOS | TargetOS::FreeBSD | TargetOS::Unix
        )
    }

    /// Returns `true` if Win64 shadow space is required.
    pub fn requires_shadow_space(self) -> bool {
        matches!(self, TargetOS::Windows)
    }
}

impl fmt::Display for TargetOS {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TargetOS::Linux => write!(f, "linux"),
            TargetOS::Windows => write!(f, "windows"),
            TargetOS::MacOS => write!(f, "macos"),
            TargetOS::FreeBSD => write!(f, "freebsd"),
            TargetOS::Unix => write!(f, "unix"),
            TargetOS::Unknown => write!(f, "unknown"),
        }
    }
}

/// Calling convention (simplified — mirrors x86_frame_lowering::CallConv).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CallingConv {
    /// System V AMD64 ABI (Linux, macOS, FreeBSD).
    SystemV,
    /// Microsoft x64 ABI (Windows).
    Win64,
    /// IA-32 cdecl (System V i386).
    Cdecl32,
    /// IA-32 stdcall (Windows 32-bit).
    Stdcall32,
    /// IA-32 fastcall.
    Fastcall32,
}

impl CallingConv {
    /// Returns `true` for 64-bit calling conventions.
    pub fn is_64bit(self) -> bool {
        matches!(self, CallingConv::SystemV | CallingConv::Win64)
    }

    /// Returns `true` for Windows-targeting conventions.
    pub fn is_windows(self) -> bool {
        matches!(self, CallingConv::Win64 | CallingConv::Stdcall32)
    }

    /// Returns `true` if shadow space is required for this convention.
    pub fn requires_shadow_space(self) -> bool {
        matches!(self, CallingConv::Win64)
    }

    /// Returns `true` if the calling convention allows a red zone.
    pub fn has_red_zone(self) -> bool {
        matches!(self, CallingConv::SystemV)
    }
}

impl Default for CallingConv {
    fn default() -> Self {
        CallingConv::SystemV
    }
}

/// Strategy used for stack probing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ProbeStrategy {
    /// No probing — skip touching pages before allocation.
    None,
    /// Inline probing: emit a loop that touches each page.
    /// Used on Linux and generic Unix targets.
    Inline,
    /// Call `__chkstk` runtime function (Windows).
    /// The function expects the allocation size in RAX/EAX.
    ChkStk,
    /// Call `__chkstk_ms` runtime function (MSVC variant).
    /// Expects size in RAX/EAX, preserves all volatile registers.
    ChkStkMs,
    /// Use explicit probe instructions at function entry for large static frames,
    /// combined with dynamic probing for alloca.
    ExplicitProbe,
}

impl ProbeStrategy {
    /// Whether this strategy emits a call to a runtime function.
    pub fn is_runtime_call(self) -> bool {
        matches!(self, ProbeStrategy::ChkStk | ProbeStrategy::ChkStkMs)
    }

    /// Whether this strategy emits inline probing code.
    pub fn is_inline(self) -> bool {
        matches!(self, ProbeStrategy::Inline | ProbeStrategy::ExplicitProbe)
    }

    /// The name of the runtime function, if any.
    pub fn runtime_symbol(self) -> Option<&'static str> {
        match self {
            ProbeStrategy::ChkStk => Some("__chkstk"),
            ProbeStrategy::ChkStkMs => Some("__chkstk_ms"),
            _ => None,
        }
    }
}

/// Direction of stack growth.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum StackDirection {
    /// Stack grows downward (lower addresses) — x86 standard.
    Downward,
    /// Stack grows upward (higher addresses) — not used on x86 but included for completeness.
    Upward,
}

/// Alignment requirement for dynamic stack realignment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum RealignAlignment {
    /// Align stack to 32 bytes.
    Align32,
    /// Align stack to 64 bytes (AVX).
    Align64,
    /// Align stack to 128 bytes (AVX-512).
    Align128,
    /// No realignment.
    None,
}

impl RealignAlignment {
    /// Returns the byte value of this alignment.
    pub fn byte_value(self) -> u64 {
        match self {
            RealignAlignment::Align32 => 32,
            RealignAlignment::Align64 => 64,
            RealignAlignment::Align128 => 128,
            RealignAlignment::None => 0,
        }
    }

    /// Parses a numeric alignment value into the enum.
    pub fn from_bytes(bytes: u64) -> Self {
        match bytes {
            0 => RealignAlignment::None,
            1..=32 => RealignAlignment::Align32,
            33..=64 => RealignAlignment::Align64,
            _ => RealignAlignment::Align128,
        }
    }
}

/// Type of frame object.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FrameObjectKind {
    /// Fixed-size frame object (spill slot, local variable).
    Fixed,
    /// Variable-size frame object (alloca, VLA).
    Variable,
    /// Callee-saved register spill.
    CalleeSavedReg,
    /// Return address slot.
    ReturnAddress,
    /// Outgoing argument area for calls.
    OutgoingArgs,
    /// Shadow space (Win64).
    ShadowSpace,
    /// Stack protector canary.
    StackProtector,
}

impl fmt::Display for FrameObjectKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FrameObjectKind::Fixed => write!(f, "fixed"),
            FrameObjectKind::Variable => write!(f, "variable"),
            FrameObjectKind::CalleeSavedReg => write!(f, "callee_saved"),
            FrameObjectKind::ReturnAddress => write!(f, "return_addr"),
            FrameObjectKind::OutgoingArgs => write!(f, "outgoing_args"),
            FrameObjectKind::ShadowSpace => write!(f, "shadow_space"),
            FrameObjectKind::StackProtector => write!(f, "stack_protector"),
        }
    }
}

/// Severity level for stack clash diagnostics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ClashSeverity {
    /// No clash risk detected.
    None,
    /// Low risk — frame is just above the probe threshold.
    Low,
    /// Medium risk — frame contains variable allocations without probing.
    Medium,
    /// High risk — large alloca without probing enabled.
    High,
    /// Critical — dynamic alloca > multiple pages without any probing.
    Critical,
}

// ============================================================================
// Core Data Structures
// ============================================================================

/// Represents a single frame object in the stack layout.
///
/// Frame objects are placed in the stack frame at fixed or variable offsets
/// from the frame pointer or stack pointer.
#[derive(Debug, Clone)]
pub struct FrameObject {
    /// Unique identifier for this frame object.
    pub id: u32,
    /// The kind of frame object (fixed, variable, callee-saved, etc.).
    pub kind: FrameObjectKind,
    /// Offset from the frame pointer (negative for locals, positive for args).
    pub fp_offset: i64,
    /// Offset from the stack pointer (at function entry).
    pub sp_offset: i64,
    /// Size in bytes.
    pub size: u64,
    /// Required alignment.
    pub alignment: u64,
    /// Whether this object is referenced by a debug info variable.
    pub has_debug_info: bool,
    /// For variable objects: the VirtReg holding the size.
    pub size_reg: Option<VirtReg>,
    /// For callee-saved regs: the physical register number.
    pub phys_reg: Option<u16>,
    /// Whether the object is spillable.
    pub is_spill: bool,
}

impl FrameObject {
    /// Creates a new fixed-size frame object.
    pub fn new_fixed(id: u32, size: u64, alignment: u64, fp_offset: i64, sp_offset: i64) -> Self {
        FrameObject {
            id,
            kind: FrameObjectKind::Fixed,
            fp_offset,
            sp_offset,
            size,
            alignment,
            has_debug_info: false,
            size_reg: None,
            phys_reg: None,
            is_spill: false,
        }
    }

    /// Creates a new variable-size frame object (alloca).
    pub fn new_variable(
        id: u32,
        size: u64,
        alignment: u64,
        fp_offset: i64,
        sp_offset: i64,
        size_reg: VirtReg,
    ) -> Self {
        FrameObject {
            id,
            kind: FrameObjectKind::Variable,
            fp_offset,
            sp_offset,
            size,
            alignment,
            has_debug_info: false,
            size_reg: Some(size_reg),
            phys_reg: None,
            is_spill: false,
        }
    }

    /// Creates a callee-saved register spill slot.
    pub fn new_callee_saved(
        id: u32,
        phys_reg: u16,
        size: u64,
        fp_offset: i64,
        sp_offset: i64,
    ) -> Self {
        FrameObject {
            id,
            kind: FrameObjectKind::CalleeSavedReg,
            fp_offset,
            sp_offset,
            size,
            alignment: size, // GPR spills are naturally aligned
            has_debug_info: false,
            size_reg: None,
            phys_reg: Some(phys_reg),
            is_spill: true,
        }
    }

    /// Creates a return address slot.
    pub fn new_return_address(fp_offset: i64) -> Self {
        FrameObject {
            id: 0,
            kind: FrameObjectKind::ReturnAddress,
            fp_offset,
            sp_offset: fp_offset,
            size: 8, // Return address is 8 bytes on x86-64, 4 on x86-32
            alignment: 8,
            has_debug_info: false,
            size_reg: None,
            phys_reg: None,
            is_spill: false,
        }
    }

    /// Creates a shadow space entry (Win64).
    pub fn new_shadow_space(fp_offset: i64) -> Self {
        FrameObject {
            id: u32::MAX, // Sentinel ID for shadow space
            kind: FrameObjectKind::ShadowSpace,
            fp_offset,
            sp_offset: fp_offset + SHADOW_SPACE_WIN64 as i64 - 8,
            size: SHADOW_SPACE_WIN64,
            alignment: 8,
            has_debug_info: false,
            size_reg: None,
            phys_reg: None,
            is_spill: false,
        }
    }
}

/// Represents the complete layout of a function's stack frame.
///
/// This structure tracks all frame objects, their offsets, the total frame
/// size, and probing requirements.
#[derive(Debug, Clone)]
pub struct StackFrameLayout {
    /// The calling convention used.
    pub calling_conv: CallingConv,
    /// Whether a frame pointer (%rbp / %ebp) is used.
    pub has_frame_pointer: bool,
    /// Whether dynamic stack realignment is enabled.
    pub has_dynamic_realignment: bool,
    /// Required stack alignment for this function.
    pub stack_alignment: u64,
    /// Dynamic realignment amount (0 if no realignment).
    pub realign_amount: u64,
    /// Total fixed frame size (callee-saved regs + locals + spill slots).
    pub fixed_frame_size: u64,
    /// Total outgoing argument area size.
    pub outgoing_arg_size: u64,
    /// Size of the shadow space (Win64 only, 0 otherwise).
    pub shadow_space_size: u64,
    /// Maximum call frame size for any call in this function.
    pub max_call_frame_size: u64,
    /// Whether this function has variable-size allocas.
    pub has_variable_allocas: bool,
    /// Whether the red zone can be used (leaf function, SysV AMD64).
    pub can_use_red_zone: bool,
    /// All fixed frame objects, in offset order.
    pub fixed_objects: Vec<FrameObject>,
    /// All variable frame objects (allocas).
    pub variable_objects: Vec<FrameObject>,
    /// Callee-saved register spill slots.
    pub callee_saved_spills: Vec<FrameObject>,
    /// Stack protector canary location, if present.
    pub stack_protector_offset: Option<i64>,
    /// Address of the return address slot relative to frame pointer.
    pub return_address_offset: i64,
    /// Total frame size (including all fixed + variable + argument area).
    pub total_frame_size: u64,
    /// Whether probing is required for the static part of this frame.
    pub requires_static_probe: bool,
    /// Whether probing is required for dynamic allocations.
    pub requires_dynamic_probe: bool,
    /// The probe interval (page size).
    pub probe_interval: u64,
    /// DRAP register (if dynamic realignment is used).
    pub drap_register: Option<u16>,
}

impl StackFrameLayout {
    /// Creates an empty frame layout with defaults for a given calling convention.
    pub fn new(cc: CallingConv) -> Self {
        let (shadow, red_zone) = match cc {
            CallingConv::Win64 => (SHADOW_SPACE_WIN64, false),
            CallingConv::SystemV => (0, true),
            _ => (0, true),
        };
        StackFrameLayout {
            calling_conv: cc,
            has_frame_pointer: false,
            has_dynamic_realignment: false,
            stack_alignment: if cc.is_64bit() {
                STACK_ALIGNMENT_SYSV
            } else {
                16
            },
            realign_amount: 0,
            fixed_frame_size: 0,
            outgoing_arg_size: 0,
            shadow_space_size: shadow,
            max_call_frame_size: 0,
            has_variable_allocas: false,
            can_use_red_zone: red_zone,
            fixed_objects: Vec::new(),
            variable_objects: Vec::new(),
            callee_saved_spills: Vec::new(),
            stack_protector_offset: None,
            return_address_offset: 8, // default: above saved %rbp
            total_frame_size: 0,
            requires_static_probe: false,
            requires_dynamic_probe: false,
            probe_interval: DEFAULT_PROBE_INTERVAL,
            drap_register: None,
        }
    }

    /// Computes the aligned offset from the given raw offset.
    pub fn align_offset(offset: u64, alignment: u64) -> u64 {
        (offset + alignment - 1) & !(alignment - 1)
    }

    /// Returns the total size of the callee-saved register spill area.
    pub fn callee_saved_size(&self) -> u64 {
        self.callee_saved_spills.iter().map(|o| o.size).sum()
    }

    /// Returns `true` if probing is required at all.
    pub fn requires_probing(&self) -> bool {
        self.requires_static_probe || self.requires_dynamic_probe
    }
}

// ============================================================================
// X86StackProbing — Top-Level Struct
// ============================================================================

/// The central struct for X86 stack probing and dynamic stack realignment.
///
/// `X86StackProbing` manages the configuration and state for stack probing,
/// dynamic `alloca` lowering, stack clash protection, and dynamic stack
/// realignment on X86/X86-64 targets.
///
/// # Examples
///
/// ```ignore
/// let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
/// prober.set_probe_strategy(ProbeStrategy::Inline);
/// prober.set_stack_clash_protection(true);
/// prober.set_probe_interval(4096);
/// prober.enable_dynamic_realignment(RealignAlignment::Align64);
///
/// let layout = prober.compute_frame_layout(&frame_info);
/// prober.emit_prologue_probe(&mut mbb, &layout);
/// ```
#[derive(Debug)]
pub struct X86StackProbing {
    /// Target operating system.
    pub target_os: TargetOS,
    /// Calling convention.
    pub calling_conv: CallingConv,
    /// Current probe strategy.
    pub probe_strategy: ProbeStrategy,
    /// Whether stack clash protection is enabled (-fstack-clash-protection).
    pub stack_clash_protection: bool,
    /// The probe interval in bytes (page size for touch-each-page probing).
    pub probe_interval: u64,
    /// Whether to emit explicit probes for the static frame.
    pub probe_static_frame: bool,
    /// Whether to emit probes for dynamic allocations.
    pub probe_dynamic_alloca: bool,
    /// Dynamic stack realignment configuration.
    pub realign_alignment: RealignAlignment,
    /// Whether dynamic realignment is enabled by user flag.
    pub realign_enabled: bool,
    /// Whether the DRAP register is available.
    pub drap_available: bool,
    /// The DRAP register to use (if realignment is enabled).
    pub drap_register: u16,
    /// Whether the function uses a frame pointer.
    pub uses_frame_pointer: bool,
    /// Whether the function is a leaf (makes no calls) — affects red zone usage.
    pub is_leaf_function: bool,
    /// Whether to emit the red zone (SysV AMD64 only, for leaf functions).
    pub emit_red_zone: bool,
    /// Counter for generated frame object IDs.
    next_frame_object_id: AtomicU32,
    /// Counter for the number of probes emitted.
    probe_count: AtomicU64,
    /// Internal statistics.
    stats: Arc<RwLock<ProbeStats>>,
}

/// Statistics tracked during stack probing and frame layout.
#[derive(Debug, Clone, Default)]
pub struct ProbeStats {
    /// Number of static frame probes emitted.
    pub static_probes: u64,
    /// Number of dynamic alloca probes emitted.
    pub dynamic_probes: u64,
    /// Number of probe loops generated.
    pub probe_loops: u64,
    /// Number of functions with dynamic realignment.
    pub realigned_functions: u64,
    /// Number of functions with stack clash protection active.
    pub clash_protected_functions: u64,
    /// Number of alloca sites lowered.
    pub alloca_sites: u64,
    /// Total bytes probed (static + dynamic).
    pub total_bytes_probed: u64,
    /// Number of __chkstk calls emitted.
    pub chkstk_calls: u64,
    /// Number of gap probes between allocas.
    pub gap_probes: u64,
}

impl ProbeStats {
    /// Creates a new empty stats tracker.
    pub fn new() -> Self {
        ProbeStats::default()
    }

    /// Merges another stats into this one (accumulate).
    pub fn merge(&mut self, other: &ProbeStats) {
        self.static_probes += other.static_probes;
        self.dynamic_probes += other.dynamic_probes;
        self.probe_loops += other.probe_loops;
        self.realigned_functions += other.realigned_functions;
        self.clash_protected_functions += other.clash_protected_functions;
        self.alloca_sites += other.alloca_sites;
        self.total_bytes_probed += other.total_bytes_probed;
        self.chkstk_calls += other.chkstk_calls;
        self.gap_probes += other.gap_probes;
    }

    /// Resets all counters to zero.
    pub fn reset(&mut self) {
        *self = ProbeStats::default();
    }
}

impl fmt::Display for ProbeStats {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "Stack Probing Statistics:")?;
        writeln!(f, "  Static probes:          {}", self.static_probes)?;
        writeln!(f, "  Dynamic probes:         {}", self.dynamic_probes)?;
        writeln!(f, "  Probe loops:            {}", self.probe_loops)?;
        writeln!(f, "  Realigned functions:    {}", self.realigned_functions)?;
        writeln!(
            f,
            "  Clash-protected funcs:  {}",
            self.clash_protected_functions
        )?;
        writeln!(f, "  Alloca sites:           {}", self.alloca_sites)?;
        writeln!(f, "  Total bytes probed:     {}", self.total_bytes_probed)?;
        writeln!(f, "  __chkstk calls:         {}", self.chkstk_calls)?;
        write!(f, "  Gap probes:             {}", self.gap_probes)
    }
}

impl Clone for X86StackProbing {
    fn clone(&self) -> Self {
        X86StackProbing {
            target_os: self.target_os,
            calling_conv: self.calling_conv,
            probe_strategy: self.probe_strategy,
            stack_clash_protection: self.stack_clash_protection,
            probe_interval: self.probe_interval,
            probe_static_frame: self.probe_static_frame,
            probe_dynamic_alloca: self.probe_dynamic_alloca,
            realign_alignment: self.realign_alignment,
            realign_enabled: self.realign_enabled,
            drap_available: self.drap_available,
            drap_register: self.drap_register,
            uses_frame_pointer: self.uses_frame_pointer,
            is_leaf_function: self.is_leaf_function,
            emit_red_zone: self.emit_red_zone,
            next_frame_object_id: AtomicU32::new(self.next_frame_object_id.load(Ordering::Relaxed)),
            probe_count: AtomicU64::new(self.probe_count.load(Ordering::Relaxed)),
            stats: Arc::clone(&self.stats),
        }
    }
}

impl X86StackProbing {
    /// Creates a new `X86StackProbing` with sensible defaults for the given
    /// target OS and calling convention.
    ///
    /// # Arguments
    ///
    /// * `target_os` — the operating system (determines probe strategy default).
    /// * `cc` — the calling convention.
    pub fn new(target_os: TargetOS, cc: CallingConv) -> Self {
        let default_strategy = Self::default_strategy_for(target_os);
        X86StackProbing {
            target_os,
            calling_conv: cc,
            probe_strategy: default_strategy,
            stack_clash_protection: false,
            probe_interval: DEFAULT_PROBE_INTERVAL,
            probe_static_frame: true,
            probe_dynamic_alloca: true,
            realign_alignment: RealignAlignment::None,
            realign_enabled: false,
            drap_available: cc.is_64bit(),
            drap_register: if cc.is_64bit() {
                DRAP_REGISTER_X64
            } else {
                DRAP_REGISTER_X32
            },
            uses_frame_pointer: false,
            is_leaf_function: false,
            emit_red_zone: cc == CallingConv::SystemV,
            next_frame_object_id: AtomicU32::new(0),
            probe_count: AtomicU64::new(0),
            stats: Arc::new(RwLock::new(ProbeStats::new())),
        }
    }

    /// Returns the default probe strategy for a given target OS.
    fn default_strategy_for(os: TargetOS) -> ProbeStrategy {
        match os {
            TargetOS::Windows => ProbeStrategy::ChkStk,
            TargetOS::Linux | TargetOS::FreeBSD | TargetOS::Unix => ProbeStrategy::Inline,
            TargetOS::MacOS => ProbeStrategy::Inline,
            TargetOS::Unknown => ProbeStrategy::None,
        }
    }

    // --- Configuration Methods ---

    /// Sets the probe strategy.
    pub fn set_probe_strategy(&mut self, strategy: ProbeStrategy) -> &mut Self {
        self.probe_strategy = strategy;
        self
    }

    /// Enables or disables stack clash protection (`-fstack-clash-protection`).
    pub fn set_stack_clash_protection(&mut self, enable: bool) -> &mut Self {
        self.stack_clash_protection = enable;
        self
    }

    /// Sets the probe interval in bytes. Clamped to [MIN_PROBE_INTERVAL..MAX_PROBE_INTERVAL].
    pub fn set_probe_interval(&mut self, interval: u64) -> &mut Self {
        self.probe_interval = interval.clamp(MIN_PROBE_INTERVAL, MAX_PROBE_INTERVAL);
        self
    }

    /// Enables or disables static frame probing.
    pub fn set_probe_static_frame(&mut self, probe: bool) -> &mut Self {
        self.probe_static_frame = probe;
        self
    }

    /// Enables or disables dynamic alloca probing.
    pub fn set_probe_dynamic_alloca(&mut self, probe: bool) -> &mut Self {
        self.probe_dynamic_alloca = probe;
        self
    }

    /// Enables dynamic stack realignment with the given alignment.
    ///
    /// This corresponds to the `-mstackrealign` GCC/Clang flag.
    pub fn enable_dynamic_realignment(&mut self, alignment: RealignAlignment) -> &mut Self {
        self.realign_enabled = true;
        self.realign_alignment = alignment;
        self
    }

    /// Disables dynamic stack realignment.
    pub fn disable_dynamic_realignment(&mut self) -> &mut Self {
        self.realign_enabled = false;
        self.realign_alignment = RealignAlignment::None;
        self
    }

    /// Sets whether the DRAP register is available for realignment.
    pub fn set_drap_available(&mut self, available: bool) -> &mut Self {
        self.drap_available = available;
        self
    }

    /// Sets the DRAP register number.
    pub fn set_drap_register(&mut self, reg: u16) -> &mut Self {
        self.drap_register = reg;
        self
    }

    /// Sets whether the function uses a frame pointer.
    pub fn set_uses_frame_pointer(&mut self, uses_fp: bool) -> &mut Self {
        self.uses_frame_pointer = uses_fp;
        self
    }

    /// Sets whether this is a leaf function (makes no calls).
    pub fn set_is_leaf_function(&mut self, leaf: bool) -> &mut Self {
        self.is_leaf_function = leaf;
        self
    }

    /// Sets whether the red zone can be emitted.
    pub fn set_emit_red_zone(&mut self, emit: bool) -> &mut Self {
        self.emit_red_zone = emit;
        self
    }

    // --- Frame Object ID Management ---

    /// Allocates a new unique frame object ID.
    pub fn next_frame_object_id(&self) -> u32 {
        self.next_frame_object_id.fetch_add(1, Ordering::Relaxed)
    }

    /// Resets the frame object ID counter.
    pub fn reset_frame_object_ids(&self) {
        self.next_frame_object_id.store(0, Ordering::Relaxed);
    }

    // --- Probing Decision Logic ---

    /// Determines whether probing is required for a static frame of the given size.
    ///
    /// Under stack clash protection, any frame larger than
    /// `MAX_FRAME_SIZE_WITHOUT_PROBE` requires an entry probe. Without stack
    /// clash protection, probing may still be required on Windows for any
    /// allocation larger than one page.
    pub fn requires_static_probe(&self, frame_size: u64) -> bool {
        if !self.probe_static_frame {
            return false;
        }
        if self.probe_strategy == ProbeStrategy::None {
            return false;
        }
        if self.stack_clash_protection {
            return frame_size > MAX_FRAME_SIZE_WITHOUT_PROBE;
        }
        // On Windows, any frame larger than one page (4096) is probed
        if self.target_os.is_windows() {
            return frame_size > DEFAULT_PROBE_INTERVAL;
        }
        // On Linux, only probe if dynamic allocas are present (guard pages handle static)
        false
    }

    /// Determines whether probing is required for a dynamic alloca of `size` bytes.
    pub fn requires_dynamic_probe(&self, size: u64) -> bool {
        if !self.probe_dynamic_alloca {
            return false;
        }
        if self.probe_strategy == ProbeStrategy::None {
            return false;
        }
        // Always probe dynamic allocas if they exceed one probe interval
        size > self.probe_interval
    }

    /// Computes the number of probes needed for a given allocation size.
    pub fn probe_count_for_size(&self, size: u64) -> u64 {
        if size == 0 {
            return 0;
        }
        // Number of pages (intervals) to touch
        (size + self.probe_interval - 1) / self.probe_interval
    }

    // --- Stack Clash Severity Assessment ---

    /// Assesses the stack clash severity for a frame layout.
    pub fn assess_clash_severity(&self, layout: &StackFrameLayout) -> ClashSeverity {
        if !self.stack_clash_protection {
            return ClashSeverity::None;
        }
        if !layout.has_variable_allocas && layout.total_frame_size <= MAX_FRAME_SIZE_WITHOUT_PROBE {
            return ClashSeverity::None;
        }
        if layout.total_frame_size <= MAX_FRAME_SIZE_WITHOUT_PROBE * 2 {
            return ClashSeverity::Low;
        }
        if layout.has_variable_allocas && !self.probe_dynamic_alloca {
            return ClashSeverity::High;
        }
        if layout.total_frame_size > 65536 {
            return ClashSeverity::Critical;
        }
        ClashSeverity::Medium
    }

    // --- Statistics Access ---

    /// Returns a clone of the current probe statistics.
    pub fn get_stats(&self) -> ProbeStats {
        self.stats.read().unwrap().clone()
    }

    /// Increments a specific counter in the stats.
    fn inc_stat<F>(&self, update: F)
    where
        F: FnOnce(&mut ProbeStats),
    {
        if let Ok(mut stats) = self.stats.write() {
            update(&mut stats);
        }
    }
}

// ============================================================================
// Dynamic Stack Allocation — alloca / DYNAMIC_STACKALLOC lowering
// ============================================================================

/// Configuration for lowering an `alloca` instruction.
#[derive(Debug, Clone)]
pub struct AllocaConfig {
    /// The virtual register holding the allocation size.
    pub size_reg: VirtReg,
    /// The virtual register that will receive the result pointer.
    pub result_reg: VirtReg,
    /// Required alignment for the allocation.
    pub alignment: u64,
    /// Whether this alloca is in the entry block (can be merged into prologue).
    pub in_entry_block: bool,
    /// Whether to probe the allocation.
    pub probe: bool,
    /// Whether to emit `llvm.stacksave` before and `llvm.stackrestore` after.
    pub use_save_restore: bool,
}

/// The result of lowering a dynamic stack allocation.
#[derive(Debug, Clone)]
pub struct AllocaResult {
    /// Sequence of machine instructions implementing the alloca.
    pub instructions: Vec<MachineInstr>,
    /// The frame object created for this allocation.
    pub frame_object: FrameObject,
    /// The stack pointer value after adjustment (before allocation).
    pub old_sp_reg: VirtReg,
    /// The stack pointer value after adjustment (after allocation).
    pub new_sp_reg: VirtReg,
    /// Whether probing was emitted.
    pub probed: bool,
    /// Number of probe instructions emitted.
    pub probe_count: u64,
}

/// Context for `DYNAMIC_STACKALLOC` intrinsic lowering.
#[derive(Debug, Clone)]
pub struct DynamicStackAllocContext {
    /// The virtual register holding the size to allocate.
    pub size_reg: VirtReg,
    /// Required alignment.
    pub alignment: u64,
    /// Whether this is for a function argument (copy to argument area).
    pub is_arg_copy: bool,
    /// Whether probing is required.
    pub probe: bool,
}

/// Result of lowering `DYNAMIC_STACKALLOC`.
#[derive(Debug, Clone)]
pub struct DynamicStackAllocResult {
    /// The generated machine instructions.
    pub instructions: Vec<MachineInstr>,
    /// The register holding the pointer to the allocated space.
    pub result_reg: VirtReg,
    /// The old stack pointer value.
    pub old_sp: VirtReg,
    /// The new stack pointer value.
    pub new_sp: VirtReg,
    /// Whether a probe was emitted.
    pub probed: bool,
}

impl X86StackProbing {
    /// Lowers an `alloca` instruction into a sequence of machine instructions.
    ///
    /// On x86-64, an alloca:
    /// 1. Rounds the requested size up to the required alignment
    /// 2. Subtracts from %rsp (or %esp on 32-bit)
    /// 3. Optionally probes each page of the new allocation
    /// 4. Stores the old %rsp for `llvm.stackrestore`
    /// 5. Returns the new %rsp value as the allocation pointer
    ///
    /// # Arguments
    ///
    /// * `config` — alloca lowering configuration.
    ///
    /// # Returns
    ///
    /// An `AllocaResult` with the generated instructions and frame object.
    pub fn lower_alloca(&self, config: &AllocaConfig) -> AllocaResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        self.inc_stat(|s| s.alloca_sites += 1);

        // Step 1: Round size up to alignment
        //   size_reg = (size_reg + alignment - 1) & ~(alignment - 1)
        if config.alignment > 1 {
            let align_mask = !(config.alignment as i64 - 1);
            // ADD size_reg, alignment-1
            instrs.push(MachineInstr::new_alu_imm(
                X86Opcode::ADD64ri8 as u16,
                config.size_reg,
                config.size_reg,
                (config.alignment - 1) as i64,
            ));
            // AND size_reg, align_mask
            instrs.push(MachineInstr::new_alu_imm(
                X86Opcode::AND64ri8 as u16,
                config.size_reg,
                config.size_reg,
                align_mask,
            ));
        }

        // Step 2: Save current SP for stackrestore (if needed)
        let old_sp = VirtReg::new();
        if config.use_save_restore {
            instrs.push(MachineInstr::new_copy(old_sp, VirtReg::phys(sp_reg)));
        }

        // Step 3: Probe if needed (before actually moving SP)
        let mut probed = false;
        let mut probe_count = 0u64;
        if config.probe && self.probe_dynamic_alloca {
            let probe_result = self.emit_dynamic_probe(config.size_reg, config.alignment);
            instrs.extend(probe_result.instructions);
            probed = probe_result.probes_emitted > 0;
            probe_count = probe_result.probes_emitted;
        }

        // Step 4: Adjust stack pointer
        //   SUB RSP, size_reg
        instrs.push(MachineInstr::new_alu_reg(
            if is_64bit {
                X86Opcode::SUB64rr as u16
            } else {
                X86Opcode::SUB32rr as u16
            },
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            config.size_reg,
        ));

        // Step 5: The result of alloca is the new SP value
        let new_sp = VirtReg::new();
        instrs.push(MachineInstr::new_copy(new_sp, VirtReg::phys(sp_reg)));
        instrs.push(MachineInstr::new_copy(config.result_reg, new_sp));

        // Step 6: Align SP after allocation (if dynamic realignment is enabled)
        if self.realign_enabled && self.realign_alignment != RealignAlignment::None {
            let align_bytes = self.realign_alignment.byte_value();
            // AND RSP, ~(align_bytes - 1)
            let mask = !(align_bytes as i64 - 1);
            instrs.push(MachineInstr::new_alu_imm(
                X86Opcode::AND64ri8 as u16,
                VirtReg::phys(sp_reg),
                VirtReg::phys(sp_reg),
                mask,
            ));
        }

        // Create frame object
        let fo = FrameObject::new_variable(
            self.next_frame_object_id(),
            0, // dynamic size — not known at compile time
            config.alignment.max(self.stack_alignment()),
            -(self.num_fixed_objects() as i64 + 1) * 8, // approximate offset
            0,
            config.size_reg,
        );

        self.inc_stat(|s| s.total_bytes_probed += probe_count * self.probe_interval);

        AllocaResult {
            instructions: instrs,
            frame_object: fo,
            old_sp_reg: old_sp,
            new_sp_reg: new_sp,
            probed,
            probe_count,
        }
    }

    /// Lowers a `DYNAMIC_STACKALLOC` intrinsic.
    ///
    /// The DYNAMIC_STACKALLOC intrinsic is similar to alloca but is used by the
    /// code generator for allocating space to copy arguments onto the stack.
    ///
    /// # Arguments
    ///
    /// * `ctx` — the dynamic stack allocation context.
    ///
    /// # Returns
    ///
    /// A `DynamicStackAllocResult` with the generated instructions.
    pub fn lower_dynamic_stack_alloc(
        &self,
        ctx: &DynamicStackAllocContext,
    ) -> DynamicStackAllocResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        // Align size
        let align = ctx.alignment.max(self.stack_alignment());
        let aligned_size_reg = VirtReg::new();

        if align > 1 {
            let mask = !(align as i64 - 1);
            // MOV tmp, size_reg
            instrs.push(MachineInstr::new_copy(aligned_size_reg, ctx.size_reg));
            // ADD tmp, align-1
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::ADD64ri8 as u16
                } else {
                    X86Opcode::ADD32ri8 as u16
                },
                aligned_size_reg,
                aligned_size_reg,
                (align - 1) as i64,
            ));
            // AND tmp, mask
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::AND64ri8 as u16
                } else {
                    X86Opcode::AND32ri8 as u16
                },
                aligned_size_reg,
                aligned_size_reg,
                mask,
            ));
        } else {
            instrs.push(MachineInstr::new_copy(aligned_size_reg, ctx.size_reg));
        }

        // Save old SP
        let old_sp = VirtReg::new();
        instrs.push(MachineInstr::new_copy(old_sp, VirtReg::phys(sp_reg)));

        // Probe if needed
        let mut probed = false;
        if ctx.probe && self.probe_dynamic_alloca {
            let probe_result = self.emit_dynamic_probe(aligned_size_reg, align);
            probed = probe_result.probes_emitted > 0;
            instrs.extend(probe_result.instructions);
        }

        // SUB SP, aligned_size_reg
        instrs.push(MachineInstr::new_alu_reg(
            if is_64bit {
                X86Opcode::SUB64rr as u16
            } else {
                X86Opcode::SUB32rr as u16
            },
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            aligned_size_reg,
        ));

        // Result is the new SP
        let new_sp = VirtReg::new();
        instrs.push(MachineInstr::new_copy(new_sp, VirtReg::phys(sp_reg)));

        DynamicStackAllocResult {
            instructions: instrs,
            result_reg: new_sp,
            old_sp,
            new_sp,
            probed,
        }
    }

    /// Returns the current stack alignment for this configuration.
    fn stack_alignment(&self) -> u64 {
        if self.realign_enabled {
            self.realign_alignment
                .byte_value()
                .max(STACK_ALIGNMENT_SYSV)
        } else {
            STACK_ALIGNMENT_SYSV
        }
    }

    /// Returns the approximate number of fixed objects tracked (for offset calculation).
    fn num_fixed_objects(&self) -> u32 {
        // Simplified — in practice would be tracked in frame layout
        0
    }
}

// ============================================================================
// Stack Probing — __chkstk, __chkstk_ms, Linux guard page probing
// ============================================================================

/// The result of emitting a probe sequence.
#[derive(Debug, Clone)]
pub struct ProbeEmissionResult {
    /// The emitted machine instructions.
    pub instructions: Vec<MachineInstr>,
    /// Number of probes actually emitted.
    pub probes_emitted: u64,
    /// Whether a runtime call was emitted (vs. inline).
    pub is_runtime_call: bool,
    /// The number of bytes covered by this probe sequence.
    pub bytes_probed: u64,
}

/// Represents a single probe point (one page touch).
#[derive(Debug, Clone, Copy)]
pub struct ProbePoint {
    /// The address probed (relative to current stack pointer).
    pub address_offset: i64,
    /// The page index being probed (0 = first page below current SP).
    pub page_index: u64,
}

impl X86StackProbing {
    /// Emits a probing sequence for a static frame of `frame_size` bytes.
    ///
    /// The behavior depends on the selected `ProbeStrategy`:
    ///
    /// - `ProbeStrategy::Inline` / `ExplicitProbe`:
    ///   Emits a loop that touches each page from `%rsp - probe_interval`
    ///   down to `%rsp - frame_size`.
    ///
    /// - `ProbeStrategy::ChkStk`:
    ///   Moves `frame_size` into `RAX`/`EAX` and calls `__chkstk`.
    ///
    /// - `ProbeStrategy::ChkStkMs`:
    ///   Moves `frame_size` into `RAX`/`EAX` and calls `__chkstk_ms`.
    ///
    /// # Arguments
    ///
    /// * `frame_size` — the total size of the static frame to probe.
    ///
    /// # Returns
    ///
    /// A `ProbeEmissionResult` with the generated instructions.
    pub fn emit_static_probe(&self, frame_size: u64) -> ProbeEmissionResult {
        if frame_size == 0 || self.probe_strategy == ProbeStrategy::None {
            return ProbeEmissionResult {
                instructions: Vec::new(),
                probes_emitted: 0,
                is_runtime_call: false,
                bytes_probed: 0,
            };
        }

        self.inc_stat(|s| s.static_probes += 1);

        match self.probe_strategy {
            ProbeStrategy::Inline | ProbeStrategy::ExplicitProbe => {
                self.emit_inline_probe(frame_size)
            }
            ProbeStrategy::ChkStk => self.emit_chkstk_call(frame_size, false),
            ProbeStrategy::ChkStkMs => self.emit_chkstk_call(frame_size, true),
            ProbeStrategy::None => unreachable!(),
        }
    }

    /// Emits a probing sequence for a dynamic allocation of `size_reg` bytes.
    ///
    /// For dynamic allocations, the probe strategy typically uses an inline
    /// loop (even on Windows, where __chkstk handles the probing internally).
    ///
    /// # Arguments
    ///
    /// * `size_reg` — the virtual register containing the allocation size.
    /// * `alignment` — the required alignment of the allocation.
    ///
    /// # Returns
    ///
    /// A `ProbeEmissionResult` with the generated instructions.
    pub fn emit_dynamic_probe(&self, size_reg: VirtReg, _alignment: u64) -> ProbeEmissionResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        if self.probe_strategy == ProbeStrategy::None {
            return ProbeEmissionResult {
                instructions: instrs,
                probes_emitted: 0,
                is_runtime_call: false,
                bytes_probed: 0,
            };
        }

        self.inc_stat(|s| {
            s.dynamic_probes += 1;
            s.probe_loops += 1;
        });

        if self.probe_strategy.is_runtime_call() {
            // For runtime calls, set up RAX/EAX with the size and call chkstk
            let rax = if is_64bit { RAX } else { EAX };
            instrs.push(MachineInstr::new_copy(VirtReg::phys(rax), size_reg));
            let is_ms = matches!(self.probe_strategy, ProbeStrategy::ChkStkMs);
            instrs.extend(self.emit_chkstk_call(0, is_ms).instructions);
            // Note: chkstk itself does the SUB RSP — we skip our own SUB

            return ProbeEmissionResult {
                instructions: instrs,
                probes_emitted: 1,
                is_runtime_call: true,
                bytes_probed: 0, // runtime handles it
            };
        }

        // Inline probing loop for dynamic allocation
        //
        // Algorithm (x86-64):
        //   ; Input: size_reg = number of bytes to allocate
        //   ; Clobbers: temp reg (RAX), flags
        //   align size to probe_interval
        //   neg size_reg         ; size_reg = -aligned_size (for indexing up)
        //   probe_loop:
        //     lea rsp, [rsp + size_reg]  ; temporarily adjust SP (size_reg is negative)
        //     test [rsp], rsp            ; touch the page
        //     add size_reg, probe_interval
        //     jnz probe_loop
        //   ; SP is now at its final position

        let probe_interval_imm = self.probe_interval as i64;
        let temp_reg = VirtReg::new();

        // Round size up to probe_interval
        if self.probe_interval > 1 {
            let round_mask = !(self.probe_interval as i64 - 1);
            // MOV temp, size_reg
            instrs.push(MachineInstr::new_copy(temp_reg, size_reg));
            // ADD temp, probe_interval-1
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::ADD64ri32 as u16
                } else {
                    X86Opcode::ADD32ri as u16
                },
                temp_reg,
                temp_reg,
                probe_interval_imm - 1,
            ));
            // AND temp, round_mask
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::AND64ri32 as u16
                } else {
                    X86Opcode::AND32ri as u16
                },
                temp_reg,
                temp_reg,
                round_mask,
            ));
        } else {
            instrs.push(MachineInstr::new_copy(temp_reg, size_reg));
        }

        // NEG temp (make it negative so we can index upward)
        instrs.push(MachineInstr::new_unary(
            X86Opcode::NEG64r as u16,
            temp_reg,
            temp_reg,
        ));

        // Probe loop: touch each page
        // Each iteration:
        //   LEA RSP, [RSP + temp]   — temporarily move SP down by temp (negative)
        //   TEST [RSP], RSP          — touch page (read to force page fault / guard hit)
        //   ADD temp, probe_interval — advance toward zero
        //   JNZ probe_loop           — loop until temp == 0

        // We need to represent a basic block for the loop. In a real lowering,
        // this would create new MBBs. Here we represent instructions inline.
        let _loop_label = format!(
            ".Lprobe_loop_{}",
            self.probe_count.fetch_add(1, Ordering::Relaxed)
        );

        // LEA RSP, [RSP + temp]
        instrs.push(MachineInstr::new_lea(
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            temp_reg,
            1,
            0,
        ));

        // TEST [RSP], RSP — touch the page (write 0 to [RSP] to force page-in)
        instrs.push(MachineInstr::new_mem_test(
            VirtReg::phys(sp_reg),
            0,
            if is_64bit { 8 } else { 4 },
        ));

        // ADD temp, probe_interval
        instrs.push(MachineInstr::new_alu_imm(
            if is_64bit {
                X86Opcode::ADD64ri32 as u16
            } else {
                X86Opcode::ADD32ri as u16
            },
            temp_reg,
            temp_reg,
            probe_interval_imm,
        ));

        // CMP temp, 0 (implicitly sets ZF if temp == 0)
        // JNZ loop_label

        let probe_count = self.probe_count_for_size(0); // dynamic — not known statically
        self.inc_stat(|s| s.total_bytes_probed += probe_count * self.probe_interval);

        ProbeEmissionResult {
            instructions: instrs,
            probes_emitted: 1, // one loop that covers all pages
            is_runtime_call: false,
            bytes_probed: 0, // dynamic — size unknown at compile time
        }
    }

    /// Emits an inline probing sequence that touches each page.
    ///
    /// This is the default strategy for non-Windows targets. It generates a
    /// loop that decrements the stack pointer one page at a time, touching
    /// each page to ensure guard pages are triggered.
    fn emit_inline_probe(&self, frame_size: u64) -> ProbeEmissionResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        if frame_size <= self.probe_interval {
            // Small frame: just one touch is enough
            // SUB RSP, frame_size
            // TEST [RSP], RSP
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::SUB64ri32 as u16
                } else {
                    X86Opcode::SUB32ri as u16
                },
                VirtReg::phys(sp_reg),
                VirtReg::phys(sp_reg),
                -(frame_size as i64),
            ));
            instrs.push(MachineInstr::new_mem_test(
                VirtReg::phys(sp_reg),
                0,
                if is_64bit { 8 } else { 4 },
            ));

            self.inc_stat(|s| s.total_bytes_probed += frame_size);
            self.inc_stat(|s| s.probe_loops += 1);

            return ProbeEmissionResult {
                instructions: instrs,
                probes_emitted: 1,
                is_runtime_call: false,
                bytes_probed: frame_size,
            };
        }

        // Large frame: probe loop
        let probe_count = self.probe_count_for_size(frame_size);
        let aligned_size = probe_count * self.probe_interval;
        let temp_reg = VirtReg::new();

        // MOV temp, aligned_size (negated for loop)
        let neg_size = -(aligned_size as i64);
        instrs.push(MachineInstr::new_mov_imm(temp_reg, neg_size));

        let _loop_label = format!(
            ".Lprobe_static_{}",
            self.probe_count.fetch_add(1, Ordering::Relaxed)
        );

        // Loop:
        //   LEA RSP, [RSP + temp]  — adjust SP by temp (negative)
        //   TEST [RSP], RSP         — touch the page
        //   ADD temp, probe_interval
        //   JNZ loop_label
        instrs.push(MachineInstr::new_lea(
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            temp_reg,
            1,
            0,
        ));
        instrs.push(MachineInstr::new_mem_test(
            VirtReg::phys(sp_reg),
            0,
            if is_64bit { 8 } else { 4 },
        ));
        instrs.push(MachineInstr::new_alu_imm(
            if is_64bit {
                X86Opcode::ADD64ri32 as u16
            } else {
                X86Opcode::ADD32ri as u16
            },
            temp_reg,
            temp_reg,
            self.probe_interval as i64,
        ));
        // JNZ loop_label would be emitted here in a real lowering

        self.inc_stat(|s| {
            s.total_bytes_probed += aligned_size;
            s.probe_loops += 1;
        });

        ProbeEmissionResult {
            instructions: instrs,
            probes_emitted: probe_count,
            is_runtime_call: false,
            bytes_probed: aligned_size,
        }
    }

    /// Emits a call to `__chkstk` or `__chkstk_ms`.
    ///
    /// `__chkstk` (Windows):
    /// - Input: RAX = number of bytes to allocate
    /// - Touches pages from RSP downward
    /// - Subtracts RAX from RSP
    /// - Preserves all registers except RAX
    ///
    /// `__chkstk_ms` (MSVC variant):
    /// - Same as __chkstk, but preserves all volatile registers
    ///   (uses R10/R11 internally)
    ///
    /// # Arguments
    ///
    /// * `frame_size` — if > 0, emits MOV RAX, frame_size before the call.
    ///   If 0, assumes RAX already contains the size.
    /// * `ms_variant` — if true, calls `__chkstk_ms` instead of `__chkstk`.
    fn emit_chkstk_call(&self, frame_size: u64, ms_variant: bool) -> ProbeEmissionResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let rax = if is_64bit { RAX } else { EAX };

        if frame_size > 0 {
            // MOV RAX, frame_size
            instrs.push(MachineInstr::new_mov_imm(
                VirtReg::phys(rax),
                frame_size as i64,
            ));
        }

        // CALL __chkstk or __chkstk_ms
        let symbol = if ms_variant {
            "__chkstk_ms"
        } else {
            "__chkstk"
        };
        instrs.push(MachineInstr::new_call(symbol));

        // After __chkstk returns, RSP has been adjusted by RAX bytes.
        // No further SUB RSP is needed.

        self.inc_stat(|s| {
            s.chkstk_calls += 1;
            s.total_bytes_probed += frame_size;
        });

        ProbeEmissionResult {
            instructions: instrs,
            probes_emitted: 1,
            is_runtime_call: true,
            bytes_probed: frame_size,
        }
    }

    /// Emits the prologue probing sequence for a function.
    ///
    /// This is called during function prologue emission, after the frame
    /// pointer is set up (if used), to probe the static frame.
    ///
    /// # Arguments
    ///
    /// * `layout` — the computed stack frame layout.
    ///
    /// # Returns
    ///
    /// A `ProbeEmissionResult` with the prologue probe instructions.
    pub fn emit_prologue_probe(&self, layout: &StackFrameLayout) -> ProbeEmissionResult {
        if !layout.requires_static_probe {
            return ProbeEmissionResult {
                instructions: Vec::new(),
                probes_emitted: 0,
                is_runtime_call: false,
                bytes_probed: 0,
            };
        }
        self.emit_static_probe(layout.fixed_frame_size)
    }

    /// Emits a gap probe between two dynamic allocations.
    ///
    /// Under stack clash protection, if two allocas are separated by more
    /// than one probe interval, a gap probe must be inserted to ensure the
    /// guard pages in the gap are touched.
    ///
    /// # Arguments
    ///
    /// * `gap_size` — the number of bytes between the two allocations.
    ///
    /// # Returns
    ///
    /// A `ProbeEmissionResult`.
    pub fn emit_gap_probe(&self, gap_size: u64) -> ProbeEmissionResult {
        if gap_size <= self.probe_interval {
            return ProbeEmissionResult {
                instructions: Vec::new(),
                probes_emitted: 0,
                is_runtime_call: false,
                bytes_probed: 0,
            };
        }

        self.inc_stat(|s| s.gap_probes += 1);
        self.emit_static_probe(gap_size)
    }

    /// Computes the set of probe points for a given frame size.
    ///
    /// Each probe point represents a page that must be touched to ensure
    /// guard pages are activated for the entire allocation.
    ///
    /// # Arguments
    ///
    /// * `frame_size` — the size of the allocation.
    ///
    /// # Returns
    ///
    /// A vector of `ProbePoint`s, one per page to probe.
    pub fn compute_probe_points(&self, frame_size: u64) -> Vec<ProbePoint> {
        if frame_size == 0 {
            return Vec::new();
        }
        let num_probes = self.probe_count_for_size(frame_size);
        let mut points = Vec::with_capacity(num_probes as usize);
        for i in 0..num_probes {
            points.push(ProbePoint {
                // Each probe touches [RSP - (i+1) * probe_interval]
                address_offset: -((i + 1) as i64 * self.probe_interval as i64),
                page_index: i,
            });
        }
        points
    }

    /// Checks if a static frame of `frame_size` bytes needs stack clash probing.
    pub fn needs_stack_clash_probe(&self, frame_size: u64) -> bool {
        self.stack_clash_protection && frame_size > MAX_FRAME_SIZE_WITHOUT_PROBE
    }

    /// Returns the number of pages touched by a probe of `frame_size` bytes.
    pub fn pages_touched(&self, frame_size: u64) -> u64 {
        self.probe_count_for_size(frame_size)
    }
}

// ============================================================================
// Dynamic Stack Realignment — mstackrealign, DRAP, frame pointer setup
// ============================================================================

/// The result of emitting dynamic stack realignment code.
#[derive(Debug, Clone)]
pub struct RealignmentResult {
    /// Instructions for realignment (emitted in prologue).
    pub instructions: Vec<MachineInstr>,
    /// The alignment achieved.
    pub alignment: u64,
    /// Whether DRAP was used.
    pub used_drap: bool,
    /// The DRAP register, if used.
    pub drap_register: Option<u16>,
    /// The old frame pointer value (if frame pointer was saved to DRAP).
    pub saved_fp_reg: Option<VirtReg>,
    /// The amount by which SP was adjusted for alignment.
    pub adjustment_amount: u64,
    /// Whether frame pointer was reconfigured for the realigned stack.
    pub fp_reconfigured: bool,
}

impl X86StackProbing {
    /// Emits code for dynamic stack realignment in the function prologue.
    ///
    /// When `-mstackrealign` is enabled, the stack pointer is aligned to a
    /// specified boundary at runtime. This is necessary when the ABI-guaranteed
    /// alignment (16 bytes on x86-64) is insufficient for local variables
    /// that require higher alignment (e.g., `__m256` requiring 32 bytes,
    /// `__m512` requiring 64 bytes).
    ///
    /// The realignment sequence (x86-64):
    /// ```asm
    /// push %rbp
    /// mov  %rsp, %rbp
    /// push %r10          ; save DRAP register if needed
    /// and  %rsp, -align  ; align SP to 'align' bytes
    /// mov  %rbp, %r10    ; DRAP ← old frame pointer (optional)
    /// ```
    ///
    /// DRAP is used when the frame pointer is needed but the base register
    /// is unavailable (e.g., all 7 callee-saved GPRs are in use). The DRAP
    /// register stores the original %rbp value so that frame objects can
    /// still be addressed.
    ///
    /// # Arguments
    ///
    /// * `alignment` — the byte alignment (must be a power of 2, max 128).
    /// * `needs_frame_pointer` — whether the function needs a frame pointer.
    /// * `base_reg_available` — whether the normal base register is free.
    ///
    /// # Returns
    ///
    /// A `RealignmentResult` describing the emitted instructions.
    pub fn emit_dynamic_realignment(
        &self,
        alignment: RealignAlignment,
        needs_frame_pointer: bool,
        base_reg_available: bool,
    ) -> RealignmentResult {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };
        let bp_reg = if is_64bit { RBP } else { EBP32_REG };

        if alignment == RealignAlignment::None {
            return RealignmentResult {
                instructions: instrs,
                alignment: 0,
                used_drap: false,
                drap_register: None,
                saved_fp_reg: None,
                adjustment_amount: 0,
                fp_reconfigured: false,
            };
        }

        let align_bytes = alignment.byte_value();
        self.inc_stat(|s| s.realigned_functions += 1);

        // Step 1: Save frame pointer (if used)
        let mut used_drap = false;
        let mut saved_fp = None;

        if needs_frame_pointer {
            // PUSH RBP
            instrs.push(MachineInstr::new_push(bp_reg));
            // MOV RBP, RSP
            instrs.push(MachineInstr::new_copy(
                VirtReg::phys(bp_reg),
                VirtReg::phys(sp_reg),
            ));
        }

        // Step 2: Determine if DRAP is needed
        // DRAP is needed when:
        // - We must realign the stack (AND with mask changes SP), AND
        // - The frame pointer base is not usable (e.g., RBX is used as base), AND
        // - The function has variable allocas or needs FP-relative addressing
        let need_drap =
            !base_reg_available && alignment != RealignAlignment::None && self.uses_frame_pointer;

        if need_drap && self.drap_available {
            let drap = self.drap_register;
            // PUSH drap  (save the DRAP register on the stack)
            instrs.push(MachineInstr::new_push(drap));
            used_drap = true;
            saved_fp = Some(VirtReg::new());
            // Save current RBP into a virtual register (will be moved to DRAP later)
            instrs.push(MachineInstr::new_copy(
                saved_fp.unwrap(),
                VirtReg::phys(bp_reg),
            ));
        }

        // Step 3: Align the stack pointer
        // AND RSP, ~(align_bytes - 1)
        let mask = !(align_bytes as i64 - 1);
        instrs.push(MachineInstr::new_alu_imm(
            if is_64bit {
                X86Opcode::AND64ri32 as u16
            } else {
                X86Opcode::AND32ri as u16
            },
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            mask,
        ));

        // Step 4: If DRAP is used, move the original BP into DRAP
        if used_drap {
            let drap = self.drap_register;
            if let Some(fp_reg) = saved_fp {
                instrs.push(MachineInstr::new_copy(VirtReg::phys(drap), fp_reg));
            }
        }

        // Step 5: Emit frame pointer setup if needed
        let fp_reconfigured = needs_frame_pointer && !used_drap;
        if fp_reconfigured {
            // PUSH old RBP
            // MOV RBP, RSP  — already done above
            // Frame pointer is now set to the realigned SP
        }

        // Step 6: Allocate space for the local frame
        let local_frame_size = self.compute_local_frame_size();
        if local_frame_size > 0 {
            instrs.push(MachineInstr::new_alu_imm(
                if is_64bit {
                    X86Opcode::SUB64ri32 as u16
                } else {
                    X86Opcode::SUB32ri as u16
                },
                VirtReg::phys(sp_reg),
                VirtReg::phys(sp_reg),
                -(local_frame_size as i64),
            ));
        }

        RealignmentResult {
            instructions: instrs,
            alignment: align_bytes,
            used_drap,
            drap_register: if used_drap {
                Some(self.drap_register)
            } else {
                None
            },
            saved_fp_reg: saved_fp,
            adjustment_amount: local_frame_size,
            fp_reconfigured,
        }
    }

    /// Emits the epilogue counterpart for dynamic realignment.
    ///
    /// This restores the stack pointer from the frame pointer (or DRAP register)
    /// and pops any saved registers.
    ///
    /// # Arguments
    ///
    /// * `result` — the `RealignmentResult` from `emit_dynamic_realignment`.
    ///
    /// # Returns
    ///
    /// Vector of machine instructions for the epilogue.
    pub fn emit_realignment_epilogue(&self, result: &RealignmentResult) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let bp_reg = if is_64bit { RBP } else { EBP32_REG };

        if result.alignment == 0 {
            return instrs;
        }

        // MOV RSP, RBP  (restore SP to BP)
        instrs.push(MachineInstr::new_copy(
            VirtReg::phys(if is_64bit { RSP } else { ESP32_REG }),
            VirtReg::phys(bp_reg),
        ));

        // If DRAP was used, pop the DRAP register
        if result.used_drap {
            if let Some(drap) = result.drap_register {
                instrs.push(MachineInstr::new_pop(drap));
            }
        }

        // POP RBP (restore frame pointer)
        instrs.push(MachineInstr::new_pop(bp_reg));

        // RET
        instrs.push(MachineInstr::new_ret());

        instrs
    }

    /// Checks whether dynamic realignment would be beneficial.
    ///
    /// Returns `true` if realigning the stack could allow better code
    /// generation (e.g., aligned loads for vector types).
    pub fn should_realign(&self, has_overaligned_locals: bool) -> bool {
        if !self.realign_enabled {
            return false;
        }
        has_overaligned_locals
            && self.realign_alignment != RealignAlignment::None
            && self.calling_conv.is_64bit()
    }

    /// Returns the DRAP register to use.
    pub fn get_drap_register(&self) -> u16 {
        if self.drap_available {
            self.drap_register
        } else {
            // Fallback: use frame pointer itself
            if self.calling_conv.is_64bit() {
                RBP
            } else {
                EBP32_REG
            }
        }
    }

    /// Returns whether a DRAP register is needed.
    pub fn needs_drap(&self, base_reg_available: bool, has_allocas: bool) -> bool {
        self.realign_enabled && !base_reg_available && has_allocas && self.drap_available
    }

    /// Computes the local frame size given a layout.
    fn compute_local_frame_size(&self) -> u64 {
        // In a real implementation, this would be computed from the layout
        // For now, return the fixed frame size
        0
    }
}

// ============================================================================
// Stack Clash Protection — -fstack-clash-protection
// ============================================================================

/// Configuration for stack clash protection.
#[derive(Debug, Clone)]
pub struct StackClashConfig {
    /// Whether stack clash protection is enabled.
    pub enabled: bool,
    /// The probe interval (default: 4096).
    pub probe_interval: u64,
    /// Whether to emit explicit probes at function entry for large frames.
    pub probe_entry: bool,
    /// Whether to emit gap probes between dynamic allocations.
    pub probe_gaps: bool,
    /// The minimum frame size that triggers entry probing.
    pub probe_threshold: u64,
    /// Whether to use `__chkstk` on Windows for clash protection.
    pub use_chkstk: bool,
}

impl Default for StackClashConfig {
    fn default() -> Self {
        StackClashConfig {
            enabled: false,
            probe_interval: DEFAULT_PROBE_INTERVAL,
            probe_entry: true,
            probe_gaps: true,
            probe_threshold: MAX_FRAME_SIZE_WITHOUT_PROBE,
            use_chkstk: false,
        }
    }
}

/// The result of applying stack clash protection to a frame.
#[derive(Debug, Clone)]
pub struct StackClashResult {
    /// Whether protection was applied.
    pub protected: bool,
    /// Number of entry probes emitted.
    pub entry_probes: u64,
    /// Number of gap probes emitted.
    pub gap_probes: u64,
    /// Number of bytes covered by entry probes.
    pub entry_bytes_probed: u64,
    /// Number of bytes covered by gap probes.
    pub gap_bytes_probed: u64,
    /// Total probe overhead (in bytes of code).
    pub code_overhead_bytes: u64,
    /// Whether a runtime function was used.
    pub used_runtime: bool,
    /// Severity assessment before/after protection.
    pub severity_before: ClashSeverity,
    pub severity_after: ClashSeverity,
}

impl X86StackProbing {
    /// Applies stack clash protection to the given frame layout.
    ///
    /// This function analyzes the frame layout and emits appropriate probing
    /// instructions. Under `-fstack-clash-protection`:
    ///
    /// 1. **Entry probe**: If the static frame exceeds `probe_threshold`, an
    ///    explicit probe loop (or `__chkstk` call) is emitted at function
    ///    entry. This touches pages from the current stack pointer down to
    ///    the bottom of the fixed frame.
    ///
    /// 2. **Gap probes**: Between consecutive dynamic allocations (allocas),
    ///    if the gap exceeds one probe interval, a probe is emitted to touch
    ///    the pages in the gap. This prevents skipping guard pages between
    ///    two variable-size allocations.
    ///
    /// 3. **Dynamic probes**: Each `alloca` larger than one probe interval
    ///    is probed individually, touching all pages in the dynamic region.
    ///
    /// ## Rationale
    ///
    /// Without stack clash protection, a sufficiently large `alloca` can
    /// "jump over" the stack guard page into another memory region (e.g.,
    /// the heap or a shared library mapping). By touching every page, we
    /// ensure that the OS has a chance to expand the stack or signal a fault
    /// at the guard page boundary.
    ///
    /// # Arguments
    ///
    /// * `layout` — the computed stack frame layout.
    ///
    /// # Returns
    ///
    /// A `StackClashResult` summarizing what protection was applied.
    pub fn apply_stack_clash_protection(&self, layout: &StackFrameLayout) -> StackClashResult {
        let severity_before = self.assess_clash_severity(layout);

        if !self.stack_clash_protection {
            return StackClashResult {
                protected: false,
                entry_probes: 0,
                gap_probes: 0,
                entry_bytes_probed: 0,
                gap_bytes_probed: 0,
                code_overhead_bytes: 0,
                used_runtime: false,
                severity_before,
                severity_after: severity_before,
            };
        }

        self.inc_stat(|s| s.clash_protected_functions += 1);

        let mut entry_probes = 0u64;
        let mut gap_probes = 0u64;
        let mut entry_bytes = 0u64;
        let mut gap_bytes = 0u64;
        let mut used_runtime = false;

        // Entry probe for static frame
        if layout.fixed_frame_size > MAX_FRAME_SIZE_WITHOUT_PROBE {
            let result = self.emit_static_probe(layout.fixed_frame_size);
            entry_probes = result.probes_emitted;
            entry_bytes = result.bytes_probed;
            used_runtime = result.is_runtime_call;
        }

        // Gap probes between variable allocations
        if layout.has_variable_allocas && self.probe_dynamic_alloca {
            let mut prev_end: i64 = 0;
            for (i, var_obj) in layout.variable_objects.iter().enumerate() {
                if i > 0 {
                    let gap = (prev_end - var_obj.fp_offset).abs() as u64;
                    if gap > self.probe_interval {
                        let gap_result = self.emit_gap_probe(gap);
                        gap_probes += gap_result.probes_emitted;
                        gap_bytes += gap_result.bytes_probed;
                    }
                }
                prev_end = var_obj.fp_offset - var_obj.size as i64;
            }
        }

        // Estimate code overhead (very rough: ~5 bytes per probe instruction)
        let code_overhead = (entry_probes + gap_probes) * 5;

        let severity_after = ClashSeverity::None; // Protection resolves the threat

        StackClashResult {
            protected: true,
            entry_probes,
            gap_probes,
            entry_bytes_probed: entry_bytes,
            gap_bytes_probed: gap_bytes,
            code_overhead_bytes: code_overhead,
            used_runtime,
            severity_before,
            severity_after,
        }
    }

    /// Configures stack clash protection from compiler flags.
    ///
    /// Parses the `-fstack-clash-protection` flag and sets up the
    /// `StackClashConfig` accordingly.
    pub fn configure_stack_clash(&mut self, enable: bool, probe_interval: Option<u64>) {
        self.stack_clash_protection = enable;
        if let Some(interval) = probe_interval {
            self.set_probe_interval(interval);
        }
    }

    /// Returns whether a gap probe is needed between two allocations.
    pub fn needs_gap_probe(&self, gap_size: u64) -> bool {
        self.stack_clash_protection && gap_size > self.probe_interval
    }

    /// Returns the probe threshold for static frames.
    pub fn probe_threshold(&self) -> u64 {
        if self.stack_clash_protection {
            MAX_FRAME_SIZE_WITHOUT_PROBE
        } else {
            u64::MAX // never probe if no clash protection
        }
    }
}

// ============================================================================
// Stack Frame Layout Computation
// ============================================================================

/// Information needed to compute a stack frame layout.
#[derive(Debug, Clone, Default)]
pub struct FrameInfo {
    /// Calling convention to use.
    pub calling_conv: CallingConv,
    /// Whether the function uses a frame pointer.
    pub uses_frame_pointer: bool,
    /// List of callee-saved registers to spill.
    pub callee_saved_regs: Vec<u16>,
    /// Size of each callee-saved register (8 for x86-64, 4 for x86-32).
    pub reg_size: u64,
    /// Fixed-size local variables: (size, alignment) pairs.
    pub fixed_locals: Vec<(u64, u64)>,
    /// Number of variable-size allocations (allocas).
    pub num_variable_allocas: u32,
    /// Size of the outgoing argument area.
    pub outgoing_arg_size: u64,
    /// Whether this is a leaf function (makes no calls).
    pub is_leaf: bool,
    /// Whether stack realignment is needed.
    pub needs_realignment: bool,
    /// Stack realignment amount (0 if not needed).
    pub realign_amount: u64,
    /// Whether a stack protector canary is needed.
    pub has_stack_protector: bool,
    /// Whether debugging information requires a frame pointer.
    pub debug_requires_fp: bool,
}

impl X86StackProbing {
    /// Computes the complete stack frame layout for a function.
    ///
    /// This is the main entry point for frame layout computation. It:
    /// 1. Determines the offset of the return address
    /// 2. Sizes the callee-saved register spill area
    /// 3. Places fixed locals with proper alignment
    /// 4. Reserves space for the outgoing argument area
    /// 5. Adds shadow space (Win64) or red zone (SysV)
    /// 6. Determines probing requirements
    ///
    /// # Arguments
    ///
    /// * `info` — information about the function's frame requirements.
    ///
    /// # Returns
    ///
    /// A `StackFrameLayout` describing the complete frame.
    pub fn compute_frame_layout(&self, info: &FrameInfo) -> StackFrameLayout {
        let cc = info.calling_conv;
        let _is_64bit = cc.is_64bit();

        let mut layout = StackFrameLayout::new(cc);
        layout.has_frame_pointer = info.uses_frame_pointer || info.debug_requires_fp;
        layout.has_dynamic_realignment = info.needs_realignment;
        layout.realign_amount = info.realign_amount;
        layout.has_variable_allocas = info.num_variable_allocas > 0;
        layout.can_use_red_zone = info.is_leaf && cc == CallingConv::SystemV;
        layout.probe_interval = self.probe_interval;

        if info.needs_realignment {
            layout.stack_alignment = info.realign_amount.max(layout.stack_alignment);
        }

        // --- Step 1: Determine return address offset ---
        // The return address is at RSP+0 on function entry (pushed by CALL).
        // If we push RBP for a frame pointer, it's at RBP+8.
        layout.return_address_offset = if layout.has_frame_pointer {
            info.reg_size as i64
        } else {
            0
        };

        // --- Step 2: Compute callee-saved register spill area ---
        let mut current_offset: i64 = 0;
        if layout.has_frame_pointer {
            // Space for saved RBP
            current_offset += info.reg_size as i64;
        }

        for &reg in &info.callee_saved_regs {
            let id = self.next_frame_object_id();
            let spill = FrameObject::new_callee_saved(
                id,
                reg,
                info.reg_size,
                -current_offset,
                -current_offset,
            );
            layout.callee_saved_spills.push(spill);
            current_offset += info.reg_size as i64;
        }

        // --- Step 3: Place fixed locals ---
        let mut fp_offset = -current_offset;
        for (_i, &(size, align)) in info.fixed_locals.iter().enumerate() {
            // Align the offset
            let aligned_offset = StackFrameLayout::align_offset((-fp_offset) as u64, align) as i64;
            let id = self.next_frame_object_id();
            let fixed_obj = FrameObject::new_fixed(
                id,
                size,
                align,
                -aligned_offset - size as i64,
                -aligned_offset - size as i64,
            );
            fp_offset = -aligned_offset - size as i64;
            layout.fixed_objects.push(fixed_obj);
        }

        layout.fixed_frame_size = (-fp_offset) as u64;

        // --- Step 4: Outgoing argument area ---
        layout.outgoing_arg_size = info.outgoing_arg_size;
        layout.max_call_frame_size = info.outgoing_arg_size;

        // --- Step 5: Shadow space (Win64) ---
        if cc.requires_shadow_space() {
            layout.shadow_space_size = SHADOW_SPACE_WIN64;
        }

        // --- Step 6: Total frame size ---
        let total_fixed =
            layout.fixed_frame_size + layout.outgoing_arg_size + layout.shadow_space_size;
        // Align to stack alignment
        layout.total_frame_size =
            StackFrameLayout::align_offset(total_fixed, layout.stack_alignment);

        // --- Step 7: Determine probing requirements ---
        layout.requires_static_probe = self.requires_static_probe(layout.fixed_frame_size);
        layout.requires_dynamic_probe = layout.has_variable_allocas && self.probe_dynamic_alloca;

        // --- Step 8: Set DRAP register if needed ---
        if layout.has_dynamic_realignment && self.realign_enabled {
            layout.drap_register = Some(self.drap_register);
        }

        layout
    }

    /// Computes a minimal frame layout for a leaf function.
    ///
    /// Leaf functions (those that make no calls) can use the red zone on
    /// SysV AMD64, avoiding stack pointer adjustment entirely for small frames.
    pub fn compute_leaf_frame_layout(&self, info: &FrameInfo) -> StackFrameLayout {
        let mut layout = self.compute_frame_layout(info);
        layout.can_use_red_zone = info.is_leaf && info.calling_conv == CallingConv::SystemV;

        // If the total frame fits in the red zone, we can eliminate SP adjustment
        if layout.can_use_red_zone && layout.total_frame_size <= RED_ZONE_SIZE_SYSV {
            layout.total_frame_size = 0;
            layout.requires_static_probe = false;
        }

        layout
    }

    /// Computes a frame layout for a function with Win64 ABI constraints.
    pub fn compute_win64_frame_layout(&self, info: &FrameInfo) -> StackFrameLayout {
        let mut layout = self.compute_frame_layout(info);

        // Win64 requires 16-byte alignment after the return address is pushed
        // The CALL instruction pushes 8 bytes, so an additional 8 bytes of
        // alignment padding is needed if we push RBP (8 bytes)
        if layout.has_frame_pointer {
            // 8 (ret addr) + 8 (rbp) = 16 — already aligned
        } else {
            // Ensure frame size is 16-byte aligned
            layout.total_frame_size =
                StackFrameLayout::align_offset(layout.total_frame_size, STACK_ALIGNMENT_WIN64);
        }

        // Win64 always uses __chkstk for large frames
        if layout.total_frame_size > DEFAULT_PROBE_INTERVAL {
            layout.requires_static_probe = true;
        }

        layout
    }

    /// Validates that a frame layout is consistent with ABI requirements.
    ///
    /// Returns a list of validation errors, if any.
    pub fn validate_frame_layout(&self, layout: &StackFrameLayout) -> Vec<String> {
        let mut errors = Vec::new();

        // Check alignment
        if layout.total_frame_size % layout.stack_alignment != 0 {
            errors.push(format!(
                "Frame size {} is not aligned to {}",
                layout.total_frame_size, layout.stack_alignment
            ));
        }

        // Check red zone constraints
        if layout.can_use_red_zone && !layout.calling_conv.has_red_zone() {
            errors.push("Red zone requested for non-SysV ABI".to_string());
        }

        // Check shadow space
        if layout.calling_conv.requires_shadow_space() && layout.shadow_space_size == 0 {
            errors.push("Shadow space required for Win64 ABI but size is 0".to_string());
        }

        // Check DRAP availability
        if layout.has_dynamic_realignment && layout.drap_register.is_some() && !self.drap_available
        {
            errors.push("DRAP register needed but not available".to_string());
        }

        // Check probing consistency
        if layout.requires_static_probe && self.probe_strategy == ProbeStrategy::None {
            errors.push("Static probing required but strategy is None".to_string());
        }

        errors
    }

    /// Returns a human-readable description of the frame layout.
    pub fn describe_frame_layout(&self, layout: &StackFrameLayout) -> String {
        let mut desc = String::new();
        desc.push_str(&format!(
            "Stack Frame Layout ({:?}, {}):\n",
            layout.calling_conv,
            if layout.calling_conv.is_64bit() {
                "x86-64"
            } else {
                "x86-32"
            }
        ));
        desc.push_str(&format!(
            "  Frame pointer:       {}\n",
            if layout.has_frame_pointer {
                "yes"
            } else {
                "no"
            }
        ));
        desc.push_str(&format!(
            "  Dynamic realignment: {}",
            if layout.has_dynamic_realignment {
                format!("yes ({}B)", layout.realign_amount)
            } else {
                "no".to_string()
            }
        ));
        if let Some(drap) = layout.drap_register {
            desc.push_str(&format!(", DRAP=r{}", drap));
        }
        desc.push('\n');
        desc.push_str(&format!(
            "  Callee-saved spills: {} objects, {} bytes\n",
            layout.callee_saved_spills.len(),
            layout.callee_saved_size()
        ));
        desc.push_str(&format!(
            "  Fixed locals:        {} objects, {} bytes\n",
            layout.fixed_objects.len(),
            layout.fixed_frame_size
        ));
        desc.push_str(&format!(
            "  Variable allocas:    {}\n",
            if layout.has_variable_allocas {
                "yes"
            } else {
                "no"
            }
        ));
        desc.push_str(&format!(
            "  Outgoing args:       {} bytes\n",
            layout.outgoing_arg_size
        ));
        desc.push_str(&format!(
            "  Shadow space:        {} bytes\n",
            layout.shadow_space_size
        ));
        desc.push_str(&format!(
            "  Red zone usable:     {}\n",
            if layout.can_use_red_zone { "yes" } else { "no" }
        ));
        desc.push_str(&format!(
            "  Total frame size:    {} bytes\n",
            layout.total_frame_size
        ));
        desc.push_str(&format!(
            "  Static probe:        {}\n",
            if layout.requires_static_probe {
                "required"
            } else {
                "not required"
            }
        ));
        desc.push_str(&format!(
            "  Dynamic probe:       {}\n",
            if layout.requires_dynamic_probe {
                "required"
            } else {
                "not required"
            }
        ));
        desc.push_str(&format!(
            "  Probe interval:      {} bytes\n",
            layout.probe_interval
        ));
        desc
    }
}

// ============================================================================
// Frame Layout Helpers — Shadow Space, Red Zone, Outgoing Args
// ============================================================================

/// Helper for managing the Win64 shadow space (home space for register args).
#[derive(Debug, Clone)]
pub struct ShadowSpaceManager {
    /// Whether shadow space is active.
    pub active: bool,
    /// Size of the shadow space (32 bytes on Win64).
    pub size: u64,
    /// Offset of the shadow space from the stack pointer.
    pub sp_offset: i64,
}

impl ShadowSpaceManager {
    /// Creates a new shadow space manager.
    pub fn new(active: bool) -> Self {
        ShadowSpaceManager {
            active,
            size: if active { SHADOW_SPACE_WIN64 } else { 0 },
            sp_offset: 0,
        }
    }

    /// Returns the offset from SP to the start of the shadow space.
    pub fn offset_to_shadow(&self) -> i64 {
        self.sp_offset
    }

    /// Returns the offset from SP to the i-th shadow space slot (i in 0..3).
    pub fn shadow_slot_offset(&self, slot: u32) -> i64 {
        assert!(slot < 4, "Only 4 shadow slots (0-3) exist in Win64");
        self.sp_offset + (slot as i64) * 8
    }

    /// Returns `true` if the shadow space is large enough for `n_args` register arguments.
    pub fn can_fit_args(&self, n_args: u32) -> bool {
        !self.active || (n_args as u64) * 8 <= self.size
    }
}

/// Helper for managing the System V AMD64 red zone.
#[derive(Debug, Clone)]
pub struct RedZoneManager {
    /// Whether the red zone is usable.
    pub usable: bool,
    /// Size of the red zone (128 bytes).
    pub size: u64,
    /// How many bytes of the red zone are currently in use.
    pub used: u64,
}

impl RedZoneManager {
    /// Creates a new red zone manager.
    pub fn new(usable: bool) -> Self {
        RedZoneManager {
            usable,
            size: if usable { RED_ZONE_SIZE_SYSV } else { 0 },
            used: 0,
        }
    }

    /// Attempts to allocate `bytes` in the red zone.
    ///
    /// Returns `true` if the allocation fits, `false` if the red zone is full
    /// or unavailable.
    pub fn allocate(&mut self, bytes: u64) -> bool {
        if !self.usable {
            return false;
        }
        if self.used + bytes <= self.size {
            self.used += bytes;
            true
        } else {
            false
        }
    }

    /// Returns the offset from RSP for an allocation at the given index.
    pub fn offset_for_allocation(&self, index: u32) -> i64 {
        // Red zone is below RSP, so offsets are negative
        -((index as i64) * 8) - 8
    }

    /// Returns the remaining bytes in the red zone.
    pub fn remaining(&self) -> u64 {
        if self.usable {
            self.size - self.used
        } else {
            0
        }
    }

    /// Resets the used count.
    pub fn reset(&mut self) {
        self.used = 0;
    }
}

/// Helper for managing the outgoing argument area.
#[derive(Debug, Clone)]
pub struct OutgoingArgManager {
    /// Total size of the outgoing argument area.
    pub total_size: u64,
    /// Currently allocated size.
    pub allocated: u64,
    /// Whether the area has been finalized.
    pub finalized: bool,
}

impl OutgoingArgManager {
    /// Creates a new outgoing argument area manager.
    pub fn new() -> Self {
        OutgoingArgManager {
            total_size: 0,
            allocated: 0,
            finalized: false,
        }
    }

    /// Reserves `size` bytes in the outgoing argument area.
    ///
    /// The area is grown to accommodate the largest call in the function.
    pub fn reserve(&mut self, size: u64) {
        self.total_size = self.total_size.max(size);
    }

    /// Finalizes the area size and returns the aligned size.
    pub fn finalize(&mut self, alignment: u64) -> u64 {
        self.finalized = true;
        StackFrameLayout::align_offset(self.total_size, alignment)
    }

    /// Returns the offset from SP to the start of the outgoing argument area.
    pub fn sp_offset(&self) -> i64 {
        0 // Outgoing args are at the top of the frame (lowest address)
    }

    /// Returns the SP offset for the i-th argument.
    pub fn arg_offset(&self, arg_index: u32) -> i64 {
        (arg_index as i64) * 8
    }
}

// ============================================================================
// Alloca Tracking — Variable-Size Frame Objects
// ============================================================================

/// Tracks all `alloca` / VLA allocations within a function.
#[derive(Debug, Clone, Default)]
pub struct AllocaTracker {
    /// All tracked alloca allocations.
    pub allocas: Vec<AllocaRecord>,
    /// Whether any alloca is in the entry block.
    pub has_entry_alloca: bool,
    /// Total number of bytes allocated dynamically (approximate).
    pub total_dynamic_bytes: u64,
    /// Whether stacksave/stackrestore is needed.
    pub needs_save_restore: bool,
}

/// A record of a single alloca / VLA allocation.
#[derive(Debug, Clone)]
pub struct AllocaRecord {
    /// The virtual register holding the allocation size.
    pub size_reg: VirtReg,
    /// The virtual register receiving the result pointer.
    pub result_reg: VirtReg,
    /// Required alignment.
    pub alignment: u64,
    /// Whether this alloca is in the entry block.
    pub in_entry_block: bool,
    /// The stack pointer before this alloca.
    pub old_sp: Option<VirtReg>,
    /// The stack pointer after this alloca.
    pub new_sp: Option<VirtReg>,
    /// Whether probing was applied.
    pub probed: bool,
    /// The frame object created.
    pub frame_object: Option<FrameObject>,
}

impl AllocaTracker {
    /// Creates a new alloca tracker.
    pub fn new() -> Self {
        AllocaTracker::default()
    }

    /// Registers a new alloca.
    pub fn register_alloca(
        &mut self,
        size_reg: VirtReg,
        result_reg: VirtReg,
        alignment: u64,
        in_entry_block: bool,
    ) -> usize {
        let idx = self.allocas.len();
        self.allocas.push(AllocaRecord {
            size_reg,
            result_reg,
            alignment,
            in_entry_block,
            old_sp: None,
            new_sp: None,
            probed: false,
            frame_object: None,
        });
        if in_entry_block {
            self.has_entry_alloca = true;
        }
        self.needs_save_restore =
            self.allocas.len() > 1 || (self.allocas.len() == 1 && !in_entry_block);
        idx
    }

    /// Updates an alloca record with the result of lowering.
    pub fn update_alloca_result(
        &mut self,
        idx: usize,
        old_sp: VirtReg,
        new_sp: VirtReg,
        probed: bool,
        frame_object: FrameObject,
    ) {
        if let Some(record) = self.allocas.get_mut(idx) {
            record.old_sp = Some(old_sp);
            record.new_sp = Some(new_sp);
            record.probed = probed;
            record.frame_object = Some(frame_object);
        }
    }

    /// Returns the total number of allocated allocas.
    pub fn count(&self) -> usize {
        self.allocas.len()
    }

    /// Returns all entry-block allocas.
    pub fn entry_allocas(&self) -> impl Iterator<Item = &AllocaRecord> {
        self.allocas.iter().filter(|a| a.in_entry_block)
    }

    /// Returns all non-entry allocas.
    pub fn non_entry_allocas(&self) -> impl Iterator<Item = &AllocaRecord> {
        self.allocas.iter().filter(|a| !a.in_entry_block)
    }

    /// Returns `true` if stack probing is needed for any alloca.
    pub fn needs_probing(&self, _probe_interval: u64) -> bool {
        self.allocas.iter().any(|_a| {
            // Allocas larger than one probe interval need probing
            true // Dynamic size — always probe
        })
    }
}

// ============================================================================
// Callee-Saved Register Spill Management
// ============================================================================

/// Manages the callee-saved register spill area in the stack frame.
#[derive(Debug, Clone)]
pub struct CalleeSavedManager {
    /// Registers to spill, in order (first spilled is at highest offset).
    pub spill_regs: Vec<u16>,
    /// Offset of each spill from the frame pointer.
    pub spill_offsets: Vec<i64>,
    /// Total size of the spill area in bytes.
    pub total_spill_size: u64,
    /// Whether the area has been finalized.
    pub finalized: bool,
    /// Register size (8 for x86-64, 4 for x86-32).
    pub reg_size: u64,
}

impl CalleeSavedManager {
    /// Creates a new callee-saved spill manager.
    pub fn new(reg_size: u64) -> Self {
        CalleeSavedManager {
            spill_regs: Vec::new(),
            spill_offsets: Vec::new(),
            total_spill_size: 0,
            finalized: false,
            reg_size,
        }
    }

    /// Adds a register to the spill set.
    ///
    /// Returns the index of the spill slot.
    pub fn add_spill(&mut self, reg: u16) -> usize {
        let idx = self.spill_regs.len();
        self.spill_regs.push(reg);
        // Offset will be computed during finalization
        self.spill_offsets.push(0);
        idx
    }

    /// Finalizes the spill area, computing offsets for each register.
    ///
    /// The first spilled register is closest to the frame pointer (highest
    /// negative offset). Each subsequent spill is further from the frame
    /// pointer (more negative).
    ///
    /// Returns the total spill area size.
    pub fn finalize(&mut self) -> u64 {
        if self.finalized {
            return self.total_spill_size;
        }

        let mut offset: i64 = -8; // Start below saved RBP (or return address if no FP)

        for i in 0..self.spill_regs.len() {
            offset -= self.reg_size as i64;
            self.spill_offsets[i] = offset;
        }

        self.total_spill_size = self.spill_regs.len() as u64 * self.reg_size;
        self.finalized = true;
        self.total_spill_size
    }

    /// Returns the frame-pointer-relative offset for a spill slot.
    pub fn spill_offset(&self, index: usize) -> Option<i64> {
        self.spill_offsets.get(index).copied()
    }

    /// Returns the total number of spilled registers.
    pub fn count(&self) -> usize {
        self.spill_regs.len()
    }

    /// Emits the prologue spills (PUSH instructions).
    pub fn emit_prologue_spills(&self) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        // Spills are emitted in reverse order so that the first register
        // in the list is closest to the frame pointer
        for &reg in self.spill_regs.iter().rev() {
            instrs.push(MachineInstr::new_push(reg));
        }
        instrs
    }

    /// Emits the epilogue restores (POP instructions).
    pub fn emit_epilogue_restores(&self) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        for &reg in &self.spill_regs {
            instrs.push(MachineInstr::new_pop(reg));
        }
        instrs
    }
}

// ============================================================================
// Entry Probe Emission — Explicit probes for large static frames
// ============================================================================

/// Represents a sequence of explicit probes for a large static frame.
#[derive(Debug, Clone)]
pub struct EntryProbeSequence {
    /// The probe points (one per page).
    pub probe_points: Vec<ProbePoint>,
    /// The strategy used.
    pub strategy: ProbeStrategy,
    /// The generated machine instructions.
    pub instructions: Vec<MachineInstr>,
    /// Total bytes covered by the sequence.
    pub total_bytes_covered: u64,
}

impl X86StackProbing {
    /// Generates an entry probe sequence for a large static frame.
    ///
    /// Unlike the loop-based inline probe, explicit entry probes unroll the
    /// probing into a series of discrete SUB+TEST instructions. This is
    /// useful when the probe loop overhead would be significant, or when
    /// stack clash protection requires explicit probes at function entry.
    ///
    /// **Trade-off**: Explicit probes increase code size but avoid loop
    /// overhead and branch mispredictions in the prologue.
    ///
    /// # Arguments
    ///
    /// * `frame_size` — the fixed frame size to probe.
    /// * `max_unroll` — maximum number of unrolled probes (beyond this, use a loop).
    ///
    /// # Returns
    ///
    /// An `EntryProbeSequence` with the generated instructions.
    pub fn emit_explicit_entry_probe(
        &self,
        frame_size: u64,
        max_unroll: usize,
    ) -> EntryProbeSequence {
        let probe_points = self.compute_probe_points(frame_size);
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        if probe_points.len() <= max_unroll {
            // Unroll: emit a discrete probe for each page
            let mut _cumulative: i64 = 0;
            for _point in &probe_points {
                let page_size = self.probe_interval as i64;
                _cumulative -= page_size;
                // SUB RSP, page_size (can be LEA for non-destructive touch)
                instrs.push(MachineInstr::new_alu_imm(
                    if is_64bit {
                        X86Opcode::SUB64ri32 as u16
                    } else {
                        X86Opcode::SUB32ri as u16
                    },
                    VirtReg::phys(sp_reg),
                    VirtReg::phys(sp_reg),
                    -page_size,
                ));
                // TEST [RSP], RSP — touch the new page
                instrs.push(MachineInstr::new_mem_test(
                    VirtReg::phys(sp_reg),
                    0,
                    if is_64bit { 8 } else { 4 },
                ));
            }
        } else {
            // Loop: use a counter-based loop for many pages
            let counter_reg = VirtReg::new();
            let remaining = VirtReg::new();
            let probe_count = probe_points.len() as i64;

            // MOV counter, probe_count
            instrs.push(MachineInstr::new_mov_imm(counter_reg, probe_count));

            // MOV remaining, frame_size (negated for LEA indexing)
            instrs.push(MachineInstr::new_mov_imm(remaining, -(frame_size as i64)));

            // loop_start:
            //   LEA RSP, [RSP + remaining] — adjust (remaining is negative)
            //   ADD remaining, probe_interval
            //   TEST [RSP], RSP
            //   LEA RSP, [RSP - remaining] — restore? No, just keep adjusting
            //   DEC counter
            //   JNZ loop_start
            //
            // Actually, the correct loop structure:
            //   MOV RCX, probe_count
            //   MOV RAX, -probe_interval
            // .Lprobe_loop:
            //   LEA RSP, [RSP + RAX]       ; move SP down one page
            //   TEST [RSP], RSP             ; touch
            //   DEC RCX
            //   JNZ .Lprobe_loop
            //   ; RSP is now at final position

            let step_reg = VirtReg::new();
            instrs.push(MachineInstr::new_mov_imm(counter_reg, probe_count));
            instrs.push(MachineInstr::new_mov_imm(
                step_reg,
                -(self.probe_interval as i64),
            ));

            // Loop body
            instrs.push(MachineInstr::new_lea(
                VirtReg::phys(sp_reg),
                VirtReg::phys(sp_reg),
                step_reg,
                1,
                0,
            ));
            instrs.push(MachineInstr::new_mem_test(
                VirtReg::phys(sp_reg),
                0,
                if is_64bit { 8 } else { 4 },
            ));
            // DEC counter_reg
            instrs.push(MachineInstr::new_unary(
                X86Opcode::DEC64r as u16,
                counter_reg,
                counter_reg,
            ));
            // JNZ loop_start — implicit via branch instruction
        }

        self.inc_stat(|s| s.static_probes += probe_points.len() as u64);

        EntryProbeSequence {
            probe_points,
            strategy: ProbeStrategy::ExplicitProbe,
            instructions: instrs,
            total_bytes_covered: frame_size,
        }
    }

    /// Emits a simple probe for a stack protector canary setup.
    ///
    /// When a stack protector (-fstack-protector) is enabled, the canary
    /// sits between the locals and the saved return address. Probing ensures
    /// that the canary's page is touched before the canary is written.
    pub fn emit_canary_probe(&self) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };

        // The canary is typically at [RBP-8] or [RSP+offset].
        // We emit a touch at that location to ensure the page is present.
        // SUB RSP, canary_offset (if not already done)
        // TEST [RSP + canary_offset], RSP
        instrs.push(MachineInstr::new_mem_test(
            VirtReg::phys(sp_reg),
            0, // relative to current SP
            if is_64bit { 8 } else { 4 },
        ));

        instrs
    }
}

// ============================================================================
// Probing Loop Generation — Touch Each Page
// ============================================================================

/// Represents a probing loop: a counted loop that touches each page between
/// the current stack pointer and the target stack pointer.
#[derive(Debug, Clone)]
pub struct ProbingLoop {
    /// The register holding the loop counter (number of pages remaining).
    pub counter_reg: VirtReg,
    /// The register holding the page step (negative probe interval).
    pub step_reg: VirtReg,
    /// The loop instructions (without branch — caller adds the branch).
    pub body_instructions: Vec<MachineInstr>,
    /// The number of iterations (static count).
    pub iterations: u64,
    /// Whether the loop is for a static or dynamic allocation.
    pub is_dynamic: bool,
}

impl X86StackProbing {
    /// Generates a probing loop that touches pages from the current SP down
    /// to the final SP after allocation.
    ///
    /// The loop structure (x86-64):
    /// ```asm
    ///     mov  ecx, num_pages        ; loop counter
    ///     mov  eax, -4096            ; step (one page down)
    /// .Lprobe:
    ///     lea  rsp, [rsp + rax]      ; move SP down one page
    ///     test qword ptr [rsp], rsp  ; touch the page
    ///     dec  ecx
    ///     jnz  .Lprobe
    /// ```
    ///
    /// # Arguments
    ///
    /// * `num_pages` — the number of pages to probe (must be > 0).
    /// * `is_dynamic` — whether this loop is for a dynamic allocation.
    ///
    /// # Returns
    ///
    /// A `ProbingLoop` describing the generated instructions.
    pub fn generate_probing_loop(&self, num_pages: u64, is_dynamic: bool) -> ProbingLoop {
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };
        let mut body = Vec::new();

        let counter_reg = VirtReg::new();
        let step_reg = VirtReg::new();

        // MOV counter, num_pages
        body.push(MachineInstr::new_mov_imm(counter_reg, num_pages as i64));

        // MOV step, -probe_interval
        body.push(MachineInstr::new_mov_imm(
            step_reg,
            -(self.probe_interval as i64),
        ));

        // Loop body:
        //   LEA SP, [SP + step]  — move SP down
        //   TEST [SP], SP         — touch the page
        //   DEC counter
        //   JNZ loop_top

        body.push(MachineInstr::new_lea(
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            step_reg,
            1,
            0,
        ));
        body.push(MachineInstr::new_mem_test(
            VirtReg::phys(sp_reg),
            0,
            if is_64bit { 8 } else { 4 },
        ));
        body.push(MachineInstr::new_unary(
            if is_64bit {
                X86Opcode::DEC64r as u16
            } else {
                X86Opcode::DEC32r as u16
            },
            counter_reg,
            counter_reg,
        ));

        self.inc_stat(|s| {
            s.probe_loops += 1;
            s.total_bytes_probed += num_pages * self.probe_interval;
        });

        ProbingLoop {
            counter_reg,
            step_reg,
            body_instructions: body,
            iterations: num_pages,
            is_dynamic,
        }
    }

    /// Generates a probing loop for a dynamic allocation where the number
    /// of pages is not known at compile time.
    ///
    /// The loop terminates when the remaining size reaches zero.
    ///
    /// # Arguments
    ///
    /// * `size_reg` — register containing the allocation size.
    ///
    /// # Returns
    ///
    /// A `ProbingLoop` with dynamic termination.
    pub fn generate_dynamic_probing_loop(&self, size_reg: VirtReg) -> ProbingLoop {
        let is_64bit = self.calling_conv.is_64bit();
        let sp_reg = if is_64bit { RSP } else { ESP32_REG };
        let mut body = Vec::new();

        let remaining_reg = VirtReg::new();
        let step_reg = VirtReg::new();

        // MOV remaining, size_reg
        body.push(MachineInstr::new_copy(remaining_reg, size_reg));

        // MOV step, -probe_interval
        body.push(MachineInstr::new_mov_imm(
            step_reg,
            -(self.probe_interval as i64),
        ));

        // Loop body:
        //   CMP remaining, 0
        //   JLE loop_done
        //   LEA SP, [SP + step]   — move SP down
        //   TEST [SP], SP          — touch
        //   SUB remaining, probe_interval
        //   JMP loop_top

        // CMP remaining, 0
        body.push(MachineInstr::new_cmp_imm(remaining_reg, 0));
        // JLE done — conditional branch (emitted by caller)

        body.push(MachineInstr::new_lea(
            VirtReg::phys(sp_reg),
            VirtReg::phys(sp_reg),
            step_reg,
            1,
            0,
        ));
        body.push(MachineInstr::new_mem_test(
            VirtReg::phys(sp_reg),
            0,
            if is_64bit { 8 } else { 4 },
        ));
        body.push(MachineInstr::new_alu_imm(
            if is_64bit {
                X86Opcode::SUB64ri32 as u16
            } else {
                X86Opcode::SUB32ri as u16
            },
            remaining_reg,
            remaining_reg,
            self.probe_interval as i64,
        ));

        self.inc_stat(|s| s.probe_loops += 1);

        ProbingLoop {
            counter_reg: remaining_reg,
            step_reg,
            body_instructions: body,
            iterations: 0, // dynamic — not known
            is_dynamic: true,
        }
    }

    /// Generates a "touch page" instruction sequence.
    ///
    /// This emits either an `OR [target], 0` (safe, non-destructive write)
    /// or a `TEST [target], reg` (read-only, but triggers page fault if
    /// the page is not mapped).
    pub fn emit_touch_page(&self, target_reg: u16, offset: i32) -> MachineInstr {
        let is_64bit = self.calling_conv.is_64bit();
        MachineInstr::new_mem_test(
            VirtReg::phys(target_reg),
            offset as i64,
            if is_64bit { 8 } else { 4 },
        )
    }

    /// Returns whether a probing loop is preferred over unrolled probes.
    ///
    /// Unrolling produces larger code but avoids loop overhead. For small
    /// frames (<= 4 pages), unrolling is usually better.
    ///
    /// # Arguments
    ///
    /// * `num_pages` — number of pages to probe.
    /// * `opt_for_size` — whether to optimize for code size (-Os / -Oz).
    pub fn prefer_probe_loop(&self, num_pages: u64, opt_for_size: bool) -> bool {
        if opt_for_size {
            return num_pages > 1;
        }
        num_pages > 4
    }
}

// ============================================================================
// MachineInstr Extensions — Instructions used by stack probing
// ============================================================================

/// Extension trait providing stack-probing-specific instruction constructors
/// for `MachineInstr`. In a real codebase, `MachineInstr` would already have
/// many of these; this extension fills the gaps needed for stack probing.
pub trait StackProbeInstrExt {
    /// Creates a new ALU instruction with an immediate operand.
    fn new_alu_imm(opcode: u16, dst: VirtReg, src: VirtReg, imm: i64) -> MachineInstr;

    /// Creates a new ALU instruction with a register operand.
    fn new_alu_reg(opcode: u16, dst: VirtReg, src1: VirtReg, src2: VirtReg) -> MachineInstr;

    /// Creates a new unary instruction (NEG, DEC, INC, NOT).
    fn new_unary(opcode: u16, dst: VirtReg, src: VirtReg) -> MachineInstr;

    /// Creates a LEA instruction: dst = [base + index*scale + disp].
    fn new_lea(dst: VirtReg, base: VirtReg, index: VirtReg, scale: u8, disp: i32) -> MachineInstr;

    /// Creates a memory test instruction: CMP [base + offset], 0.
    fn new_mem_test(base: VirtReg, offset: i64, size: u64) -> MachineInstr;

    /// Creates a MOV immediate instruction.
    fn new_mov_imm(dst: VirtReg, imm: i64) -> MachineInstr;

    /// Creates a register-to-register copy (MOV).
    fn new_copy(dst: VirtReg, src: VirtReg) -> MachineInstr;

    /// Creates a PUSH instruction.
    fn new_push(reg: u16) -> MachineInstr;

    /// Creates a POP instruction.
    fn new_pop(reg: u16) -> MachineInstr;

    /// Creates a CALL instruction to a symbol.
    fn new_call(symbol: &str) -> MachineInstr;

    /// Creates a RET instruction.
    fn new_ret() -> MachineInstr;

    /// Creates a CMP with an immediate operand.
    fn new_cmp_imm(reg: VirtReg, imm: i64) -> MachineInstr;
}

// Note: In a real implementation, these would be `impl StackProbeInstrExt for MachineInstr`.
// For this module, we use free functions or assume MachineInstr has these constructors.
// The `MachineInstr::new_*` calls throughout this module reference these constructors.

// ============================================================================
// Stack Frame Dump — Debug visualization
// ============================================================================

impl X86StackProbing {
    /// Produces a detailed text dump of the stack frame layout for debugging.
    ///
    /// This is useful for understanding how the compiler has laid out the
    /// stack frame, which is critical for debugging stack-related issues
    /// (alignment, probing, realignment).
    pub fn dump_frame_layout(&self, layout: &StackFrameLayout) -> String {
        let mut out = String::new();
        out.push_str("=============== Stack Frame Dump ===============\n");
        out.push_str(&format!(
            "  Calling convention:  {:?}\n",
            layout.calling_conv
        ));
        out.push_str(&format!(
            "  Architecture:        {}\n",
            if layout.calling_conv.is_64bit() {
                "x86-64"
            } else {
                "x86-32"
            }
        ));
        out.push_str(&format!(
            "  Frame pointer:       {}\n",
            layout.has_frame_pointer
        ));
        if layout.has_dynamic_realignment {
            out.push_str(&format!(
                "  Realignment:         {} bytes\n",
                layout.realign_amount
            ));
            if let Some(drap) = layout.drap_register {
                out.push_str(&format!("  DRAP register:       r{}\n", drap));
            }
        }
        out.push_str("\n--- Fixed Frame Objects ---\n");
        for obj in &layout.fixed_objects {
            out.push_str(&format!(
                "  [id={}] {:?}: size={}, align={}, fp_offset={}, sp_offset={}\n",
                obj.id, obj.kind, obj.size, obj.alignment, obj.fp_offset, obj.sp_offset
            ));
        }
        out.push_str("\n--- Variable Frame Objects ---\n");
        for obj in &layout.variable_objects {
            out.push_str(&format!(
                "  [id={}] {:?}: size={}, align={}, fp_offset={}, sp_offset={}\n",
                obj.id, obj.kind, obj.size, obj.alignment, obj.fp_offset, obj.sp_offset
            ));
        }
        out.push_str("\n--- Callee-Saved Spills ---\n");
        for spill in &layout.callee_saved_spills {
            out.push_str(&format!(
                "  [id={}] reg=r{}: size={}, fp_offset={}\n",
                spill.id,
                spill.phys_reg.unwrap_or(0),
                spill.size,
                spill.fp_offset
            ));
        }
        out.push_str("\n--- Frame Summary ---\n");
        out.push_str(&format!(
            "  Fixed frame size:    {} bytes\n",
            layout.fixed_frame_size
        ));
        out.push_str(&format!(
            "  Outgoing arg size:   {} bytes\n",
            layout.outgoing_arg_size
        ));
        out.push_str(&format!(
            "  Shadow space:        {} bytes\n",
            layout.shadow_space_size
        ));
        out.push_str(&format!(
            "  Total frame size:    {} bytes\n",
            layout.total_frame_size
        ));
        out.push_str(&format!(
            "  Stack alignment:     {} bytes\n",
            layout.stack_alignment
        ));
        out.push_str("\n--- Probing ---\n");
        out.push_str(&format!(
            "  Static probe:        {}\n",
            if layout.requires_static_probe {
                "REQUIRED"
            } else {
                "not needed"
            }
        ));
        out.push_str(&format!(
            "  Dynamic probe:       {}\n",
            if layout.requires_dynamic_probe {
                "REQUIRED"
            } else {
                "not needed"
            }
        ));
        out.push_str(&format!(
            "  Probe interval:      {} bytes\n",
            layout.probe_interval
        ));
        out.push_str(&format!(
            "  Red zone:            {}\n",
            if layout.can_use_red_zone {
                "available"
            } else {
                "unavailable"
            }
        ));
        if let Some(canary_off) = layout.stack_protector_offset {
            out.push_str(&format!(
                "  Stack protector:     yes (offset={})\n",
                canary_off
            ));
        } else {
            out.push_str("  Stack protector:     none\n");
        }
        out.push_str("================================================\n");
        out
    }

    /// Produces an ASCII diagram of the stack frame.
    pub fn draw_frame_diagram(&self, layout: &StackFrameLayout) -> String {
        let mut out = String::new();
        let is_64bit = layout.calling_conv.is_64bit();
        let addr_size: i64 = if is_64bit { 8 } else { 4 };

        out.push_str("        Stack Frame Diagram\n");
        out.push_str("        ==================\n\n");
        out.push_str("        Higher addresses\n");
        out.push_str("        |\n");

        // Return address
        out.push_str(&format!(
            "   {:>+5} +--------------------------+ <- Return Address (CALL pushed)\n",
            layout.return_address_offset + addr_size
        ));

        if layout.has_frame_pointer {
            out.push_str(&format!(
                "   {:>+5} |   Previous %rbp          | <- Frame pointer\n",
                layout.return_address_offset
            ));
        }

        // Callee-saved regs
        let mut offset = layout.return_address_offset;
        for spill in &layout.callee_saved_spills {
            offset -= spill.size as i64;
            out.push_str(&format!(
                "   {:>+5} |   Saved r{:<3} ({:>4}B)   |\n",
                offset,
                spill.phys_reg.unwrap_or(0),
                spill.size
            ));
        }

        // Fixed locals
        for obj in &layout.fixed_objects {
            out.push_str(&format!(
                "   {:>+5} |   Local #{:<4} ({:>4}B)  |\n",
                obj.fp_offset, obj.id, obj.size
            ));
        }

        // Variable allocas
        if layout.has_variable_allocas {
            out.push_str("        |   ... (variable alloca)  |\n");
        }

        // Outgoing args
        if layout.outgoing_arg_size > 0 {
            out.push_str(&format!(
                "   {:>+5} |   Outgoing args ({:>4}B)  |\n",
                -(layout.fixed_frame_size as i64 + layout.outgoing_arg_size as i64),
                layout.outgoing_arg_size
            ));
        }

        // Shadow space
        if layout.shadow_space_size > 0 {
            out.push_str(&format!(
                "   {:>+5} |   Shadow space ({:>4}B)  |\n",
                -(layout.fixed_frame_size as i64
                    + layout.outgoing_arg_size as i64
                    + layout.shadow_space_size as i64),
                layout.shadow_space_size
            ));
        }

        out.push_str("        |\n");
        out.push_str("        v  Lower addresses\n");
        out.push_str(&format!("   %rsp  +--------------------------+\n"));

        if layout.can_use_red_zone {
            out.push_str(&format!(
                "   {:>+5}   [ Red Zone: {} bytes ]\n",
                -(RED_ZONE_SIZE_SYSV as i64),
                RED_ZONE_SIZE_SYSV
            ));
        }

        out
    }
}

// ============================================================================
// Frame Builder — Convenience API for constructing frame layouts
// ============================================================================

/// A builder for constructing `StackFrameLayout` objects incrementally.
#[derive(Debug, Clone)]
pub struct FrameBuilder {
    layout: StackFrameLayout,
}

impl FrameBuilder {
    /// Creates a new `FrameBuilder` for the given calling convention.
    pub fn new(cc: CallingConv) -> Self {
        FrameBuilder {
            layout: StackFrameLayout::new(cc),
        }
    }

    /// Sets whether a frame pointer is used.
    pub fn with_frame_pointer(mut self, use_fp: bool) -> Self {
        self.layout.has_frame_pointer = use_fp;
        self
    }

    /// Sets dynamic realignment.
    pub fn with_dynamic_realignment(mut self, align: u64) -> Self {
        self.layout.has_dynamic_realignment = true;
        self.layout.realign_amount = align;
        self.layout.stack_alignment = align.max(self.layout.stack_alignment);
        self
    }

    /// Adds a callee-saved register spill.
    pub fn add_callee_saved(mut self, reg: u16, size: u64) -> Self {
        let id = (self.layout.callee_saved_spills.len() + self.layout.fixed_objects.len()) as u32;
        let offset = -(self.layout.callee_saved_size() as i64 + size as i64);
        let spill = FrameObject::new_callee_saved(id, reg, size, offset, offset);
        self.layout.callee_saved_spills.push(spill);
        self
    }

    /// Adds a fixed-size local variable.
    pub fn add_fixed_local(mut self, size: u64, alignment: u64) -> Self {
        let id = (self.layout.callee_saved_spills.len() + self.layout.fixed_objects.len()) as u32;
        let current_size = self.layout.fixed_frame_size;
        let aligned = StackFrameLayout::align_offset(current_size, alignment);
        let obj = FrameObject::new_fixed(
            id,
            size,
            alignment,
            -(aligned as i64 + size as i64),
            -(aligned as i64 + size as i64),
        );
        self.layout.fixed_frame_size = aligned + size;
        self.layout.fixed_objects.push(obj);
        self
    }

    /// Adds a variable-size alloca.
    pub fn add_variable_alloca(mut self, size_reg: VirtReg, alignment: u64) -> Self {
        let id = (self.layout.callee_saved_spills.len()
            + self.layout.fixed_objects.len()
            + self.layout.variable_objects.len()) as u32;
        let obj = FrameObject::new_variable(id, 0, alignment, 0, 0, size_reg);
        self.layout.variable_objects.push(obj);
        self.layout.has_variable_allocas = true;
        self
    }

    /// Sets the outgoing argument area size.
    pub fn with_outgoing_args(mut self, size: u64) -> Self {
        self.layout.outgoing_arg_size = size;
        self
    }

    /// Sets the shadow space size (Win64).
    pub fn with_shadow_space(mut self, size: u64) -> Self {
        self.layout.shadow_space_size = size;
        self
    }

    /// Sets whether the red zone can be used.
    pub fn with_red_zone(mut self, can_use: bool) -> Self {
        self.layout.can_use_red_zone = can_use;
        self
    }

    /// Sets the probe interval.
    pub fn with_probe_interval(mut self, interval: u64) -> Self {
        self.layout.probe_interval = interval;
        self
    }

    /// Sets the DRAP register.
    pub fn with_drap(mut self, reg: u16) -> Self {
        self.layout.drap_register = Some(reg);
        self
    }

    /// Finalizes the frame layout and computes derived fields.
    pub fn build(mut self) -> StackFrameLayout {
        let total_fixed = self.layout.fixed_frame_size
            + self.layout.callee_saved_size()
            + self.layout.outgoing_arg_size
            + self.layout.shadow_space_size;
        self.layout.total_frame_size =
            StackFrameLayout::align_offset(total_fixed, self.layout.stack_alignment);
        self.layout
    }
}

// ============================================================================
// ABISpecific — ABI-specific stack probing rules
// ============================================================================

/// ABI-specific rules for stack probing and frame layout.
#[derive(Debug, Clone)]
pub struct ABISpecific {
    /// The calling convention.
    pub cc: CallingConv,
    /// Whether this ABI requires stack probing for frames > one page.
    pub requires_probe_large_frame: bool,
    /// The default probe strategy for this ABI.
    pub default_probe_strategy: ProbeStrategy,
    /// Whether the red zone exists for this ABI.
    pub has_red_zone: bool,
    /// Whether shadow space exists.
    pub has_shadow_space: bool,
    /// Shadow space size (if applicable).
    pub shadow_space_size: u64,
    /// Red zone size (if applicable).
    pub red_zone_size: u64,
    /// Stack alignment requirement.
    pub stack_alignment: u64,
    /// Whether dynamic realignment is supported.
    pub supports_realignment: bool,
    /// Whether CSR spills must happen before local allocation.
    pub spills_before_locals: bool,
}

impl ABISpecific {
    /// Returns the ABI-specific rules for a given calling convention.
    pub fn for_calling_conv(cc: CallingConv) -> Self {
        match cc {
            CallingConv::SystemV => ABISpecific {
                cc,
                requires_probe_large_frame: false,
                default_probe_strategy: ProbeStrategy::Inline,
                has_red_zone: true,
                has_shadow_space: false,
                shadow_space_size: 0,
                red_zone_size: RED_ZONE_SIZE_SYSV,
                stack_alignment: STACK_ALIGNMENT_SYSV,
                supports_realignment: true,
                spills_before_locals: true,
            },
            CallingConv::Win64 => ABISpecific {
                cc,
                requires_probe_large_frame: true,
                default_probe_strategy: ProbeStrategy::ChkStk,
                has_red_zone: false,
                has_shadow_space: true,
                shadow_space_size: SHADOW_SPACE_WIN64,
                red_zone_size: 0,
                stack_alignment: STACK_ALIGNMENT_WIN64,
                supports_realignment: false, // Win64 generally doesn't realign
                spills_before_locals: true,
            },
            CallingConv::Cdecl32 => ABISpecific {
                cc,
                requires_probe_large_frame: false,
                default_probe_strategy: ProbeStrategy::None,
                has_red_zone: false,
                has_shadow_space: false,
                shadow_space_size: 0,
                red_zone_size: 0,
                stack_alignment: 16,
                supports_realignment: true,
                spills_before_locals: true,
            },
            CallingConv::Stdcall32 => ABISpecific {
                cc,
                requires_probe_large_frame: true,
                default_probe_strategy: ProbeStrategy::ChkStk,
                has_red_zone: false,
                has_shadow_space: false,
                shadow_space_size: 0,
                red_zone_size: 0,
                stack_alignment: 16,
                supports_realignment: false,
                spills_before_locals: true,
            },
            CallingConv::Fastcall32 => ABISpecific {
                cc,
                requires_probe_large_frame: false,
                default_probe_strategy: ProbeStrategy::None,
                has_red_zone: false,
                has_shadow_space: false,
                shadow_space_size: 0,
                red_zone_size: 0,
                stack_alignment: 16,
                supports_realignment: false,
                spills_before_locals: true,
            },
        }
    }

    /// Returns `true` if probing is recommended for a frame of the given size.
    pub fn should_probe_frame(&self, frame_size: u64, probe_interval: u64) -> bool {
        if !self.requires_probe_large_frame {
            return false;
        }
        frame_size > probe_interval
    }

    /// Returns the recommended probe strategy.
    pub fn recommended_strategy(&self) -> ProbeStrategy {
        self.default_probe_strategy
    }
}

// ============================================================================
// Polyfills / Thin Wrappers — MachineInstr constructor helpers
// ============================================================================

/// Thin-wrapper around `MachineInstr` for stack probing.
///
/// In the actual codebase, `MachineInstr` would be a fully-featured type with
/// many constructors. This module uses these polyfills so it compiles
/// independently and demonstrates the complete algorithm.
///
/// Replace these with the real `MachineInstr` constructors when integrating.
impl MachineInstr {
    /// Creates a dummy MachineInstr for ALU with immediate.
    pub fn new_alu_imm(_opcode: u16, _dst: VirtReg, _src: VirtReg, _imm: i64) -> MachineInstr {
        MachineInstr::placeholder("alu_imm")
    }

    /// Creates a dummy MachineInstr for ALU with register.
    pub fn new_alu_reg(
        _opcode: u16,
        _dst: VirtReg,
        _src1: VirtReg,
        _src2: VirtReg,
    ) -> MachineInstr {
        MachineInstr::placeholder("alu_reg")
    }

    /// Creates a dummy MachineInstr for unary ops.
    pub fn new_unary(_opcode: u16, _dst: VirtReg, _src: VirtReg) -> MachineInstr {
        MachineInstr::placeholder("unary")
    }

    /// Creates a dummy MachineInstr for LEA.
    pub fn new_lea(
        _dst: VirtReg,
        _base: VirtReg,
        _index: VirtReg,
        _scale: u8,
        _disp: i32,
    ) -> MachineInstr {
        MachineInstr::placeholder("lea")
    }

    /// Creates a dummy MachineInstr for memory test.
    pub fn new_mem_test(_base: VirtReg, _offset: i64, _size: u64) -> MachineInstr {
        MachineInstr::placeholder("mem_test")
    }

    /// Creates a dummy MachineInstr for MOV imm.
    pub fn new_mov_imm(_dst: VirtReg, _imm: i64) -> MachineInstr {
        MachineInstr::placeholder("mov_imm")
    }

    /// Creates a dummy MachineInstr for register copy.
    pub fn new_copy(_dst: VirtReg, _src: VirtReg) -> MachineInstr {
        MachineInstr::placeholder("copy")
    }

    /// Creates a dummy MachineInstr for PUSH.
    pub fn new_push(_reg: u16) -> MachineInstr {
        MachineInstr::placeholder("push")
    }

    /// Creates a dummy MachineInstr for POP.
    pub fn new_pop(_reg: u16) -> MachineInstr {
        MachineInstr::placeholder("pop")
    }

    /// Creates a dummy MachineInstr for CALL.
    pub fn new_call(_symbol: &str) -> MachineInstr {
        MachineInstr::placeholder("call")
    }

    /// Creates a dummy MachineInstr for RET.
    pub fn new_ret() -> MachineInstr {
        MachineInstr::placeholder("ret")
    }

    /// Creates a dummy MachineInstr for CMP immediate.
    pub fn new_cmp_imm(_reg: VirtReg, _imm: i64) -> MachineInstr {
        MachineInstr::placeholder("cmp_imm")
    }

    /// Creates a placeholder `MachineInstr` for testing/prototyping.
    ///
    /// In a real backend, replace this with the actual instruction builder.
    pub fn placeholder(kind: &str) -> MachineInstr {
        // This is a polyfill to allow compilation. In the real codebase,
        // MachineInstr would be fully implemented with actual lowering.
        // For testing purposes, we use a dummy that tracks the kind name.
        MachineInstr {
            opcode: 0,
            operands: vec![MachineOperand::Symbol(kind.to_string())],
            ..Default::default()
        }
    }
}

// ============================================================================
// Placeholder Types — VirtReg, MachineOperand, MachineInstr stubs
// ============================================================================

/// A virtual register placeholder, used for compilation and testing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct VirtReg {
    pub id: u32,
    pub is_phys: bool,
    pub phys_id: u16,
}

impl VirtReg {
    /// Creates a new virtual register.
    pub fn new() -> Self {
        use std::sync::atomic::AtomicU32;
        static NEXT_ID: AtomicU32 = AtomicU32::new(1000);
        VirtReg {
            id: NEXT_ID.fetch_add(1, Ordering::Relaxed),
            is_phys: false,
            phys_id: 0,
        }
    }

    /// Creates a virtual register representing a physical register.
    pub fn phys(reg_id: u16) -> Self {
        VirtReg {
            id: reg_id as u32,
            is_phys: true,
            phys_id: reg_id,
        }
    }
}

/// A placeholder `MachineOperand`.
#[derive(Debug, Clone)]
pub enum MachineOperand {
    /// A register operand.
    Reg(VirtReg),
    /// An immediate operand.
    Imm(i64),
    /// A symbol name operand.
    Symbol(String),
    /// A memory operand: [base + index*scale + disp].
    Mem {
        base: VirtReg,
        index: VirtReg,
        scale: u8,
        disp: i32,
    },
}

impl Default for MachineOperand {
    fn default() -> Self {
        MachineOperand::Imm(0)
    }
}

/// A placeholder `MachineInstr` for compilation.
#[derive(Debug, Clone, Default)]
pub struct MachineInstr {
    pub opcode: u16,
    pub operands: Vec<MachineOperand>,
}

// ============================================================================
// Placeholder types extended (re-exported for use in this module)
// ============================================================================

/// Placeholder for `MachineBasicBlock`.
#[derive(Debug, Clone, Default)]
pub struct MachineBasicBlock {
    pub instructions: Vec<MachineInstr>,
    pub label: Option<String>,
}

/// Placeholder for `MachineFunction`.
#[derive(Debug, Clone, Default)]
pub struct MachineFunction {
    pub name: String,
    pub blocks: Vec<MachineBasicBlock>,
}

/// Re-export opcode constants used in this module.
#[allow(non_upper_case_globals)]
pub mod x86_opcodes {
    /// X86 opcode enumeration — subset used by stack probing.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    #[repr(u16)]
    pub enum X86Opcode {
        ADD64ri8 = 1,
        ADD64ri32 = 2,
        ADD32ri = 3,
        ADD32ri8 = 4,
        SUB64ri32 = 5,
        SUB64rr = 6,
        SUB32ri = 7,
        SUB32rr = 8,
        AND64ri8 = 9,
        AND64ri32 = 10,
        AND32ri = 11,
        AND32ri8 = 33,
        NEG64r = 12,
        DEC64r = 13,
        DEC32r = 14,
        MOV64ri = 15,
        MOV32ri = 16,
        MOV64rr = 17,
        MOV32rr = 18,
        PUSH64r = 19,
        POP64r = 20,
        PUSH32r = 21,
        POP32r = 22,
        CALL = 23,
        RET = 24,
        LEA64r = 25,
        TEST64mr = 26,
        TEST32mr = 27,
        CMP64ri = 28,
        CMP32ri = 29,
        JNE = 30,
        JNZ = 31,
        JLE = 32,
    }
}

// ============================================================================
// Tests
// ============================================================================

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

    // --- Test Helpers ---

    fn make_linux_prober() -> X86StackProbing {
        X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV)
    }

    fn make_windows_prober() -> X86StackProbing {
        X86StackProbing::new(TargetOS::Windows, CallingConv::Win64)
    }

    fn make_basic_frame_info() -> FrameInfo {
        FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: true,
            callee_saved_regs: vec![RBX_REG, R12_REG, R13_REG],
            reg_size: 8,
            fixed_locals: vec![(16, 8), (32, 16), (8, 8)],
            num_variable_allocas: 0,
            outgoing_arg_size: 32,
            is_leaf: false,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        }
    }

    // =========================================================================
    // X86StackProbing — construction & configuration
    // =========================================================================

    #[test]
    fn test_new_linux_prober_defaults() {
        let prober = make_linux_prober();
        assert_eq!(prober.target_os, TargetOS::Linux);
        assert_eq!(prober.calling_conv, CallingConv::SystemV);
        assert_eq!(prober.probe_strategy, ProbeStrategy::Inline);
        assert_eq!(prober.probe_interval, DEFAULT_PROBE_INTERVAL);
        assert!(!prober.stack_clash_protection);
        assert!(prober.emit_red_zone);
    }

    #[test]
    fn test_new_windows_prober_defaults() {
        let prober = make_windows_prober();
        assert_eq!(prober.target_os, TargetOS::Windows);
        assert_eq!(prober.calling_conv, CallingConv::Win64);
        assert_eq!(prober.probe_strategy, ProbeStrategy::ChkStk);
        assert!(!prober.emit_red_zone);
    }

    #[test]
    fn test_set_probe_strategy() {
        let mut prober = make_linux_prober();
        prober.set_probe_strategy(ProbeStrategy::ExplicitProbe);
        assert_eq!(prober.probe_strategy, ProbeStrategy::ExplicitProbe);
    }

    #[test]
    fn test_set_stack_clash_protection() {
        let mut prober = make_linux_prober();
        assert!(!prober.stack_clash_protection);
        prober.set_stack_clash_protection(true);
        assert!(prober.stack_clash_protection);
    }

    #[test]
    fn test_set_probe_interval() {
        let mut prober = make_linux_prober();
        prober.set_probe_interval(8192);
        assert_eq!(prober.probe_interval, 8192);
    }

    #[test]
    fn test_probe_interval_clamping() {
        let mut prober = make_linux_prober();
        // Below minimum — should clamp to MIN_PROBE_INTERVAL
        prober.set_probe_interval(512);
        assert_eq!(prober.probe_interval, MIN_PROBE_INTERVAL);
        // Above maximum — should clamp to MAX_PROBE_INTERVAL
        prober.set_probe_interval(200000);
        assert_eq!(prober.probe_interval, MAX_PROBE_INTERVAL);
    }

    #[test]
    fn test_enable_dynamic_realignment() {
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align64);
        assert!(prober.realign_enabled);
        assert_eq!(prober.realign_alignment, RealignAlignment::Align64);
    }

    #[test]
    fn test_disable_dynamic_realignment() {
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align32);
        prober.disable_dynamic_realignment();
        assert!(!prober.realign_enabled);
        assert_eq!(prober.realign_alignment, RealignAlignment::None);
    }

    // =========================================================================
    // Probe strategy selection
    // =========================================================================

    #[test]
    fn test_default_strategy_linux() {
        assert_eq!(
            ProbeStrategy::Inline,
            X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV).probe_strategy
        );
    }

    #[test]
    fn test_default_strategy_windows() {
        assert_eq!(
            ProbeStrategy::ChkStk,
            X86StackProbing::new(TargetOS::Windows, CallingConv::Win64).probe_strategy
        );
    }

    #[test]
    fn test_default_strategy_macos() {
        assert_eq!(
            ProbeStrategy::Inline,
            X86StackProbing::new(TargetOS::MacOS, CallingConv::SystemV).probe_strategy
        );
    }

    #[test]
    fn test_default_strategy_unknown() {
        assert_eq!(
            ProbeStrategy::None,
            X86StackProbing::new(TargetOS::Unknown, CallingConv::SystemV).probe_strategy
        );
    }

    // =========================================================================
    // Probe count computation
    // =========================================================================

    #[test]
    fn test_probe_count_zero_size() {
        let prober = make_linux_prober();
        assert_eq!(prober.probe_count_for_size(0), 0);
    }

    #[test]
    fn test_probe_count_one_page() {
        let prober = make_linux_prober();
        assert_eq!(prober.probe_count_for_size(4096), 1);
    }

    #[test]
    fn test_probe_count_multiple_pages() {
        let prober = make_linux_prober();
        assert_eq!(prober.probe_count_for_size(8192), 2);
        assert_eq!(prober.probe_count_for_size(12288), 3);
        assert_eq!(prober.probe_count_for_size(16384), 4);
    }

    #[test]
    fn test_probe_count_partial_page() {
        let prober = make_linux_prober();
        // Even 1 byte beyond a page boundary requires another probe
        assert_eq!(prober.probe_count_for_size(4097), 2);
        assert_eq!(prober.probe_count_for_size(1), 1);
    }

    // =========================================================================
    // Probe requirement decisions
    // =========================================================================

    #[test]
    fn test_requires_static_probe_small_frame() {
        let prober = make_linux_prober();
        // Without stack clash, small frames don't need probes on Linux
        assert!(!prober.requires_static_probe(2048));
    }

    #[test]
    fn test_requires_static_probe_clash_large_frame() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        assert!(prober.requires_static_probe(8192));
    }

    #[test]
    fn test_requires_static_probe_clash_small_frame() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        assert!(!prober.requires_static_probe(2048));
    }

    #[test]
    fn test_requires_static_probe_windows() {
        let prober = make_windows_prober();
        // On Windows, frames > one page are always probed
        assert!(prober.requires_static_probe(8192));
        assert!(!prober.requires_static_probe(2048));
    }

    #[test]
    fn test_requires_static_probe_disabled() {
        let mut prober = make_windows_prober();
        prober.set_probe_static_frame(false);
        assert!(!prober.requires_static_probe(8192));
    }

    #[test]
    fn test_requires_dynamic_probe() {
        let prober = make_linux_prober();
        assert!(prober.requires_dynamic_probe(8192));
    }

    #[test]
    fn test_requires_dynamic_probe_small() {
        let prober = make_linux_prober();
        assert!(!prober.requires_dynamic_probe(1024));
    }

    // =========================================================================
    // Probe points
    // =========================================================================

    #[test]
    fn test_compute_probe_points_single_page() {
        let prober = make_linux_prober();
        let points = prober.compute_probe_points(4096);
        assert_eq!(points.len(), 1);
        assert_eq!(points[0].address_offset, -4096);
        assert_eq!(points[0].page_index, 0);
    }

    #[test]
    fn test_compute_probe_points_multiple_pages() {
        let prober = make_linux_prober();
        let points = prober.compute_probe_points(16384);
        assert_eq!(points.len(), 4);
        assert_eq!(points[0].address_offset, -4096);
        assert_eq!(points[1].address_offset, -8192);
        assert_eq!(points[2].address_offset, -12288);
        assert_eq!(points[3].address_offset, -16384);
    }

    #[test]
    fn test_compute_probe_points_zero() {
        let prober = make_linux_prober();
        let points = prober.compute_probe_points(0);
        assert!(points.is_empty());
    }

    // =========================================================================
    // Stack clash severity
    // =========================================================================

    #[test]
    fn test_clash_severity_none() {
        let prober = make_linux_prober();
        let layout = StackFrameLayout::new(CallingConv::SystemV);
        assert_eq!(prober.assess_clash_severity(&layout), ClashSeverity::None);
    }

    #[test]
    fn test_clash_severity_low() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.total_frame_size = MAX_FRAME_SIZE_WITHOUT_PROBE * 2;
        assert_eq!(prober.assess_clash_severity(&layout), ClashSeverity::Low);
    }

    #[test]
    fn test_clash_severity_medium() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.total_frame_size = 16384;
        assert_eq!(prober.assess_clash_severity(&layout), ClashSeverity::Medium);
    }

    #[test]
    fn test_clash_severity_high_variable_no_probe() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        prober.set_probe_dynamic_alloca(false);
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.has_variable_allocas = true;
        assert_eq!(prober.assess_clash_severity(&layout), ClashSeverity::High);
    }

    #[test]
    fn test_clash_severity_critical() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.total_frame_size = 131072; // 128 KiB
        assert_eq!(
            prober.assess_clash_severity(&layout),
            ClashSeverity::Critical
        );
    }

    // =========================================================================
    // Dynamic stack allocation — alloca lowering
    // =========================================================================

    #[test]
    fn test_lower_alloca_basic() {
        let prober = make_linux_prober();
        let size_reg = VirtReg::new();
        let result_reg = VirtReg::new();
        let config = AllocaConfig {
            size_reg,
            result_reg,
            alignment: 16,
            in_entry_block: true,
            probe: false,
            use_save_restore: false,
        };
        let result = prober.lower_alloca(&config);
        // Should produce alignment + SUB instructions
        assert!(!result.instructions.is_empty());
        assert!(!result.probed);
    }

    #[test]
    fn test_lower_alloca_with_probe() {
        let mut prober = make_linux_prober();
        prober.set_probe_dynamic_alloca(true);
        let size_reg = VirtReg::new();
        let result_reg = VirtReg::new();
        let config = AllocaConfig {
            size_reg,
            result_reg,
            alignment: 16,
            in_entry_block: true,
            probe: true,
            use_save_restore: false,
        };
        let result = prober.lower_alloca(&config);
        assert!(!result.instructions.is_empty());
        // Dynamic probe should be emitted
        assert!(result.probed);
    }

    #[test]
    fn test_lower_alloca_with_save_restore() {
        let prober = make_linux_prober();
        let size_reg = VirtReg::new();
        let result_reg = VirtReg::new();
        let config = AllocaConfig {
            size_reg,
            result_reg,
            alignment: 8,
            in_entry_block: false,
            probe: false,
            use_save_restore: true,
        };
        let result = prober.lower_alloca(&config);
        assert!(!result.instructions.is_empty());
        // Should save old SP for stackrestore
    }

    // =========================================================================
    // Dynamic stack allocation — DYNAMIC_STACKALLOC lowering
    // =========================================================================

    #[test]
    fn test_lower_dynamic_stack_alloc_basic() {
        let prober = make_linux_prober();
        let ctx = DynamicStackAllocContext {
            size_reg: VirtReg::new(),
            alignment: 16,
            is_arg_copy: false,
            probe: false,
        };
        let result = prober.lower_dynamic_stack_alloc(&ctx);
        assert!(!result.instructions.is_empty());
        assert!(!result.probed);
    }

    #[test]
    fn test_lower_dynamic_stack_alloc_with_probe() {
        let mut prober = make_linux_prober();
        prober.set_probe_dynamic_alloca(true);
        let ctx = DynamicStackAllocContext {
            size_reg: VirtReg::new(),
            alignment: 32,
            is_arg_copy: false,
            probe: true,
        };
        let result = prober.lower_dynamic_stack_alloc(&ctx);
        assert!(!result.instructions.is_empty());
        assert!(result.probed);
    }

    #[test]
    fn test_lower_dynamic_stack_alloc_arg_copy() {
        let prober = make_linux_prober();
        let ctx = DynamicStackAllocContext {
            size_reg: VirtReg::new(),
            alignment: 8,
            is_arg_copy: true,
            probe: false,
        };
        let result = prober.lower_dynamic_stack_alloc(&ctx);
        assert!(!result.instructions.is_empty());
    }

    // =========================================================================
    // Stack probing — static probe emission
    // =========================================================================

    #[test]
    fn test_emit_static_probe_inline() {
        let prober = make_linux_prober();
        let result = prober.emit_static_probe(16384);
        assert!(!result.instructions.is_empty());
        assert!(!result.is_runtime_call);
        assert!(result.probes_emitted > 0);
    }

    #[test]
    fn test_emit_static_probe_chkstk() {
        let prober = make_windows_prober();
        let result = prober.emit_static_probe(16384);
        assert!(!result.instructions.is_empty());
        assert!(result.is_runtime_call);
    }

    #[test]
    fn test_emit_static_probe_zero() {
        let prober = make_linux_prober();
        let result = prober.emit_static_probe(0);
        assert!(result.instructions.is_empty());
        assert_eq!(result.probes_emitted, 0);
    }

    #[test]
    fn test_emit_static_probe_none_strategy() {
        let mut prober = make_linux_prober();
        prober.set_probe_strategy(ProbeStrategy::None);
        let result = prober.emit_static_probe(8192);
        assert!(result.instructions.is_empty());
    }

    // =========================================================================
    // Dynamic probing
    // =========================================================================

    #[test]
    fn test_emit_dynamic_probe_inline() {
        let prober = make_linux_prober();
        let result = prober.emit_dynamic_probe(VirtReg::new(), 16);
        assert!(!result.instructions.is_empty());
        assert!(!result.is_runtime_call);
    }

    #[test]
    fn test_emit_dynamic_probe_chkstk() {
        let prober = make_windows_prober();
        let result = prober.emit_dynamic_probe(VirtReg::new(), 16);
        assert!(!result.instructions.is_empty());
        assert!(result.is_runtime_call);
    }

    // =========================================================================
    // Gap probing
    // =========================================================================

    #[test]
    fn test_emit_gap_probe_small() {
        let prober = make_linux_prober();
        let result = prober.emit_gap_probe(2048);
        assert!(result.instructions.is_empty()); // Too small for a page
    }

    #[test]
    fn test_emit_gap_probe_large() {
        let prober = make_linux_prober();
        let result = prober.emit_gap_probe(16384);
        assert!(!result.instructions.is_empty());
    }

    // =========================================================================
    // Prologue probing
    // =========================================================================

    #[test]
    fn test_emit_prologue_probe_not_needed() {
        let prober = make_linux_prober();
        let layout = StackFrameLayout::new(CallingConv::SystemV);
        let result = prober.emit_prologue_probe(&layout);
        assert!(result.instructions.is_empty());
    }

    #[test]
    fn test_emit_prologue_probe_needed() {
        let mut prober = make_windows_prober();
        prober.set_stack_clash_protection(true);
        let mut layout = StackFrameLayout::new(CallingConv::Win64);
        layout.fixed_frame_size = 32768;
        layout.requires_static_probe = true;
        let result = prober.emit_prologue_probe(&layout);
        assert!(!result.instructions.is_empty());
    }

    // =========================================================================
    // Probing loop generation
    // =========================================================================

    #[test]
    fn test_generate_probing_loop_static() {
        let prober = make_linux_prober();
        let loop_info = prober.generate_probing_loop(8, false);
        assert!(!loop_info.body_instructions.is_empty());
        assert_eq!(loop_info.iterations, 8);
        assert!(!loop_info.is_dynamic);
    }

    #[test]
    fn test_generate_dynamic_probing_loop() {
        let prober = make_linux_prober();
        let size_reg = VirtReg::new();
        let loop_info = prober.generate_dynamic_probing_loop(size_reg);
        assert!(!loop_info.body_instructions.is_empty());
        assert!(loop_info.is_dynamic);
    }

    #[test]
    fn test_prefer_probe_loop_small() {
        let prober = make_linux_prober();
        // Few pages, optimizing for speed → prefer unrolled
        assert!(!prober.prefer_probe_loop(2, false));
    }

    #[test]
    fn test_prefer_probe_loop_large() {
        let prober = make_linux_prober();
        // Many pages → prefer loop
        assert!(prober.prefer_probe_loop(10, false));
    }

    #[test]
    fn test_prefer_probe_loop_opt_for_size() {
        let prober = make_linux_prober();
        // Optimizing for size → always prefer loop for >1 page
        assert!(prober.prefer_probe_loop(2, true));
        assert!(!prober.prefer_probe_loop(1, true));
    }

    // =========================================================================
    // Explicit entry probe
    // =========================================================================

    #[test]
    fn test_explicit_entry_probe_unrolled() {
        let prober = make_linux_prober();
        let seq = prober.emit_explicit_entry_probe(16384, 10);
        assert!(!seq.instructions.is_empty());
        assert_eq!(seq.strategy, ProbeStrategy::ExplicitProbe);
        assert_eq!(seq.total_bytes_covered, 16384);
    }

    #[test]
    fn test_explicit_entry_probe_loop_fallback() {
        let prober = make_linux_prober();
        // 100 pages but only 5 max unroll → should use loop
        let seq = prober.emit_explicit_entry_probe(409600, 5);
        assert!(!seq.instructions.is_empty());
    }

    // =========================================================================
    // Dynamic stack realignment
    // =========================================================================

    #[test]
    fn test_emit_dynamic_realignment_none() {
        let prober = make_linux_prober();
        let result = prober.emit_dynamic_realignment(RealignAlignment::None, true, true);
        assert!(result.instructions.is_empty());
        assert!(!result.used_drap);
    }

    #[test]
    fn test_emit_dynamic_realignment_align64() {
        let prober = make_linux_prober();
        let result = prober.emit_dynamic_realignment(RealignAlignment::Align64, true, true);
        assert!(!result.instructions.is_empty());
        assert_eq!(result.alignment, 64);
    }

    #[test]
    fn test_emit_dynamic_realignment_with_drap() {
        let mut prober = make_linux_prober();
        prober.set_drap_register(DRAP_REGISTER_X64);
        prober.set_uses_frame_pointer(true);
        let result = prober.emit_dynamic_realignment(
            RealignAlignment::Align64,
            true,
            false, // base reg not available → need DRAP
        );
        assert!(!result.instructions.is_empty());
        assert!(result.used_drap);
        assert_eq!(result.drap_register, Some(DRAP_REGISTER_X64));
    }

    #[test]
    fn test_should_realign() {
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align32);
        assert!(prober.should_realign(true));
        assert!(!prober.should_realign(false));
    }

    #[test]
    fn test_should_realign_disabled() {
        let prober = make_linux_prober();
        assert!(!prober.should_realign(true));
    }

    #[test]
    fn test_needs_drap() {
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align32);
        // Base reg not available, has allocas, DRAP available
        assert!(prober.needs_drap(false, true));
        // Base reg available → no DRAP needed
        assert!(!prober.needs_drap(true, true));
        // No allocas → no DRAP needed
        assert!(!prober.needs_drap(false, false));
    }

    // =========================================================================
    // Stack clash protection
    // =========================================================================

    #[test]
    fn test_apply_stack_clash_protection_disabled() {
        let prober = make_linux_prober();
        let layout = StackFrameLayout::new(CallingConv::SystemV);
        let result = prober.apply_stack_clash_protection(&layout);
        assert!(!result.protected);
        assert_eq!(result.entry_probes, 0);
    }

    #[test]
    fn test_apply_stack_clash_protection_enabled() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.fixed_frame_size = 32768;
        let result = prober.apply_stack_clash_protection(&layout);
        assert!(result.protected);
        assert!(result.entry_probes > 0);
    }

    #[test]
    fn test_configure_stack_clash() {
        let mut prober = make_linux_prober();
        prober.configure_stack_clash(true, Some(8192));
        assert!(prober.stack_clash_protection);
        assert_eq!(prober.probe_interval, 8192);
    }

    #[test]
    fn test_needs_gap_probe() {
        let mut prober = make_linux_prober();
        prober.set_stack_clash_protection(true);
        assert!(prober.needs_gap_probe(8192));
        assert!(!prober.needs_gap_probe(2048));
    }

    #[test]
    fn test_probe_threshold() {
        let prober = make_linux_prober();
        assert_eq!(prober.probe_threshold(), u64::MAX); // No clash → never probe
        let mut prober2 = make_linux_prober();
        prober2.set_stack_clash_protection(true);
        assert_eq!(prober2.probe_threshold(), MAX_FRAME_SIZE_WITHOUT_PROBE);
    }

    // =========================================================================
    // Frame layout computation
    // =========================================================================

    #[test]
    fn test_compute_frame_layout_basic() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        assert!(layout.has_frame_pointer);
        assert!(!layout.has_variable_allocas);
        assert_eq!(layout.callee_saved_spills.len(), 3);
        assert_eq!(layout.fixed_objects.len(), 3);
        assert!(layout.fixed_frame_size > 0);
    }

    #[test]
    fn test_compute_frame_layout_leaf() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.is_leaf = true;
        let layout = prober.compute_frame_layout(&info);
        assert!(layout.can_use_red_zone);
    }

    #[test]
    fn test_compute_frame_layout_win64() {
        let prober = make_windows_prober();
        let mut info = make_basic_frame_info();
        info.calling_conv = CallingConv::Win64;
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.shadow_space_size, SHADOW_SPACE_WIN64);
        assert!(!layout.can_use_red_zone);
    }

    #[test]
    fn test_compute_frame_layout_with_realignment() {
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align64);
        let mut info = make_basic_frame_info();
        info.needs_realignment = true;
        info.realign_amount = 64;
        let layout = prober.compute_frame_layout(&info);
        assert!(layout.has_dynamic_realignment);
        assert_eq!(layout.realign_amount, 64);
        assert_eq!(layout.drap_register, Some(DRAP_REGISTER_X64));
    }

    #[test]
    fn test_compute_leaf_frame_layout() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.is_leaf = true;
        // Make frame small enough to fit in red zone
        info.fixed_locals = vec![(16, 8)];
        info.callee_saved_regs = vec![];
        let layout = prober.compute_leaf_frame_layout(&info);
        assert!(layout.can_use_red_zone);
    }

    #[test]
    fn test_compute_win64_frame_layout() {
        let prober = make_windows_prober();
        let mut info = make_basic_frame_info();
        info.calling_conv = CallingConv::Win64;
        let layout = prober.compute_win64_frame_layout(&info);
        assert!(layout.total_frame_size % STACK_ALIGNMENT_WIN64 == 0);
    }

    // =========================================================================
    // Frame layout validation
    // =========================================================================

    #[test]
    fn test_validate_frame_layout_valid() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let errors = prober.validate_frame_layout(&layout);
        assert!(errors.is_empty(), "Unexpected errors: {:?}", errors);
    }

    #[test]
    fn test_validate_frame_layout_red_zone_mismatch() {
        let prober = make_windows_prober();
        let mut layout = StackFrameLayout::new(CallingConv::Win64);
        layout.can_use_red_zone = true; // Should not be possible on Win64
        let errors = prober.validate_frame_layout(&layout);
        assert!(!errors.is_empty());
    }

    // =========================================================================
    // Frame dump / diagram
    // =========================================================================

    #[test]
    fn test_dump_frame_layout() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let dump = prober.dump_frame_layout(&layout);
        assert!(dump.contains("Stack Frame Dump"));
        assert!(dump.contains("SystemV"));
        assert!(dump.contains("x86-64"));
    }

    #[test]
    fn test_draw_frame_diagram() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let diagram = prober.draw_frame_diagram(&layout);
        assert!(diagram.contains("Stack Frame Diagram"));
        assert!(diagram.contains("Return Address"));
    }

    // =========================================================================
    // Statistics
    // =========================================================================

    #[test]
    fn test_stats_initial() {
        let prober = make_linux_prober();
        let stats = prober.get_stats();
        assert_eq!(stats.static_probes, 0);
        assert_eq!(stats.dynamic_probes, 0);
        assert_eq!(stats.alloca_sites, 0);
    }

    #[test]
    fn test_stats_accumulate() {
        let prober = make_linux_prober();
        // Emit some probes
        prober.emit_static_probe(16384);
        prober.lower_alloca(&AllocaConfig {
            size_reg: VirtReg::new(),
            result_reg: VirtReg::new(),
            alignment: 16,
            in_entry_block: true,
            probe: true,
            use_save_restore: false,
        });
        let stats = prober.get_stats();
        assert!(stats.static_probes > 0);
        assert!(stats.alloca_sites > 0);
    }

    #[test]
    fn test_stats_merge() {
        let mut s1 = ProbeStats::new();
        s1.static_probes = 5;
        s1.dynamic_probes = 3;
        let s2 = ProbeStats {
            static_probes: 2,
            dynamic_probes: 1,
            ..ProbeStats::default()
        };
        s1.merge(&s2);
        assert_eq!(s1.static_probes, 7);
        assert_eq!(s1.dynamic_probes, 4);
    }

    #[test]
    fn test_stats_reset() {
        let mut stats = ProbeStats::new();
        stats.static_probes = 10;
        stats.reset();
        assert_eq!(stats.static_probes, 0);
    }

    #[test]
    fn test_stats_display() {
        let stats = ProbeStats {
            static_probes: 3,
            dynamic_probes: 2,
            probe_loops: 1,
            realigned_functions: 0,
            clash_protected_functions: 1,
            alloca_sites: 4,
            total_bytes_probed: 12288,
            chkstk_calls: 0,
            gap_probes: 0,
        };
        let display = format!("{}", stats);
        assert!(display.contains("Static probes:          3"));
        assert!(display.contains("Dynamic probes:         2"));
        assert!(display.contains("Total bytes probed:     12288"));
    }

    // =========================================================================
    // CalleeSavedManager
    // =========================================================================

    #[test]
    fn test_callee_saved_manager_basic() {
        let mut mgr = CalleeSavedManager::new(8);
        mgr.add_spill(RBX_REG);
        mgr.add_spill(R12_REG);
        let size = mgr.finalize();
        assert_eq!(size, 16);
        assert_eq!(mgr.count(), 2);
        assert!(mgr.spill_offset(0).is_some());
        assert!(mgr.spill_offset(1).is_some());
    }

    #[test]
    fn test_callee_saved_prologue_spills() {
        let mut mgr = CalleeSavedManager::new(8);
        mgr.add_spill(RBX_REG);
        mgr.add_spill(R12_REG);
        mgr.finalize();
        let spills = mgr.emit_prologue_spills();
        assert_eq!(spills.len(), 2);
    }

    #[test]
    fn test_callee_saved_epilogue_restores() {
        let mut mgr = CalleeSavedManager::new(8);
        mgr.add_spill(RBX_REG);
        mgr.finalize();
        let restores = mgr.emit_epilogue_restores();
        assert_eq!(restores.len(), 1);
    }

    // =========================================================================
    // AllocaTracker
    // =========================================================================

    #[test]
    fn test_alloca_tracker_register() {
        let mut tracker = AllocaTracker::new();
        let idx = tracker.register_alloca(VirtReg::new(), VirtReg::new(), 16, true);
        assert_eq!(idx, 0);
        assert!(tracker.has_entry_alloca);
        assert_eq!(tracker.count(), 1);
    }

    #[test]
    fn test_alloca_tracker_multiple() {
        let mut tracker = AllocaTracker::new();
        tracker.register_alloca(VirtReg::new(), VirtReg::new(), 8, true);
        tracker.register_alloca(VirtReg::new(), VirtReg::new(), 16, false);
        assert_eq!(tracker.count(), 2);
        assert!(tracker.needs_save_restore);
    }

    #[test]
    fn test_alloca_tracker_entry_allocas() {
        let mut tracker = AllocaTracker::new();
        tracker.register_alloca(VirtReg::new(), VirtReg::new(), 8, true);
        tracker.register_alloca(VirtReg::new(), VirtReg::new(), 16, false);
        assert_eq!(tracker.entry_allocas().count(), 1);
        assert_eq!(tracker.non_entry_allocas().count(), 1);
    }

    #[test]
    fn test_alloca_tracker_update() {
        let mut tracker = AllocaTracker::new();
        let idx = tracker.register_alloca(VirtReg::new(), VirtReg::new(), 16, true);
        let fo = FrameObject::new_variable(0, 0, 16, 0, 0, VirtReg::new());
        tracker.update_alloca_result(idx, VirtReg::new(), VirtReg::new(), true, fo);
        let record = &tracker.allocas[idx];
        assert!(record.probed);
        assert!(record.frame_object.is_some());
    }

    // =========================================================================
    // ShadowSpaceManager
    // =========================================================================

    #[test]
    fn test_shadow_space_manager_active() {
        let mgr = ShadowSpaceManager::new(true);
        assert!(mgr.active);
        assert_eq!(mgr.size, SHADOW_SPACE_WIN64);
    }

    #[test]
    fn test_shadow_space_manager_inactive() {
        let mgr = ShadowSpaceManager::new(false);
        assert!(!mgr.active);
        assert_eq!(mgr.size, 0);
    }

    #[test]
    fn test_shadow_space_slot_offsets() {
        let mgr = ShadowSpaceManager::new(true);
        assert_eq!(mgr.shadow_slot_offset(0), 0);
        assert_eq!(mgr.shadow_slot_offset(1), 8);
        assert_eq!(mgr.shadow_slot_offset(2), 16);
        assert_eq!(mgr.shadow_slot_offset(3), 24);
    }

    #[test]
    fn test_shadow_space_can_fit_args() {
        let mgr = ShadowSpaceManager::new(true);
        assert!(mgr.can_fit_args(4));
    }

    // =========================================================================
    // RedZoneManager
    // =========================================================================

    #[test]
    fn test_red_zone_allocate() {
        let mut mgr = RedZoneManager::new(true);
        assert!(mgr.allocate(64));
        assert_eq!(mgr.used, 64);
        assert_eq!(mgr.remaining(), 64); // 128 - 64
    }

    #[test]
    fn test_red_zone_full() {
        let mut mgr = RedZoneManager::new(true);
        assert!(mgr.allocate(128));
        assert!(!mgr.allocate(1)); // Red zone exhausted
    }

    #[test]
    fn test_red_zone_unavailable() {
        let mut mgr = RedZoneManager::new(false);
        assert!(!mgr.allocate(1));
        assert_eq!(mgr.remaining(), 0);
    }

    #[test]
    fn test_red_zone_reset() {
        let mut mgr = RedZoneManager::new(true);
        mgr.allocate(100);
        mgr.reset();
        assert_eq!(mgr.used, 0);
        assert_eq!(mgr.remaining(), 128);
    }

    #[test]
    fn test_red_zone_offset() {
        let mgr = RedZoneManager::new(true);
        assert_eq!(mgr.offset_for_allocation(0), -8);
        assert_eq!(mgr.offset_for_allocation(1), -16);
    }

    // =========================================================================
    // OutgoingArgManager
    // =========================================================================

    #[test]
    fn test_outgoing_arg_manager_basic() {
        let mut mgr = OutgoingArgManager::new();
        mgr.reserve(32);
        mgr.reserve(64); // Takes max
        assert_eq!(mgr.total_size, 64);
    }

    #[test]
    fn test_outgoing_arg_finalize() {
        let mut mgr = OutgoingArgManager::new();
        mgr.reserve(30);
        let aligned = mgr.finalize(16);
        assert_eq!(aligned, 32); // 30 aligned up to 32
    }

    // =========================================================================
    // FrameBuilder
    // =========================================================================

    #[test]
    fn test_frame_builder_basic() {
        let layout = FrameBuilder::new(CallingConv::SystemV)
            .with_frame_pointer(true)
            .add_callee_saved(RBX_REG, 8)
            .add_fixed_local(16, 8)
            .with_outgoing_args(32)
            .build();
        assert!(layout.has_frame_pointer);
        assert_eq!(layout.callee_saved_spills.len(), 1);
        assert_eq!(layout.fixed_objects.len(), 1);
        assert_eq!(layout.outgoing_arg_size, 32);
    }

    #[test]
    fn test_frame_builder_with_realignment() {
        let layout = FrameBuilder::new(CallingConv::SystemV)
            .with_dynamic_realignment(64)
            .build();
        assert!(layout.has_dynamic_realignment);
        assert_eq!(layout.realign_amount, 64);
    }

    #[test]
    fn test_frame_builder_with_drap() {
        let layout = FrameBuilder::new(CallingConv::SystemV)
            .with_drap(DRAP_REGISTER_X64)
            .build();
        assert_eq!(layout.drap_register, Some(DRAP_REGISTER_X64));
    }

    #[test]
    fn test_frame_builder_full() {
        let layout = FrameBuilder::new(CallingConv::Win64)
            .with_frame_pointer(true)
            .add_callee_saved(RBX_REG, 8)
            .add_callee_saved(R12_REG, 8)
            .add_fixed_local(32, 16)
            .with_outgoing_args(32)
            .with_shadow_space(32)
            .with_red_zone(false)
            .with_probe_interval(4096)
            .build();
        assert!(layout.total_frame_size > 0);
        assert_eq!(layout.shadow_space_size, 32);
    }

    // =========================================================================
    // ABISpecific
    // =========================================================================

    #[test]
    fn test_abi_systemv() {
        let abi = ABISpecific::for_calling_conv(CallingConv::SystemV);
        assert!(abi.has_red_zone);
        assert!(!abi.has_shadow_space);
        assert!(!abi.requires_probe_large_frame);
        assert_eq!(abi.red_zone_size, RED_ZONE_SIZE_SYSV);
        assert!(abi.supports_realignment);
    }

    #[test]
    fn test_abi_win64() {
        let abi = ABISpecific::for_calling_conv(CallingConv::Win64);
        assert!(!abi.has_red_zone);
        assert!(abi.has_shadow_space);
        assert!(abi.requires_probe_large_frame);
        assert_eq!(abi.shadow_space_size, SHADOW_SPACE_WIN64);
    }

    #[test]
    fn test_abi_cdecl32() {
        let abi = ABISpecific::for_calling_conv(CallingConv::Cdecl32);
        assert!(!abi.has_red_zone);
        assert!(!abi.has_shadow_space);
        assert!(!abi.requires_probe_large_frame);
    }

    #[test]
    fn test_abi_should_probe_frame() {
        let abi = ABISpecific::for_calling_conv(CallingConv::Win64);
        assert!(abi.should_probe_frame(16384, 4096));
        assert!(!abi.should_probe_frame(2048, 4096));
    }

    // =========================================================================
    // TargetOS
    // =========================================================================

    #[test]
    fn test_target_os_is_windows() {
        assert!(TargetOS::Windows.is_windows());
        assert!(!TargetOS::Linux.is_windows());
    }

    #[test]
    fn test_target_os_is_linux() {
        assert!(TargetOS::Linux.is_linux());
        assert!(!TargetOS::Windows.is_linux());
    }

    #[test]
    fn test_target_os_has_red_zone() {
        assert!(TargetOS::Linux.has_red_zone());
        assert!(TargetOS::MacOS.has_red_zone());
        assert!(!TargetOS::Windows.has_red_zone());
    }

    #[test]
    fn test_target_os_requires_shadow_space() {
        assert!(TargetOS::Windows.requires_shadow_space());
        assert!(!TargetOS::Linux.requires_shadow_space());
    }

    #[test]
    fn test_target_os_display() {
        assert_eq!(format!("{}", TargetOS::Linux), "linux");
        assert_eq!(format!("{}", TargetOS::Windows), "windows");
        assert_eq!(format!("{}", TargetOS::MacOS), "macos");
    }

    // =========================================================================
    // CallingConv
    // =========================================================================

    #[test]
    fn test_calling_conv_is_64bit() {
        assert!(CallingConv::SystemV.is_64bit());
        assert!(CallingConv::Win64.is_64bit());
        assert!(!CallingConv::Cdecl32.is_64bit());
    }

    #[test]
    fn test_calling_conv_is_windows() {
        assert!(CallingConv::Win64.is_windows());
        assert!(CallingConv::Stdcall32.is_windows());
        assert!(!CallingConv::SystemV.is_windows());
    }

    #[test]
    fn test_calling_conv_requires_shadow_space() {
        assert!(CallingConv::Win64.requires_shadow_space());
        assert!(!CallingConv::SystemV.requires_shadow_space());
    }

    // =========================================================================
    // ProbeStrategy
    // =========================================================================

    #[test]
    fn test_probe_strategy_is_runtime_call() {
        assert!(ProbeStrategy::ChkStk.is_runtime_call());
        assert!(ProbeStrategy::ChkStkMs.is_runtime_call());
        assert!(!ProbeStrategy::Inline.is_runtime_call());
        assert!(!ProbeStrategy::None.is_runtime_call());
    }

    #[test]
    fn test_probe_strategy_is_inline() {
        assert!(ProbeStrategy::Inline.is_inline());
        assert!(ProbeStrategy::ExplicitProbe.is_inline());
        assert!(!ProbeStrategy::ChkStk.is_inline());
    }

    #[test]
    fn test_probe_strategy_runtime_symbol() {
        assert_eq!(ProbeStrategy::ChkStk.runtime_symbol(), Some("__chkstk"));
        assert_eq!(
            ProbeStrategy::ChkStkMs.runtime_symbol(),
            Some("__chkstk_ms")
        );
        assert_eq!(ProbeStrategy::Inline.runtime_symbol(), None);
    }

    // =========================================================================
    // RealignAlignment
    // =========================================================================

    #[test]
    fn test_realign_alignment_byte_value() {
        assert_eq!(RealignAlignment::None.byte_value(), 0);
        assert_eq!(RealignAlignment::Align32.byte_value(), 32);
        assert_eq!(RealignAlignment::Align64.byte_value(), 64);
        assert_eq!(RealignAlignment::Align128.byte_value(), 128);
    }

    #[test]
    fn test_realign_alignment_from_bytes() {
        assert_eq!(RealignAlignment::from_bytes(0), RealignAlignment::None);
        assert_eq!(RealignAlignment::from_bytes(16), RealignAlignment::Align32);
        assert_eq!(RealignAlignment::from_bytes(32), RealignAlignment::Align32);
        assert_eq!(RealignAlignment::from_bytes(64), RealignAlignment::Align64);
        assert_eq!(
            RealignAlignment::from_bytes(128),
            RealignAlignment::Align128
        );
    }

    // =========================================================================
    // FrameObject
    // =========================================================================

    #[test]
    fn test_frame_object_new_fixed() {
        let obj = FrameObject::new_fixed(1, 16, 8, -16, -16);
        assert_eq!(obj.id, 1);
        assert_eq!(obj.size, 16);
        assert_eq!(obj.alignment, 8);
        assert_eq!(obj.kind, FrameObjectKind::Fixed);
    }

    #[test]
    fn test_frame_object_new_variable() {
        let reg = VirtReg::new();
        let obj = FrameObject::new_variable(2, 0, 16, -32, -32, reg);
        assert_eq!(obj.kind, FrameObjectKind::Variable);
        assert!(obj.size_reg.is_some());
    }

    #[test]
    fn test_frame_object_new_callee_saved() {
        let obj = FrameObject::new_callee_saved(3, RBX_REG, 8, -8, -8);
        assert_eq!(obj.kind, FrameObjectKind::CalleeSavedReg);
        assert_eq!(obj.phys_reg, Some(RBX_REG));
        assert!(obj.is_spill);
    }

    #[test]
    fn test_frame_object_new_return_address() {
        let obj = FrameObject::new_return_address(8);
        assert_eq!(obj.kind, FrameObjectKind::ReturnAddress);
        assert_eq!(obj.size, 8);
    }

    #[test]
    fn test_frame_object_new_shadow_space() {
        let obj = FrameObject::new_shadow_space(0);
        assert_eq!(obj.kind, FrameObjectKind::ShadowSpace);
        assert_eq!(obj.size, SHADOW_SPACE_WIN64);
    }

    // =========================================================================
    // FrameObjectKind Display
    // =========================================================================

    #[test]
    fn test_frame_object_kind_display() {
        assert_eq!(format!("{}", FrameObjectKind::Fixed), "fixed");
        assert_eq!(format!("{}", FrameObjectKind::Variable), "variable");
        assert_eq!(
            format!("{}", FrameObjectKind::CalleeSavedReg),
            "callee_saved"
        );
        assert_eq!(format!("{}", FrameObjectKind::ReturnAddress), "return_addr");
        assert_eq!(
            format!("{}", FrameObjectKind::OutgoingArgs),
            "outgoing_args"
        );
        assert_eq!(format!("{}", FrameObjectKind::ShadowSpace), "shadow_space");
        assert_eq!(
            format!("{}", FrameObjectKind::StackProtector),
            "stack_protector"
        );
    }

    // =========================================================================
    // StackFrameLayout
    // =========================================================================

    #[test]
    fn test_stack_frame_layout_new() {
        let layout = StackFrameLayout::new(CallingConv::SystemV);
        assert_eq!(layout.stack_alignment, STACK_ALIGNMENT_SYSV);
        assert!(layout.can_use_red_zone);
        assert_eq!(layout.shadow_space_size, 0);
    }

    #[test]
    fn test_stack_frame_layout_win64() {
        let layout = StackFrameLayout::new(CallingConv::Win64);
        assert_eq!(layout.shadow_space_size, SHADOW_SPACE_WIN64);
        assert!(!layout.can_use_red_zone);
    }

    #[test]
    fn test_align_offset() {
        assert_eq!(StackFrameLayout::align_offset(0, 16), 0);
        assert_eq!(StackFrameLayout::align_offset(1, 16), 16);
        assert_eq!(StackFrameLayout::align_offset(15, 16), 16);
        assert_eq!(StackFrameLayout::align_offset(16, 16), 16);
        assert_eq!(StackFrameLayout::align_offset(17, 16), 32);
    }

    // =========================================================================
    // Edge cases
    // =========================================================================

    #[test]
    fn test_zero_frame_all_operations() {
        let prober = make_linux_prober();
        let info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: false,
            callee_saved_regs: vec![],
            reg_size: 8,
            fixed_locals: vec![],
            num_variable_allocas: 0,
            outgoing_arg_size: 0,
            is_leaf: true,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        };
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.total_frame_size, 0);
        assert!(!layout.requires_static_probe);
        assert!(!layout.requires_dynamic_probe);
    }

    #[test]
    fn test_huge_frame() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.fixed_locals = vec![(1_000_000, 16)]; // ~1 MiB local
        let layout = prober.compute_frame_layout(&info);
        assert!(layout.total_frame_size >= 1_000_000);
    }

    #[test]
    fn test_many_callee_saved() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.callee_saved_regs = vec![RBX_REG, R12_REG, R13_REG, R14_REG, R15_REG];
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.callee_saved_spills.len(), 5);
        assert_eq!(layout.callee_saved_size(), 40); // 5 * 8
    }

    #[test]
    fn test_mixed_alignments() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.fixed_locals = vec![
            (4, 4),   // int
            (8, 8),   // double
            (32, 32), // __m256
            (64, 64), // __m512
        ];
        let layout = prober.compute_frame_layout(&info);
        assert!(!layout.fixed_objects.is_empty());
    }

    // =========================================================================
    // Concurrency / Atomic
    // =========================================================================

    #[test]
    fn test_next_frame_object_id_thread_safe() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        let id1 = prober.next_frame_object_id();
        let id2 = prober.next_frame_object_id();
        assert_ne!(id1, id2);
    }

    #[test]
    fn test_probe_count_atomic() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        let c1 = prober.probe_count.load(Ordering::Relaxed);
        // Emission triggers fetch_add
        prober.emit_static_probe(4096);
        let c2 = prober.probe_count.load(Ordering::Relaxed);
        assert!(c2 > c1);
    }

    // =========================================================================
    // End-to-end: realistic scenario tests
    // =========================================================================

    #[test]
    fn test_e2e_linux_leaf_with_red_zone() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        let info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: false,
            callee_saved_regs: vec![],
            reg_size: 8,
            fixed_locals: vec![(64, 8)],
            num_variable_allocas: 0,
            outgoing_arg_size: 0,
            is_leaf: true,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        };
        let layout = prober.compute_leaf_frame_layout(&info);
        assert!(layout.can_use_red_zone);
        // 64 bytes fits in 128-byte red zone → no SP adjustment
        assert_eq!(layout.total_frame_size, 0);
    }

    #[test]
    fn test_e2e_windows_large_frame() {
        let mut prober = X86StackProbing::new(TargetOS::Windows, CallingConv::Win64);
        prober.set_stack_clash_protection(true);

        let mut info = make_basic_frame_info();
        info.calling_conv = CallingConv::Win64;
        info.fixed_locals = vec![(65536, 16)]; // 64 KiB local

        let layout = prober.compute_win64_frame_layout(&info);
        assert!(layout.requires_static_probe);
        assert_eq!(layout.shadow_space_size, SHADOW_SPACE_WIN64);

        let clash_result = prober.apply_stack_clash_protection(&layout);
        assert!(clash_result.protected);
        assert!(clash_result.entry_probes > 0);
    }

    #[test]
    fn test_e2e_dynamic_alloca_with_probing() {
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.set_stack_clash_protection(true);
        prober.set_probe_dynamic_alloca(true);

        let mut info = make_basic_frame_info();
        info.num_variable_allocas = 3;

        let layout = prober.compute_frame_layout(&info);
        assert!(layout.has_variable_allocas);
        assert!(layout.requires_dynamic_probe);

        let clash_result = prober.apply_stack_clash_protection(&layout);
        assert!(clash_result.protected);
    }

    #[test]
    fn test_e2e_realignment_with_drap() {
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.enable_dynamic_realignment(RealignAlignment::Align64);
        prober.set_uses_frame_pointer(true);

        let result = prober.emit_dynamic_realignment(
            RealignAlignment::Align64,
            true,  // needs frame pointer
            false, // base reg NOT available → DRAP needed
        );
        assert!(result.used_drap);
        assert_eq!(result.alignment, 64);

        let epilogue = prober.emit_realignment_epilogue(&result);
        assert!(!epilogue.is_empty());
    }

    #[test]
    fn test_e2e_multiple_allocas_with_gap_probes() {
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.set_stack_clash_protection(true);
        prober.set_probe_dynamic_alloca(true);

        // Create a layout with multiple variable allocas
        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.has_variable_allocas = true;
        layout.variable_objects = vec![
            FrameObject::new_variable(1, 0, 16, -100, -100, VirtReg::new()),
            FrameObject::new_variable(2, 0, 16, -10000, -10000, VirtReg::new()), // large gap
        ];

        let result = prober.apply_stack_clash_protection(&layout);
        assert!(result.protected);
    }

    #[test]
    fn test_e2e_explicit_entry_probe_large_frame() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        // 1 MiB frame with explicit probes (unrolled)
        let seq = prober.emit_explicit_entry_probe(1_048_576, 512);
        assert!(!seq.instructions.is_empty());
        assert_eq!(seq.total_bytes_covered, 1_048_576);
    }

    #[test]
    fn test_e2e_all_operations_combined() {
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.set_stack_clash_protection(true);
        prober.enable_dynamic_realignment(RealignAlignment::Align64);
        prober.set_probe_dynamic_alloca(true);

        let mut info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: true,
            callee_saved_regs: vec![RBX_REG, R12_REG, R13_REG, R14_REG, R15_REG],
            reg_size: 8,
            fixed_locals: vec![(16, 8), (32, 16), (64, 64)],
            num_variable_allocas: 2,
            outgoing_arg_size: 64,
            is_leaf: false,
            needs_realignment: true,
            realign_amount: 64,
            has_stack_protector: true,
            debug_requires_fp: true,
        };

        let layout = prober.compute_frame_layout(&info);

        // Validate layout
        let errors = prober.validate_frame_layout(&layout);
        assert!(
            errors.is_empty(),
            "Unexpected validation errors: {:?}",
            errors
        );

        // Apply stack clash protection
        let clash = prober.apply_stack_clash_protection(&layout);
        assert!(clash.protected);

        // Emit proposal probe
        let probe = prober.emit_prologue_probe(&layout);

        // Emit dynamic realignment
        let realign = prober.emit_dynamic_realignment(RealignAlignment::Align64, true, false);
        assert!(realign.used_drap);

        // All operations completed without panic
    }

    // =========================================================================
    // Internals — pages_touched, needs_stack_clash_probe
    // =========================================================================

    #[test]
    fn test_pages_touched() {
        let prober = make_linux_prober();
        assert_eq!(prober.pages_touched(0), 0);
        assert_eq!(prober.pages_touched(4096), 1);
        assert_eq!(prober.pages_touched(8192), 2);
    }

    #[test]
    fn test_needs_stack_clash_probe() {
        let mut prober = make_linux_prober();
        assert!(!prober.needs_stack_clash_probe(8192)); // clash off
        prober.set_stack_clash_protection(true);
        assert!(prober.needs_stack_clash_probe(8192));
        assert!(!prober.needs_stack_clash_probe(2048));
    }

    // =========================================================================
    // VirtReg placeholders
    // =========================================================================

    #[test]
    fn test_virtreg_new() {
        let r1 = VirtReg::new();
        let r2 = VirtReg::new();
        assert!(!r1.is_phys);
        assert!(!r2.is_phys);
        assert_ne!(r1.id, r2.id);
    }

    #[test]
    fn test_virtreg_phys() {
        let r = VirtReg::phys(RSP);
        assert!(r.is_phys);
        assert_eq!(r.phys_id, RSP);
    }

    // =========================================================================
    // Probe emission results
    // =========================================================================

    #[test]
    fn test_probe_emission_result_inline() {
        let prober = make_linux_prober();
        let result = prober.emit_static_probe(8192);
        assert!(!result.is_runtime_call);
        assert!(result.probes_emitted > 0);
    }

    #[test]
    fn test_probe_emission_result_runtime() {
        let prober = make_windows_prober();
        let result = prober.emit_static_probe(8192);
        assert!(result.is_runtime_call);
    }

    #[test]
    fn test_probe_emission_zero_bytes() {
        let prober = make_linux_prober();
        let result = prober.emit_dynamic_probe(VirtReg::phys(0), 16);
        // Even with zero-ish input, the probe logic handles it safely
        assert!(!result.instructions.is_empty() || result.probes_emitted == 0);
    }

    // =========================================================================
    // Advanced Integration Tests — Complex Scenarios
    // =========================================================================

    #[test]
    fn test_integration_win64_full_pipeline() {
        // Full Windows x64 pipeline: shadow space, __chkstk, stack clash, CSR spills
        let mut prober = X86StackProbing::new(TargetOS::Windows, CallingConv::Win64);
        prober.set_stack_clash_protection(true);
        prober.set_probe_strategy(ProbeStrategy::ChkStkMs);

        let mut info = FrameInfo {
            calling_conv: CallingConv::Win64,
            uses_frame_pointer: true,
            callee_saved_regs: vec![RBX_REG, R12_REG, R13_REG, R14_REG, R15_REG],
            reg_size: 8,
            fixed_locals: vec![(16, 8), (64, 32), (128, 64), (256, 16)],
            num_variable_allocas: 2,
            outgoing_arg_size: 64,
            is_leaf: false,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: true,
            debug_requires_fp: true,
        };

        let layout = prober.compute_win64_frame_layout(&info);

        // Verify Win64 specifics
        assert_eq!(layout.shadow_space_size, SHADOW_SPACE_WIN64);
        assert!(!layout.can_use_red_zone);
        assert!(layout.requires_static_probe);

        // Stack clash should be applied
        let clash = prober.apply_stack_clash_protection(&layout);
        assert!(clash.protected);

        // Prologue probe should be emitted
        let probe = prober.emit_prologue_probe(&layout);
        assert!(!probe.instructions.is_empty());

        // Validate the layout
        let errors = prober.validate_frame_layout(&layout);
        assert!(errors.is_empty(), "Validation errors: {:?}", errors);
    }

    #[test]
    fn test_integration_linux_avx512_realignment() {
        // Linux x86-64 with AVX-512 requiring 128-byte alignment
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.enable_dynamic_realignment(RealignAlignment::Align128);
        prober.set_uses_frame_pointer(true);
        prober.set_is_leaf_function(false);

        let mut info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: true,
            callee_saved_regs: vec![RBX_REG, R12_REG],
            reg_size: 8,
            fixed_locals: vec![(64, 64)], // __m512 requires 64-byte natural alignment
            num_variable_allocas: 1,
            outgoing_arg_size: 0,
            is_leaf: false,
            needs_realignment: true,
            realign_amount: 128,
            has_stack_protector: false,
            debug_requires_fp: false,
        };

        let layout = prober.compute_frame_layout(&info);
        assert!(layout.has_dynamic_realignment);
        assert_eq!(layout.realign_amount, 128);

        // Emit realignment
        let realign = prober.emit_dynamic_realignment(
            RealignAlignment::Align128,
            true,
            false, // Base reg not available → DRAP
        );
        assert!(realign.used_drap);
        assert_eq!(realign.alignment, 128);

        // Epilogue
        let epilogue = prober.emit_realignment_epilogue(&realign);
        assert!(!epilogue.is_empty());
    }

    #[test]
    fn test_integration_stack_clash_dynamic_growth() {
        // Simulate a function with many allocas that grow the stack over time
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.set_stack_clash_protection(true);
        prober.set_probe_dynamic_alloca(true);

        let mut tracker = AllocaTracker::new();
        for i in 0..10 {
            tracker.register_alloca(VirtReg::new(), VirtReg::new(), 16, i == 0);
        }
        assert_eq!(tracker.count(), 10);
        assert!(tracker.needs_probing(DEFAULT_PROBE_INTERVAL));

        let mut layout = StackFrameLayout::new(CallingConv::SystemV);
        layout.has_variable_allocas = true;
        // Simulate variable objects spread across pages
        for i in 0..10 {
            layout.variable_objects.push(FrameObject::new_variable(
                i,
                0,
                16,
                -(i as i64 * 8192 + 100),
                -(i as i64 * 8192 + 100),
                VirtReg::new(),
            ));
        }

        let clash = prober.apply_stack_clash_protection(&layout);
        assert!(clash.protected);
    }

    #[test]
    fn test_integration_leaf_function_red_zone_optimization() {
        // Leaf function with 80 bytes of locals should use red zone on SysV
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);

        let info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: false,
            callee_saved_regs: vec![],
            reg_size: 8,
            fixed_locals: vec![(80, 8)],
            num_variable_allocas: 0,
            outgoing_arg_size: 0,
            is_leaf: true,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        };

        let layout = prober.compute_leaf_frame_layout(&info);
        assert!(layout.can_use_red_zone);
        // 80 bytes fits in the 128-byte red zone
        assert_eq!(layout.total_frame_size, 0);
    }

    #[test]
    fn test_integration_large_leaf_no_red_zone() {
        // Leaf function with 256 bytes of locals — too large for red zone
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);

        let info = FrameInfo {
            calling_conv: CallingConv::SystemV,
            uses_frame_pointer: false,
            callee_saved_regs: vec![],
            reg_size: 8,
            fixed_locals: vec![(256, 8)],
            num_variable_allocas: 0,
            outgoing_arg_size: 0,
            is_leaf: true,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        };

        let layout = prober.compute_leaf_frame_layout(&info);
        // Even though it's a leaf, the frame is too large for red zone
        assert!(layout.total_frame_size > 0);
    }

    // =========================================================================
    // x86-32 specific tests
    // =========================================================================

    #[test]
    fn test_x86_32_prober_creation() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::Cdecl32);
        assert!(!prober.calling_conv.is_64bit());
        assert_eq!(prober.calling_conv, CallingConv::Cdecl32);
    }

    #[test]
    fn test_x86_32_frame_layout() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::Cdecl32);

        let info = FrameInfo {
            calling_conv: CallingConv::Cdecl32,
            uses_frame_pointer: true,
            callee_saved_regs: vec![EBX32_REG, ESI32_REG, EDI32_REG],
            reg_size: 4,
            fixed_locals: vec![(16, 4)],
            num_variable_allocas: 0,
            outgoing_arg_size: 16,
            is_leaf: false,
            needs_realignment: false,
            realign_amount: 0,
            has_stack_protector: false,
            debug_requires_fp: false,
        };

        let layout = prober.compute_frame_layout(&info);
        assert!(!layout.can_use_red_zone); // No red zone on 32-bit
        assert_eq!(layout.callee_saved_spills.len(), 3);
        assert_eq!(layout.callee_saved_size(), 12); // 3 * 4 bytes
    }

    #[test]
    fn test_x86_32_dynamic_alloca() {
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::Cdecl32);
        let size_reg = VirtReg::new();
        let result_reg = VirtReg::new();

        let config = AllocaConfig {
            size_reg,
            result_reg,
            alignment: 4, // 32-bit default alignment
            in_entry_block: true,
            probe: false,
            use_save_restore: false,
        };

        let result = prober.lower_alloca(&config);
        assert!(!result.instructions.is_empty());
        assert!(!result.probed);
    }

    #[test]
    fn test_x86_32_probe_strategy() {
        let prober = X86StackProbing::new(TargetOS::Windows, CallingConv::Stdcall32);
        assert_eq!(prober.probe_strategy, ProbeStrategy::ChkStk);
    }

    // =========================================================================
    // Boundary and stress tests
    // =========================================================================

    #[test]
    fn test_max_frame_size() {
        // Test with a frame approaching u32::MAX
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.fixed_locals = vec![(u64::MAX / 2, 16)];
        // Should not overflow/painc
        let layout = prober.compute_frame_layout(&info);
        assert!(layout.total_frame_size > 0);
    }

    #[test]
    fn test_max_callee_saved_regs() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        // All possible callee-saved regs on x86-64 SysV
        info.callee_saved_regs = vec![RBX_REG, R12_REG, R13_REG, R14_REG, R15_REG, RBP];
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.callee_saved_spills.len(), 6);
    }

    #[test]
    fn test_minimum_probe_interval_boundary() {
        let mut prober = make_linux_prober();
        prober.set_probe_interval(MIN_PROBE_INTERVAL);
        assert_eq!(prober.probe_interval, MIN_PROBE_INTERVAL);
        // Probe count with minimum interval
        assert_eq!(prober.probe_count_for_size(1024), 1);
        assert_eq!(prober.probe_count_for_size(1025), 2);
    }

    #[test]
    fn test_maximum_probe_interval_boundary() {
        let mut prober = make_linux_prober();
        prober.set_probe_interval(MAX_PROBE_INTERVAL);
        assert_eq!(prober.probe_interval, MAX_PROBE_INTERVAL);
        // Probe count with maximum interval
        assert_eq!(prober.probe_count_for_size(65536), 1);
        assert_eq!(prober.probe_count_for_size(65537), 2);
    }

    #[test]
    fn test_exact_page_boundary_probe() {
        let prober = make_linux_prober();
        // Exactly one page — one probe
        assert_eq!(prober.probe_count_for_size(4096), 1);
        // Exactly two pages
        assert_eq!(prober.probe_count_for_size(8192), 2);
        // One byte beyond two pages — three probes
        assert_eq!(prober.probe_count_for_size(8193), 3);
    }

    // =========================================================================
    // Frame alignment verification
    // =========================================================================

    #[test]
    fn test_alignment_all_power_of_two() {
        let alignments = [1, 2, 4, 8, 16, 32, 64, 128];
        for &align in &alignments {
            for size in [0, 1, align - 1, align, align + 1, align * 2] {
                let result = StackFrameLayout::align_offset(size, align);
                assert_eq!(
                    result % align,
                    0,
                    "align_offset({}, {}) = {} not aligned",
                    size,
                    align,
                    result
                );
                assert!(
                    result >= size,
                    "align_offset({}, {}) = {} < size",
                    size,
                    align,
                    result
                );
            }
        }
    }

    #[test]
    fn test_alignment_monotonic() {
        // align_offset should be monotonic: larger input → larger or equal output
        for align in [4, 8, 16, 32] {
            let mut prev = 0;
            for size in 0..1000u64 {
                let curr = StackFrameLayout::align_offset(size, align);
                assert!(
                    curr >= prev,
                    "align_offset not monotonic at size={} align={}: {} -> {}",
                    size,
                    align,
                    prev,
                    curr
                );
                prev = curr;
            }
        }
    }

    // =========================================================================
    // Concurrency tests
    // =========================================================================

    #[test]
    fn test_concurrent_probe_count() {
        use std::thread;
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        let mut handles = vec![];

        for _ in 0..4 {
            let p = prober.clone();
            handles.push(thread::spawn(move || {
                for _ in 0..100 {
                    p.emit_static_probe(4096);
                }
            }));
        }

        for h in handles {
            h.join().unwrap();
        }

        // After all threads, probe_count should be > 0
        let cnt = prober.probe_count.load(Ordering::Relaxed);
        assert!(cnt > 0, "Probe count should have been incremented");
    }

    #[test]
    fn test_concurrent_stats_accumulation() {
        use std::thread;
        let prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        let mut handles = vec![];

        for i in 0..4 {
            let p = prober.clone();
            handles.push(thread::spawn(move || {
                p.lower_alloca(&AllocaConfig {
                    size_reg: VirtReg::new(),
                    result_reg: VirtReg::new(),
                    alignment: 8,
                    in_entry_block: i == 0,
                    probe: false,
                    use_save_restore: false,
                });
            }));
        }

        for h in handles {
            h.join().unwrap();
        }

        let stats = prober.get_stats();
        assert_eq!(stats.alloca_sites, 4);
    }

    // =========================================================================
    // Serialization / Debug display
    // =========================================================================

    #[test]
    fn test_frame_layout_display_all_fields() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let desc = prober.describe_frame_layout(&layout);

        // Every major field should appear in the description
        assert!(desc.contains("Frame pointer"));
        assert!(desc.contains("Callee-saved"));
        assert!(desc.contains("Fixed locals"));
        assert!(desc.contains("Outgoing args"));
        assert!(desc.contains("Total frame size"));
        assert!(desc.contains("Static probe"));
        assert!(desc.contains("Dynamic probe"));
    }

    #[test]
    fn test_frame_dump_contains_object_details() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let dump = prober.dump_frame_layout(&layout);

        assert!(dump.contains("Stack Frame Dump"));
        assert!(dump.contains("SystemV"));
        assert!(dump.contains("Callee-Saved Spills"));
        assert!(dump.contains("Fixed Frame Objects"));
        assert!(dump.contains("Frame Summary"));
    }

    #[test]
    fn test_frame_diagram_ascii_art() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);
        let diagram = prober.draw_frame_diagram(&layout);

        assert!(diagram.contains("Stack Frame Diagram"));
        assert!(diagram.contains("Return Address"));
        assert!(diagram.contains("Higher addresses"));
        assert!(diagram.contains("Lower addresses"));
    }

    // =========================================================================
    // StackClashConfig tests
    // =========================================================================

    #[test]
    fn test_stack_clash_config_default() {
        let config = StackClashConfig::default();
        assert!(!config.enabled);
        assert_eq!(config.probe_interval, DEFAULT_PROBE_INTERVAL);
        assert!(config.probe_entry);
        assert!(config.probe_gaps);
        assert_eq!(config.probe_threshold, MAX_FRAME_SIZE_WITHOUT_PROBE);
        assert!(!config.use_chkstk);
    }

    // =========================================================================
    // StackDirection enumeration
    // =========================================================================

    #[test]
    fn test_stack_direction_variants() {
        assert_eq!(StackDirection::Downward, StackDirection::Downward);
        assert_eq!(StackDirection::Upward, StackDirection::Upward);
        assert_ne!(StackDirection::Downward, StackDirection::Upward);
    }

    // =========================================================================
    // All properties tested via property-based approach (manual)
    // =========================================================================

    #[test]
    fn test_property_probe_count_covers_size() {
        // Property: probe_count * probe_interval >= size
        for interval in [1024u64, 2048, 4096, 8192] {
            let mut prober = make_linux_prober();
            prober.set_probe_interval(interval);
            for size in [0u64, 1, 100, 1000, 4096, 5000, 8192, 16384, 65536, 100000] {
                let count = prober.probe_count_for_size(size);
                if size > 0 {
                    assert!(
                        count * interval >= size,
                        "probe_count({}) * {} = {} < {}",
                        size,
                        interval,
                        count * interval,
                        size
                    );
                } else {
                    assert_eq!(count, 0);
                }
            }
        }
    }

    #[test]
    fn test_property_alignment_preserves_idempotency() {
        // Property: align_offset(align_offset(x, a), a) == align_offset(x, a)
        for align in [4u64, 8, 16, 32, 64] {
            for x in [
                0u64, 1, 7, 8, 9, 15, 16, 17, 31, 32, 33, 63, 64, 100, 127, 128, 255, 256,
            ] {
                let once = StackFrameLayout::align_offset(x, align);
                let twice = StackFrameLayout::align_offset(once, align);
                assert_eq!(
                    once, twice,
                    "align_offset not idempotent: {} -> {} -> {}",
                    x, once, twice
                );
            }
        }
    }

    #[test]
    fn test_property_frame_size_is_aligned() {
        // Property: after computing frame layout, total_frame_size is aligned
        let mut prober = make_linux_prober();
        prober.enable_dynamic_realignment(RealignAlignment::Align64);

        let mut info = make_basic_frame_info();
        info.needs_realignment = true;
        info.realign_amount = 64;

        let layout = prober.compute_frame_layout(&info);
        assert_eq!(
            layout.total_frame_size % layout.stack_alignment,
            0,
            "Frame size {} not aligned to {}",
            layout.total_frame_size,
            layout.stack_alignment
        );
    }

    // =========================================================================
    // Documentation examples — compile-time verification of patterns
    // =========================================================================

    #[test]
    fn test_doc_example_basic_probing() {
        // Example from module-level documentation
        let mut prober = X86StackProbing::new(TargetOS::Linux, CallingConv::SystemV);
        prober.set_probe_strategy(ProbeStrategy::Inline);
        prober.set_stack_clash_protection(true);
        prober.set_probe_interval(4096);
        prober.enable_dynamic_realignment(RealignAlignment::Align64);

        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);

        // Prologue probe should be emitted for the static frame
        let result = prober.emit_prologue_probe(&layout);
        assert!(result.probes_emitted > 0 || !layout.requires_static_probe);
    }

    #[test]
    fn test_doc_example_chkstk() {
        // Example: Windows __chkstk usage
        let prober = X86StackProbing::new(TargetOS::Windows, CallingConv::Win64);
        let result = prober.emit_chkstk_call(16384, false);
        assert!(result.is_runtime_call);
        assert!(!result.instructions.is_empty());
    }

    #[test]
    fn test_doc_example_chkstk_ms() {
        // Example: Windows __chkstk_ms (MSVC variant)
        let prober = X86StackProbing::new(TargetOS::Windows, CallingConv::Win64);
        let result = prober.emit_chkstk_call(8192, true);
        assert!(result.is_runtime_call);
    }

    // =========================================================================
    // Stack protector canary probe
    // =========================================================================

    #[test]
    fn test_canary_probe_emitted() {
        let prober = make_linux_prober();
        let instrs = prober.emit_canary_probe();
        assert!(!instrs.is_empty());
    }

    // =========================================================================
    // FrameBuilder edge cases
    // =========================================================================

    #[test]
    fn test_frame_builder_empty() {
        let layout = FrameBuilder::new(CallingConv::SystemV).build();
        assert_eq!(layout.total_frame_size, 0);
        assert!(!layout.has_frame_pointer);
    }

    #[test]
    fn test_frame_builder_only_shadow() {
        let layout = FrameBuilder::new(CallingConv::Win64)
            .with_shadow_space(SHADOW_SPACE_WIN64)
            .build();
        assert_eq!(layout.shadow_space_size, SHADOW_SPACE_WIN64);
    }

    #[test]
    fn test_frame_builder_only_outgoing_args() {
        let layout = FrameBuilder::new(CallingConv::SystemV)
            .with_outgoing_args(128)
            .build();
        assert_eq!(layout.outgoing_arg_size, 128);
    }

    #[test]
    fn test_frame_builder_chained() {
        let layout = FrameBuilder::new(CallingConv::SystemV)
            .with_frame_pointer(true)
            .add_callee_saved(RBX_REG, 8)
            .add_callee_saved(R12_REG, 8)
            .add_callee_saved(R13_REG, 8)
            .add_fixed_local(16, 8)
            .add_fixed_local(32, 16)
            .add_fixed_local(64, 64)
            .with_outgoing_args(32)
            .with_red_zone(false)
            .with_probe_interval(4096)
            .build();

        assert!(layout.has_frame_pointer);
        assert_eq!(layout.callee_saved_spills.len(), 3);
        assert_eq!(layout.fixed_objects.len(), 3);
        assert_eq!(layout.outgoing_arg_size, 32);
        assert!(!layout.can_use_red_zone);
    }

    // =========================================================================
    // Regression / consistency tests
    // =========================================================================

    #[test]
    fn test_regression_probe_count_never_zero_for_nonzero_size() {
        let prober = make_linux_prober();
        for size in [1u64, 100, 500, 4095, 4096, 4097, 10000] {
            assert!(
                prober.probe_count_for_size(size) > 0,
                "probe_count_for_size({}) should be > 0",
                size
            );
        }
    }

    #[test]
    fn test_regression_frame_pointer_offset_consistency() {
        let prober = make_linux_prober();
        let info = make_basic_frame_info();
        let layout = prober.compute_frame_layout(&info);

        // With a frame pointer, the return address should be at offset +8 from RBP
        // (RBP points to saved RBP, return address is above it)
        assert_eq!(layout.return_address_offset, 8);
    }

    #[test]
    fn test_regression_no_double_probe() {
        // A small frame with probing disabled should not emit any probes
        let mut prober = make_linux_prober();
        prober.set_probe_strategy(ProbeStrategy::None);
        prober.set_stack_clash_protection(false);

        let layout = StackFrameLayout::new(CallingConv::SystemV);
        let result = prober.emit_prologue_probe(&layout);
        assert!(result.instructions.is_empty());
    }

    #[test]
    fn test_regression_alloca_with_zero_alignment() {
        // alloca with alignment=0 should be treated as default alignment
        let prober = make_linux_prober();
        let config = AllocaConfig {
            size_reg: VirtReg::new(),
            result_reg: VirtReg::new(),
            alignment: 0, // Edge: zero alignment
            in_entry_block: true,
            probe: false,
            use_save_restore: false,
        };
        let result = prober.lower_alloca(&config);
        // Should still produce valid instructions
        assert!(!result.instructions.is_empty());
    }

    #[test]
    fn test_regression_virtreg_uniqueness() {
        // Virtual registers created during lowering should be unique
        let prober = make_linux_prober();
        let config = AllocaConfig {
            size_reg: VirtReg::new(),
            result_reg: VirtReg::new(),
            alignment: 16,
            in_entry_block: true,
            probe: false,
            use_save_restore: true,
        };
        let result = prober.lower_alloca(&config);
        assert_ne!(result.old_sp_reg.id, result.new_sp_reg.id);
        assert_ne!(result.old_sp_reg.id, config.size_reg.id);
    }

    // =========================================================================
    // Opcode and instruction integrity
    // =========================================================================

    #[test]
    fn test_machine_instr_placeholder_types() {
        let instr = MachineInstr::placeholder("test_push");
        assert!(!instr.operands.is_empty());
    }

    #[test]
    fn test_machine_operand_variants() {
        let reg_op = MachineOperand::Reg(VirtReg::new());
        let imm_op = MachineOperand::Imm(42);
        let sym_op = MachineOperand::Symbol("test".to_string());
        let mem_op = MachineOperand::Mem {
            base: VirtReg::new(),
            index: VirtReg::new(),
            scale: 1,
            disp: 0,
        };

        // All variants should be constructable
        match reg_op {
            MachineOperand::Reg(_) => {}
            _ => panic!("Expected Reg"),
        }
        match imm_op {
            MachineOperand::Imm(42) => {}
            _ => panic!("Expected Imm"),
        }
        match &sym_op {
            MachineOperand::Symbol(s) => assert_eq!(s, "test"),
            _ => panic!("Expected Symbol"),
        }
        match mem_op {
            MachineOperand::Mem { scale, disp, .. } => {
                assert_eq!(scale, 1);
                assert_eq!(disp, 0);
            }
            _ => panic!("Expected Mem"),
        }
    }

    // =========================================================================
    // Assert that no panics occur in edge configurations
    // =========================================================================

    #[test]
    fn test_no_panic_empty_callee_saved() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.callee_saved_regs = vec![];
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.callee_saved_spills.len(), 0);
        assert_eq!(layout.callee_saved_size(), 0);
    }

    #[test]
    fn test_no_panic_no_fixed_locals() {
        let prober = make_linux_prober();
        let mut info = make_basic_frame_info();
        info.fixed_locals = vec![];
        let layout = prober.compute_frame_layout(&info);
        assert_eq!(layout.fixed_objects.len(), 0);
    }

    #[test]
    fn test_no_panic_realignment_disabled_but_requested() {
        let prober = make_linux_prober(); // realignment is disabled
        let result = prober.emit_dynamic_realignment(RealignAlignment::Align64, true, true);
        // Should return empty (no realignment configured) or safe fallback
        // Even if alignment is requested but realign_enabled is false,
        // the method should handle it.
        assert!(result.alignment == 0 || result.alignment == 64);
    }

    // =========================================================================
    // Display implementations
    // =========================================================================

    #[test]
    fn test_target_os_display_all() {
        for os in [
            TargetOS::Linux,
            TargetOS::Windows,
            TargetOS::MacOS,
            TargetOS::FreeBSD,
            TargetOS::Unix,
            TargetOS::Unknown,
        ] {
            let s = format!("{}", os);
            assert!(!s.is_empty());
        }
    }

    #[test]
    fn test_frame_object_kind_display_all() {
        for kind in [
            FrameObjectKind::Fixed,
            FrameObjectKind::Variable,
            FrameObjectKind::CalleeSavedReg,
            FrameObjectKind::ReturnAddress,
            FrameObjectKind::OutgoingArgs,
            FrameObjectKind::ShadowSpace,
            FrameObjectKind::StackProtector,
        ] {
            let s = format!("{}", kind);
            assert!(!s.is_empty());
        }
    }

    #[test]
    fn test_probe_stats_display_all_fields() {
        let stats = ProbeStats {
            static_probes: 1,
            dynamic_probes: 2,
            probe_loops: 3,
            realigned_functions: 4,
            clash_protected_functions: 5,
            alloca_sites: 6,
            total_bytes_probed: 7,
            chkstk_calls: 8,
            gap_probes: 9,
        };
        let s = format!("{}", stats);
        assert!(s.contains("1"));
        assert!(s.contains("9"));
    }

    // =========================================================================
    // ClashSeverity enum
    // =========================================================================

    #[test]
    fn test_clash_severity_all_variants() {
        for sev in [
            ClashSeverity::None,
            ClashSeverity::Low,
            ClashSeverity::Medium,
            ClashSeverity::High,
            ClashSeverity::Critical,
        ] {
            // All variants should be comparable
            assert_eq!(sev, sev);
        }
    }

    // =========================================================================
    // StackClashResult summary
    // =========================================================================

    #[test]
    fn test_stack_clash_result_fields() {
        let result = StackClashResult {
            protected: true,
            entry_probes: 5,
            gap_probes: 3,
            entry_bytes_probed: 20480,
            gap_bytes_probed: 12288,
            code_overhead_bytes: 40,
            used_runtime: false,
            severity_before: ClashSeverity::High,
            severity_after: ClashSeverity::None,
        };
        assert!(result.protected);
        assert_eq!(result.entry_probes, 5);
        assert_eq!(result.gap_probes, 3);
        assert_eq!(result.severity_before, ClashSeverity::High);
        assert_eq!(result.severity_after, ClashSeverity::None);
    }
}