llvm-native-core 0.1.9

//! X86 Addressing Modes — Complete ModR/M + SIB combination support,
//! memory lowering, address mode selection, optimization, and segment
//! register handling. ~9000+ lines.
//!
//! Clean-room behavioral reconstruction from:
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual,
//!   Volume 2A (Instruction Set Reference, Chapter 2: Instruction Format)
//! - AMD64 Architecture Programmer's Manual, Volume 3 (General-Purpose and
//!   System Instructions)
//! - System V Application Binary Interface: AMD64 Architecture Processor
//!   Supplement (PIC, TLS, and addressing conventions)
//!
//! ## Architecture
//! ```text
//! X86AddressingFull          — top-level addressing mode engine
//! ├── X86AddressMode         — canonical representation (16/32/64-bit)
//! ├── X86AddressingModeBuilder — builder pattern with canonicalization
//! ├── X86MemoryLowering      — IR load/store/frame/global lowering
//! ├── X86AddressOptimization — LEA formation, sinking, factoring
//! ├── X86SegmentHandling     — FS/GS/SS/DS/ES/CS segment overrides
//! └── X86AddressingTestSuite — comprehensive coverage tests
//! ```
//!
//! ## ModR/M Encoding (1 byte)
//! ```text
//! Bits:  7-6    5-3    2-0
//!       [mod]  [reg]  [r/m]
//!
//! mod = 00 → [reg] (r/m≠5), [disp32] (r/m=5), [sib] (r/m=4)
//! mod = 01 → [reg + disp8]
//! mod = 10 → [reg + disp32]
//! mod = 11 → register-direct mode
//! ```
//!
//! ## SIB Byte (1 byte)
//! ```text
//! Bits:  7-6      5-3      2-0
//!       [scale]  [index]  [base]
//!
//! scale = 0→1, 1→2, 2→4, 3→8
//! index = 4 means "no index" (ESP/RSP cannot be index)
//! base  = 5 with mod=00 means [disp32] (or [RIP+disp32] in 64-bit mode)
//! ```
//!
//! ## 16-bit Addressing Modes
//! Uses a hard-coded table because 16-bit mode does not use SIB.
//! The effective address is formed by summing the selected registers.
//!
//! ## 64-bit Addressing Special Cases
//! - [RIP + disp32]: mod=00, r/m=5 (RBP encoding) — RIP-relative
//! - [R12]: requires SIB byte to disambiguate from [disp32] (mod=00, r/m=4)
//! - [R13]: SIB with base=R13 (5), index=4 (none), disp8/disp32 per mod
//! - [RSP]/[R12]: SIB with base=RSP (4)/R12 (4), index=4 (none)
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications and black-box oracle interrogation.

use crate::x86::x86_instr_info::{X86MemOperand, X86Opcode};
use crate::x86::x86_register_info::{self, X86RegisterInfo, BP, BX, DI, SI};
use std::collections::{BTreeMap, HashMap, HashSet};

// ============================================================================
// Addressing Mode Width (16-bit / 32-bit / 64-bit)
// ============================================================================

/// The addressing mode width determines which ModR/M interpretation rules,
/// register sets, and displacement sizes apply.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AddrWidth {
    /// 16-bit addressing (real mode, 16-bit protected mode).
    /// Uses the legacy 16-bit ModR/M table: [BX+SI], [BX+DI], [BP+SI], etc.
    Addr16,
    /// 32-bit addressing (32-bit protected mode).
    /// Uses ModR/M + SIB with 32-bit registers and 32-bit displacement.
    Addr32,
    /// 64-bit addressing (long mode).
    /// Uses ModR/M + SIB with 64-bit registers, RIP-relative, and 32-bit displacement.
    Addr64,
}

impl AddrWidth {
    /// Default data size in bytes for this addressing mode.
    pub fn default_data_size(&self) -> u8 {
        match self {
            AddrWidth::Addr16 => 2,
            AddrWidth::Addr32 => 4,
            AddrWidth::Addr64 => 8,
        }
    }

    /// Whether 32-bit displacement is the maximum.
    pub fn max_disp_bits(&self) -> u32 {
        match self {
            AddrWidth::Addr16 => 16,
            AddrWidth::Addr32 | AddrWidth::Addr64 => 32,
        }
    }

    /// Whether this mode supports RIP-relative addressing.
    pub fn supports_rip_relative(&self) -> bool {
        matches!(self, AddrWidth::Addr64)
    }

    /// Whether this mode uses SIB byte.
    pub fn uses_sib(&self) -> bool {
        matches!(self, AddrWidth::Addr32 | AddrWidth::Addr64)
    }
}

// ============================================================================
// 1. X86AddressingFull — top-level addressing mode engine
// ============================================================================

/// Complete X86 addressing mode support engine.
///
/// This struct serves as the entry point for all addressing mode operations:
/// encoding/decoding ModR/M+SIB, selecting optimal address forms, lowering
/// IR memory operations, and optimizing address computations.
///
/// # Examples
/// ```ignore
/// let engine = X86AddressingFull::new(AddrWidth::Addr64);
/// let mode = engine.encode_base_disp(RAX, 42)?;
/// assert_eq!(mode.modrm, 0x40); // mod=01, reg=0, r/m=0
/// ```
#[derive(Debug, Clone)]
pub struct X86AddressingFull {
    /// Current addressing width (16/32/64-bit).
    pub addr_width: AddrWidth,
    /// Register info for name/class lookups.
    pub reg_info: X86RegisterInfo,
    /// Whether to use Intel syntax vs AT&T in debug output.
    pub intel_syntax: bool,
    /// Code model: small, kernel, medium, large.
    pub code_model: CodeModel,
    /// Whether to use position-independent code (PIC).
    pub is_pic: bool,
    /// TLS model: general-dynamic, local-dynamic, initial-exec, local-exec.
    pub tls_model: TlsModel,
    /// Optimization level for addressing mode selection.
    pub opt_level: OptLevel,
}

impl Default for X86AddressingFull {
    fn default() -> Self {
        Self {
            addr_width: AddrWidth::Addr64,
            reg_info: X86RegisterInfo,
            intel_syntax: false,
            code_model: CodeModel::Small,
            is_pic: true,
            tls_model: TlsModel::InitialExec,
            opt_level: OptLevel::Default,
        }
    }
}

impl X86AddressingFull {
    /// Create a new addressing engine with the given width.
    pub fn new(addr_width: AddrWidth) -> Self {
        Self {
            addr_width,
            ..Default::default()
        }
    }

    /// Create a new addressing engine for 64-bit mode.
    pub fn new_x86_64() -> Self {
        Self::new(AddrWidth::Addr64)
    }

    /// Create a new addressing engine for 32-bit mode.
    pub fn new_x86_32() -> Self {
        Self::new(AddrWidth::Addr32)
    }

    /// Create a new addressing engine for 16-bit mode.
    pub fn new_x86_16() -> Self {
        Self::new(AddrWidth::Addr16)
    }

    /// Set the code model.
    pub fn with_code_model(mut self, model: CodeModel) -> Self {
        self.code_model = model;
        self
    }

    /// Set PIC mode.
    pub fn with_pic(mut self, pic: bool) -> Self {
        self.is_pic = pic;
        self
    }

    /// Set TLS model.
    pub fn with_tls_model(mut self, model: TlsModel) -> Self {
        self.tls_model = model;
        self
    }

    /// Set optimization level.
    pub fn with_opt_level(mut self, level: OptLevel) -> Self {
        self.opt_level = level;
        self
    }
}

// ============================================================================
// Code Model (for symbol addressing)
// ============================================================================

/// Code model determines how global symbols are addressed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CodeModel {
    /// All code and data fits within 2GB of the RIP, using RIP-relative.
    /// `mov eax, [rip + symbol]` — default for 64-bit user-space.
    Small,
    /// Kernel code model: symbols in the top 2GB of address space.
    Kernel,
    /// Code fits within 2GB, data may be larger. Code uses RIP-relative,
    /// data uses movabs or GOT.
    Medium,
    /// Both code and data can be anywhere. All symbols use movabs or GOT.
    Large,
}

impl Default for CodeModel {
    fn default() -> Self {
        CodeModel::Small
    }
}

/// TLS (Thread-Local Storage) model.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TlsModel {
    /// General dynamic: most general, works for shared libs.
    GeneralDynamic,
    /// Local dynamic: optimized for module-local TLS.
    LocalDynamic,
    /// Initial exec: TLS block in static TLS, uses GOT.
    InitialExec,
    /// Local exec: fastest, TLS block at fixed offset from thread pointer.
    LocalExec,
}

impl Default for TlsModel {
    fn default() -> Self {
        TlsModel::InitialExec
    }
}

/// Optimization level for addressing mode selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OptLevel {
    /// No optimization: always use base+disp form.
    None,
    /// Default: prefer simple forms unless LEA is beneficial.
    Default,
    /// Aggressive: use LEA for complex address computations.
    Aggressive,
}

// ============================================================================
// 2. X86AddressMode — canonical addressing mode representation
// ============================================================================

/// Canonical X86 addressing mode with full support for all 16/32/64-bit forms.
///
/// Represents the X86 effective address computation:
/// `segment:[base + index*scale + displacement]`
///
/// # 16-bit Addressing Modes
/// In 16-bit mode, the effective address is a 16-bit sum of BX, BP, SI, DI
/// combinations. No SIB byte is used. The ModR/M byte directly encodes
/// the register combination (r/m field selects from a fixed table).
///
/// # 32-bit Addressing Modes
/// Uses ModR/M + optional SIB byte. Base register: any 32-bit GPR (EAX-EDI).
/// Index register: any 32-bit GPR except ESP. Scale: 1, 2, 4, 8.
///
/// # 64-bit Addressing Modes
/// Extends 32-bit with R8-R15 registers. RIP-relative addressing uses
/// ModR/M mod=00, r/m=5. R12/R13 require SIB for disambiguation.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct X86AddressMode {
    /// Addressing width (16, 32, or 64-bit mode).
    pub width: AddrWidth,

    /// Base register ID (e.g., RBX, RBP, RSP, RIP).
    /// `None` means no base register (absolute address or index-only).
    pub base: Option<u16>,

    /// Index register ID (e.g., RSI, RDI). None means no index.
    pub index: Option<u16>,

    /// Scale factor for the index register: 1, 2, 4, or 8.
    /// Zero means no index scaling.
    pub scale: u8,

    /// Signed displacement (8, 16, or 32 bits depending on width).
    pub displacement: i64,

    /// Segment override register ID (FS, GS, SS, etc.). None = default DS/SS.
    pub segment: Option<u16>,

    /// Whether this is a RIP-relative address (64-bit mode only).
    pub is_rip_relative: bool,

    /// Whether this is a frame-relative address (base is RBP/RSP or EBP/ESP).
    pub is_frame_relative: bool,

    /// Symbol name for global/TLS/constant-pool references.
    pub symbol: Option<String>,

    /// Whether the symbol reference uses the GOT (PIC).
    pub is_got_relative: bool,

    /// For 16-bit absolute addressing: true if this is a direct [disp16].
    pub is_absolute_16: bool,

    /// For 32-bit absolute addressing: true if this is [disp32].
    pub is_absolute_32: bool,

    /// 16-bit addressing form (only relevant for Addr16).
    pub form_16bit: Option<X86Addr16Form>,
}

impl Default for X86AddressMode {
    fn default() -> Self {
        Self {
            width: AddrWidth::Addr64,
            base: None,
            index: None,
            scale: 0,
            displacement: 0,
            segment: None,
            is_rip_relative: false,
            is_frame_relative: false,
            symbol: None,
            is_got_relative: false,
            is_absolute_16: false,
            is_absolute_32: false,
            form_16bit: None,
        }
    }
}

impl X86AddressMode {
    // ---- Constructors ----

    /// Create a 64-bit base-only address mode.
    pub fn base64(base: u16) -> Self {
        Self {
            width: AddrWidth::Addr64,
            base: Some(base),
            ..Default::default()
        }
    }

    /// Create a 64-bit base+displacement address mode.
    pub fn base_disp64(base: u16, disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr64,
            base: Some(base),
            displacement: disp,
            ..Default::default()
        }
    }

    /// Create a 64-bit base+index*scale+displacement address mode.
    pub fn full64(base: u16, index: u16, scale: u8, disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr64,
            base: Some(base),
            index: Some(index),
            scale,
            displacement: disp,
            ..Default::default()
        }
    }

    /// Create a RIP-relative address mode (64-bit).
    pub fn rip_relative(disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr64,
            displacement: disp,
            is_rip_relative: true,
            ..Default::default()
        }
    }

    /// Create a 64-bit RIP-relative address with a symbol.
    pub fn rip_symbol(symbol: &str, disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr64,
            displacement: disp,
            is_rip_relative: true,
            symbol: Some(symbol.to_string()),
            ..Default::default()
        }
    }

    /// Create a 32-bit base-only address mode.
    pub fn base32(base: u16) -> Self {
        Self {
            width: AddrWidth::Addr32,
            base: Some(base),
            ..Default::default()
        }
    }

    /// Create a 32-bit base+displacement address mode.
    pub fn base_disp32(base: u16, disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr32,
            base: Some(base),
            displacement: disp,
            ..Default::default()
        }
    }

    /// Create a 32-bit full address mode.
    pub fn full32(base: u16, index: u16, scale: u8, disp: i64) -> Self {
        Self {
            width: AddrWidth::Addr32,
            base: Some(base),
            index: Some(index),
            scale,
            displacement: disp,
            ..Default::default()
        }
    }

    /// Create a 32-bit absolute address [disp32].
    pub fn absolute32(addr: i64) -> Self {
        Self {
            width: AddrWidth::Addr32,
            displacement: addr,
            is_absolute_32: true,
            ..Default::default()
        }
    }

    /// Create a 16-bit base-only: [BX], [BP], [SI], [DI].
    pub fn base16(base: u16) -> Self {
        Self {
            width: AddrWidth::Addr16,
            base: Some(base),
            form_16bit: match base {
                r if r == BX => Some(X86Addr16Form::Bx),
                r if r == BP => Some(X86Addr16Form::Bp),
                r if r == SI => Some(X86Addr16Form::Si),
                r if r == DI => Some(X86Addr16Form::Di),
                _ => None,
            },
            ..Default::default()
        }
    }

    /// Create a 16-bit dual-register: [BX+SI], [BX+DI], [BP+SI], [BP+DI].
    pub fn base_index16(base: u16, index: u16) -> Self {
        let form = match (base, index) {
            (b, i) if b == BX && i == SI => Some(X86Addr16Form::BxSi),
            (b, i) if b == BX && i == DI => Some(X86Addr16Form::BxDi),
            (b, i) if b == BP && i == SI => Some(X86Addr16Form::BpSi),
            (b, i) if b == BP && i == DI => Some(X86Addr16Form::BpDi),
            _ => None,
        };
        Self {
            width: AddrWidth::Addr16,
            base: Some(base),
            index: Some(index),
            form_16bit: form,
            ..Default::default()
        }
    }

    /// Create a 16-bit absolute address [disp16].
    pub fn absolute16(addr: i64) -> Self {
        Self {
            width: AddrWidth::Addr16,
            displacement: addr,
            is_absolute_16: true,
            form_16bit: Some(X86Addr16Form::Disp16),
            ..Default::default()
        }
    }

    /// Set segment override.
    pub fn with_segment(mut self, seg: u16) -> Self {
        self.segment = Some(seg);
        self
    }

    /// Set frame-relative flag.
    pub fn with_frame_relative(mut self, fr: bool) -> Self {
        self.is_frame_relative = fr;
        self
    }

    /// Set symbol reference.
    pub fn with_symbol(mut self, sym: &str) -> Self {
        self.symbol = Some(sym.to_string());
        self
    }

    /// Set GOT-relative flag (for PIC).
    pub fn with_got_relative(mut self, gr: bool) -> Self {
        self.is_got_relative = gr;
        self
    }

    // ---- Queries ----

    /// Whether this address has a base register.
    pub fn has_base(&self) -> bool {
        self.base.is_some()
    }

    /// Whether this address has an index register.
    pub fn has_index(&self) -> bool {
        self.index.is_some() && self.scale > 0
    }

    /// Whether the displacement is zero.
    pub fn has_disp_zero(&self) -> bool {
        self.displacement == 0
    }

    /// Whether the displacement fits in 8 bits (signed).
    pub fn fits_disp8(&self) -> bool {
        self.displacement >= -128 && self.displacement <= 127
    }

    /// Whether the displacement fits in 32 bits (signed).
    pub fn fits_disp32(&self) -> bool {
        self.displacement >= -2_147_483_648 && self.displacement <= 2_147_483_647
    }

    /// Whether the displacement fits in 16 bits (signed).
    pub fn fits_disp16(&self) -> bool {
        self.displacement >= -32_768 && self.displacement <= 32_767
    }

    /// Classify the addressing pattern.
    pub fn classify(&self) -> AddressingForm {
        if self.is_rip_relative {
            return AddressingForm::RipRelative;
        }
        if self.is_absolute_16 {
            return AddressingForm::Absolute16;
        }
        if self.is_absolute_32 {
            return AddressingForm::Absolute32;
        }
        match (self.has_base(), self.has_index(), self.has_disp_zero()) {
            (false, false, _) if self.displacement == 0 => AddressingForm::None,
            (false, false, _) => AddressingForm::Absolute32,
            (true, false, true) => AddressingForm::BaseOnly,
            (true, false, false) if self.fits_disp8() => AddressingForm::BaseDisp8,
            (true, false, false) => AddressingForm::BaseDisp32,
            (false, true, true) => AddressingForm::IndexScale,
            (false, true, false) => AddressingForm::IndexScaleDisp,
            (true, true, true) => AddressingForm::BaseIndexScale,
            (true, true, false) if self.fits_disp8() => AddressingForm::BaseIndexScaleDisp8,
            (true, true, false) => AddressingForm::BaseIndexScaleDisp32,
        }
    }

    /// Whether this address requires a SIB byte (32/64-bit mode).
    pub fn requires_sib(&self) -> bool {
        if !self.width.uses_sib() {
            return false;
        }
        if self.is_rip_relative || self.is_absolute_32 {
            return false;
        }
        if self.has_index() {
            return true;
        }
        // RSP/R12 as base requires SIB (r/m=4 encoding)
        if let Some(b) = self.base {
            let base_enc = b & 0x7;
            if base_enc == 4 {
                return true;
            }
            // RBP/R13 as base always requires SIB in 64-bit mode
            // (because mod=00 r/m=5 is RIP-relative, not [RBP])
            if base_enc == 5 && self.width == AddrWidth::Addr64 {
                return true;
            }
        }
        false
    }

    /// Whether this address requires a REX prefix (64-bit mode).
    pub fn requires_rex(&self) -> bool {
        if self.width != AddrWidth::Addr64 {
            return false;
        }
        // Check if any register requires extended bits (bit 3 set)
        if let Some(b) = self.base {
            if b >= 8 {
                return true;
            }
        }
        if let Some(i) = self.index {
            if i >= 8 {
                return true;
            }
        }
        false
    }

    /// Whether this is a special case requiring SIB with no index.
    /// Happens for [R12] (r/m=4, base=4 needs SIB) and
    /// [R13] (r/m=5, mod=00 is RIP-relative, so always needs SIB).
    pub fn is_special_sib_case(&self) -> bool {
        if !self.width.uses_sib() || self.has_index() {
            return false;
        }
        if let Some(b) = self.base {
            let enc = b & 0x7;
            enc == 4 || (enc == 5 && self.width == AddrWidth::Addr64 && !self.is_rip_relative)
        } else {
            false
        }
    }

    /// Compute the ModR/M byte for this addressing mode.
    /// Returns (mod_field, reg_or_ext, rm_field) tuple.
    pub fn compute_modrm_parts(&self) -> (u8, u8) {
        let (mod_field, rm_field): (u8, u8) = if self.is_rip_relative {
            // mod=00, r/m=5 → [RIP + disp32]
            (Mod00, 5)
        } else if self.is_absolute_32 {
            // mod=00, r/m=5 → [disp32] (32-bit mode) or [RIP + disp32] (64-bit mode)
            // In 32-bit mode: mod=00 r/m=5 = [disp32]
            // In 64-bit mode: mod=00 r/m=5 = [RIP + disp32], disp32 without base
            if self.width == AddrWidth::Addr64 {
                (Mod00, 5) // RIP-relative
            } else {
                (Mod00, 5) // absolute disp32
            }
        } else if self.is_absolute_16 {
            // mod=00, r/m=6 → [disp16]
            (Mod00, 6)
        } else if self.requires_sib() {
            // SIB required → r/m=4
            if self.has_disp_zero() {
                // No disp: mod=00
                (Mod00, 4)
            } else if self.fits_disp8() {
                (Mod01, 4)
            } else {
                (Mod10, 4)
            }
        } else if let Some(base) = self.base {
            let rm_enc: u8 = (base & 0x7) as u8;
            if self.has_disp_zero() && rm_enc != 5 {
                (Mod00, rm_enc)
            } else if self.has_disp_zero() && rm_enc == 5 {
                // [RBP] or [R13] with no disp — needs disp8=0
                // In 64-bit mode, this is handled by requires_sib above,
                // so we only reach here in 32-bit mode.
                (Mod01, rm_enc)
            } else if self.fits_disp8() {
                (Mod01, rm_enc)
            } else {
                (Mod10, rm_enc)
            }
        } else {
            // No base, no index → absolute addressing
            (Mod00, 5)
        };

        (mod_field, rm_field)
    }

    /// Compute the SIB byte for this addressing mode.
    /// Returns (scale_field, index_field, base_field) tuple.
    pub fn compute_sib_parts(&self) -> (u8, u8, u8) {
        let scale_field: u8 = match self.scale {
            2 => 1,
            4 => 2,
            8 => 3,
            _ => 0, // 1 or no scale
        };

        let index_field: u8 = if self.has_index() {
            (self.index.unwrap() & 0x7) as u8
        } else {
            4 // "no index" encoding
        };

        let base_field: u8 = if let Some(b) = self.base {
            (b & 0x7) as u8
        } else {
            5 // disp32 form (mod=00, base=5)
        };

        (scale_field, index_field, base_field)
    }

    /// Encode the full ModR/M byte.
    /// `reg_field` is the 3-bit register/opcode-extension for the reg field.
    pub fn encode_modrm(&self, reg_field: u8) -> u8 {
        let (mod_field, rm_field) = self.compute_modrm_parts();
        (mod_field << 6) | ((reg_field & 0x7) << 3) | (rm_field & 0x7)
    }

    /// Encode the full SIB byte.
    pub fn encode_sib(&self) -> u8 {
        let (scale, index, base) = self.compute_sib_parts();
        (scale << 6) | ((index & 0x7) << 3) | (base & 0x7)
    }

    /// Determine the displacement encoding size in bytes.
    pub fn displacement_size(&self) -> u8 {
        if self.has_disp_zero() && !self.is_special_disp8_zero_case() {
            0
        } else if self.fits_disp8() {
            1
        } else if self.fits_disp16() && self.width == AddrWidth::Addr16 {
            2
        } else {
            4
        }
    }

    /// Special case: RBP/R13 with no displacement needs disp8=0
    fn is_special_disp8_zero_case(&self) -> bool {
        if self.has_disp_zero() {
            if let Some(b) = self.base {
                let enc = b & 0x7;
                if enc == 5 {
                    // RBP with no displacement: needs mod≠00 in 32-bit,
                    // handled via SIB in 64-bit.
                    return self.width == AddrWidth::Addr32 && !self.requires_sib();
                }
            }
        }
        false
    }

    /// Encode displacement bytes (little-endian).
    pub fn encode_displacement(&self) -> Vec<u8> {
        let size = self.displacement_size();
        let disp = self.displacement;
        match size {
            0 => vec![],
            1 => vec![disp as u8],
            2 => vec![(disp & 0xFF) as u8, ((disp >> 8) & 0xFF) as u8],
            4 => vec![
                (disp & 0xFF) as u8,
                ((disp >> 8) & 0xFF) as u8,
                ((disp >> 16) & 0xFF) as u8,
                ((disp >> 24) & 0xFF) as u8,
            ],
            _ => vec![],
        }
    }

    /// Full encoding: ModR/M + SIB (if needed) + displacement bytes.
    /// `reg_field` is placed in the ModR/M reg field.
    pub fn encode_full(&self, reg_field: u8) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(6);
        bytes.push(self.encode_modrm(reg_field));
        if self.requires_sib() {
            bytes.push(self.encode_sib());
        }
        bytes.extend(self.encode_displacement());
        bytes
    }

    /// Whether this address can be folded into an LEA instruction.
    pub fn can_be_lea(&self) -> bool {
        // LEA requires a memory operand (not RIP-relative for address calcs).
        self.has_base() || self.has_index()
    }

    /// Whether this address is simple enough to be encoded without SIB.
    pub fn is_simple(&self) -> bool {
        !self.requires_sib()
    }

    /// Get the complexity score of this addressing mode.
    /// Higher scores indicate more complex addressing (more bytes, more cycles).
    pub fn complexity_score(&self) -> u32 {
        let mut score: u32 = 0;
        if self.has_base() {
            score += 1;
        }
        if self.has_index() {
            score += 2;
        }
        if self.scale > 1 {
            score += 1;
        }
        let disp_size = self.displacement_size();
        score += disp_size as u32;
        if self.requires_sib() {
            score += 1;
        }
        if self.requires_rex() {
            score += 1;
        }
        if self.segment.is_some() {
            score += 1;
        }
        if self.is_rip_relative {
            score += 1;
        }
        score
    }

    /// Convert this addressing mode to an X86MemOperand.
    pub fn to_mem_operand(&self) -> X86MemOperand {
        X86MemOperand {
            base: self.base.unwrap_or(0),
            index: self.index.unwrap_or(0),
            scale: self.scale,
            displacement: self.displacement as i32,
            segment: self.segment.unwrap_or(0),
        }
    }

    /// Convert from an X86MemOperand.
    pub fn from_mem_operand(mem: &X86MemOperand, width: AddrWidth) -> Self {
        Self {
            width,
            base: if mem.base != 0 { Some(mem.base) } else { None },
            index: if mem.index != 0 {
                Some(mem.index)
            } else {
                None
            },
            scale: mem.scale,
            displacement: mem.displacement as i64,
            segment: if mem.segment != 0 {
                Some(mem.segment)
            } else {
                None
            },
            ..Default::default()
        }
    }

    /// Compute hash key for deduplication.
    pub fn hash_key(&self) -> u64 {
        let mut key: u64 = (self.width as u64) << 56;
        if let Some(b) = self.base {
            key ^= (b as u64) << 8;
        }
        if let Some(i) = self.index {
            key ^= (i as u64) << 16;
        }
        key ^= (self.scale as u64) << 24;
        key ^= (self.displacement as u64).wrapping_mul(0x9E3779B97F4A7C15);
        if self.is_rip_relative {
            key ^= 1 << 63;
        }
        if let Some(seg) = self.segment {
            key ^= (seg as u64) << 40;
        }
        key
    }
}

// ============================================================================
// ModR/M Field Constants
// ============================================================================

/// Mod field values for ModR/M byte.
pub mod mod_field {
    /// mod=00: [reg] (r/m≠5), [disp32] (r/m=5 in 32-bit), [RIP+disp32] (r/m=5 in 64-bit)
    pub const MOD00: u8 = 0;
    /// mod=01: [reg + disp8]
    pub const MOD01: u8 = 1;
    /// mod=10: [reg + disp32]
    pub const MOD10: u8 = 2;
    /// mod=11: register-direct
    pub const MOD11: u8 = 3;
}

/// Convenience aliases for mod field values.
pub const Mod00: u8 = mod_field::MOD00;
pub const Mod01: u8 = mod_field::MOD01;
pub const Mod10: u8 = mod_field::MOD10;
pub const Mod11: u8 = mod_field::MOD11;

/// SIB scale field values.
pub mod sib_scale {
    pub const TIMES_1: u8 = 0;
    pub const TIMES_2: u8 = 1;
    pub const TIMES_4: u8 = 2;
    pub const TIMES_8: u8 = 3;
}

/// SIB constants.
pub mod sib_field {
    /// Special index value meaning "no index register".
    pub const NO_INDEX: u8 = 4;
    /// Special base value for disp32 form (mod=00, base=5).
    pub const DISP32_BASE: u8 = 5;
    /// RSP/R12 base encoding.
    pub const RSP_BASE: u8 = 4;
    /// RBP/R13 base encoding.
    pub const RBP_BASE: u8 = 5;
}

// ============================================================================
// 16-bit Addressing Form Enumeration
// ============================================================================

/// Enumeration of all valid 16-bit addressing forms.
///
/// In 16-bit mode (real mode, 16-bit protected mode), the ModR/M byte
/// encodes the effective address using a fixed table of register combinations.
/// No SIB byte is used. The displacement is always 0, 8, or 16 bits.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86Addr16Form {
    /// [BX + SI]
    BxSi,
    /// [BX + DI]
    BxDi,
    /// [BP + SI]
    BpSi,
    /// [BP + DI]
    BpDi,
    /// [SI]
    Si,
    /// [DI]
    Di,
    /// [BP] — note: [BP] without displacement defaults to [BP+0] (mod≠00)
    Bp,
    /// [BX]
    Bx,
    /// [BX + SI + disp8]
    BxSiDisp8,
    /// [BX + DI + disp8]
    BxDiDisp8,
    /// [BP + SI + disp8]
    BpSiDisp8,
    /// [BP + DI + disp8]
    BpDiDisp8,
    /// [SI + disp8]
    SiDisp8,
    /// [DI + disp8]
    DiDisp8,
    /// [BP + disp8]
    BpDisp8,
    /// [BX + disp8]
    BxDisp8,
    /// [BX + SI + disp16]
    BxSiDisp16,
    /// [BX + DI + disp16]
    BxDiDisp16,
    /// [BP + SI + disp16]
    BpSiDisp16,
    /// [BP + DI + disp16]
    BpDiDisp16,
    /// [SI + disp16]
    SiDisp16,
    /// [DI + disp16]
    DiDisp16,
    /// [BP + disp16]
    BpDisp16,
    /// [BX + disp16]
    BxDisp16,
    /// [disp16] — direct absolute address
    Disp16,
}

impl X86Addr16Form {
    /// Get the ModR/M r/m field value for this form (mod=00).
    pub fn rm_field(&self) -> u8 {
        match self {
            X86Addr16Form::BxSi => 0,
            X86Addr16Form::BxDi => 1,
            X86Addr16Form::BpSi => 2,
            X86Addr16Form::BpDi => 3,
            X86Addr16Form::Si => 4,
            X86Addr16Form::Di => 5,
            X86Addr16Form::Bp => 6,
            X86Addr16Form::Bx => 7,
            X86Addr16Form::BxSiDisp8 => 0,
            X86Addr16Form::BxDiDisp8 => 1,
            X86Addr16Form::BpSiDisp8 => 2,
            X86Addr16Form::BpDiDisp8 => 3,
            X86Addr16Form::SiDisp8 => 4,
            X86Addr16Form::DiDisp8 => 5,
            X86Addr16Form::BpDisp8 => 6,
            X86Addr16Form::BxDisp8 => 7,
            X86Addr16Form::BxSiDisp16 => 0,
            X86Addr16Form::BxDiDisp16 => 1,
            X86Addr16Form::BpSiDisp16 => 2,
            X86Addr16Form::BpDiDisp16 => 3,
            X86Addr16Form::SiDisp16 => 4,
            X86Addr16Form::DiDisp16 => 5,
            X86Addr16Form::BpDisp16 => 6,
            X86Addr16Form::BxDisp16 => 7,
            X86Addr16Form::Disp16 => 6,
        }
    }

    /// Get the Mod field for this form.
    pub fn mod_field(&self) -> u8 {
        match self {
            X86Addr16Form::BxSi
            | X86Addr16Form::BxDi
            | X86Addr16Form::BpSi
            | X86Addr16Form::BpDi
            | X86Addr16Form::Si
            | X86Addr16Form::Di
            | X86Addr16Form::Bx
            | X86Addr16Form::Disp16 => Mod00,
            X86Addr16Form::Bp => Mod01, // [BP] requires disp8=0
            X86Addr16Form::BxSiDisp8
            | X86Addr16Form::BxDiDisp8
            | X86Addr16Form::BpSiDisp8
            | X86Addr16Form::BpDiDisp8
            | X86Addr16Form::SiDisp8
            | X86Addr16Form::DiDisp8
            | X86Addr16Form::BpDisp8
            | X86Addr16Form::BxDisp8 => Mod01,
            X86Addr16Form::BxSiDisp16
            | X86Addr16Form::BxDiDisp16
            | X86Addr16Form::BpSiDisp16
            | X86Addr16Form::BpDiDisp16
            | X86Addr16Form::SiDisp16
            | X86Addr16Form::DiDisp16
            | X86Addr16Form::BpDisp16
            | X86Addr16Form::BxDisp16 => Mod10,
        }
    }

    /// Whether this form has a displacement.
    pub fn has_displacement(&self) -> bool {
        matches!(
            self,
            X86Addr16Form::BxSiDisp8
                | X86Addr16Form::BxDiDisp8
                | X86Addr16Form::BpSiDisp8
                | X86Addr16Form::BpDiDisp8
                | X86Addr16Form::SiDisp8
                | X86Addr16Form::DiDisp8
                | X86Addr16Form::BpDisp8
                | X86Addr16Form::BxDisp8
                | X86Addr16Form::BxSiDisp16
                | X86Addr16Form::BxDiDisp16
                | X86Addr16Form::BpSiDisp16
                | X86Addr16Form::BpDiDisp16
                | X86Addr16Form::SiDisp16
                | X86Addr16Form::DiDisp16
                | X86Addr16Form::BpDisp16
                | X86Addr16Form::BxDisp16
                | X86Addr16Form::Disp16
                | X86Addr16Form::Bp
        )
    }

    /// Size of displacement in bytes (0, 1, or 2).
    pub fn disp_size(&self) -> u8 {
        match self {
            X86Addr16Form::Bx
            | X86Addr16Form::BxSi
            | X86Addr16Form::BxDi
            | X86Addr16Form::BpSi
            | X86Addr16Form::BpDi
            | X86Addr16Form::Si
            | X86Addr16Form::Di => 0,
            X86Addr16Form::Bp
            | X86Addr16Form::BxSiDisp8
            | X86Addr16Form::BxDiDisp8
            | X86Addr16Form::BpSiDisp8
            | X86Addr16Form::BpDiDisp8
            | X86Addr16Form::SiDisp8
            | X86Addr16Form::DiDisp8
            | X86Addr16Form::BpDisp8
            | X86Addr16Form::BxDisp8 => 1,
            X86Addr16Form::BxSiDisp16
            | X86Addr16Form::BxDiDisp16
            | X86Addr16Form::BpSiDisp16
            | X86Addr16Form::BpDiDisp16
            | X86Addr16Form::SiDisp16
            | X86Addr16Form::DiDisp16
            | X86Addr16Form::BpDisp16
            | X86Addr16Form::BxDisp16
            | X86Addr16Form::Disp16 => 2,
        }
    }

    /// Get the effective base register for this form.
    pub fn effective_base(&self) -> Option<u16> {
        match self {
            X86Addr16Form::BxSi
            | X86Addr16Form::Bx
            | X86Addr16Form::BxSiDisp8
            | X86Addr16Form::BxDisp8
            | X86Addr16Form::BxSiDisp16
            | X86Addr16Form::BxDisp16 => Some(BX),
            X86Addr16Form::BxDi | X86Addr16Form::BxDiDisp8 | X86Addr16Form::BxDiDisp16 => Some(BX),
            X86Addr16Form::BpSi
            | X86Addr16Form::BpDi
            | X86Addr16Form::Bp
            | X86Addr16Form::BpSiDisp8
            | X86Addr16Form::BpDiDisp8
            | X86Addr16Form::BpDisp8
            | X86Addr16Form::BpSiDisp16
            | X86Addr16Form::BpDiDisp16
            | X86Addr16Form::BpDisp16 => Some(BP),
            X86Addr16Form::Si | X86Addr16Form::SiDisp8 | X86Addr16Form::SiDisp16 => Some(SI),
            X86Addr16Form::Di | X86Addr16Form::DiDisp8 | X86Addr16Form::DiDisp16 => Some(DI),
            X86Addr16Form::Disp16 => None,
        }
    }

    /// Get the effective index register for this form.
    pub fn effective_index(&self) -> Option<u16> {
        match self {
            X86Addr16Form::BxSi
            | X86Addr16Form::BpSi
            | X86Addr16Form::BxSiDisp8
            | X86Addr16Form::BpSiDisp8
            | X86Addr16Form::BxSiDisp16
            | X86Addr16Form::BpSiDisp16 => Some(SI),
            X86Addr16Form::BxDi
            | X86Addr16Form::BpDi
            | X86Addr16Form::BxDiDisp8
            | X86Addr16Form::BpDiDisp8
            | X86Addr16Form::BxDiDisp16
            | X86Addr16Form::BpDiDisp16 => Some(DI),
            _ => None,
        }
    }

    /// Human-readable name of this form.
    pub fn name(&self) -> &'static str {
        match self {
            X86Addr16Form::BxSi => "[BX+SI]",
            X86Addr16Form::BxDi => "[BX+DI]",
            X86Addr16Form::BpSi => "[BP+SI]",
            X86Addr16Form::BpDi => "[BP+DI]",
            X86Addr16Form::Si => "[SI]",
            X86Addr16Form::Di => "[DI]",
            X86Addr16Form::Bp => "[BP]",
            X86Addr16Form::Bx => "[BX]",
            X86Addr16Form::BxSiDisp8 => "[BX+SI+disp8]",
            X86Addr16Form::BxDiDisp8 => "[BX+DI+disp8]",
            X86Addr16Form::BpSiDisp8 => "[BP+SI+disp8]",
            X86Addr16Form::BpDiDisp8 => "[BP+DI+disp8]",
            X86Addr16Form::SiDisp8 => "[SI+disp8]",
            X86Addr16Form::DiDisp8 => "[DI+disp8]",
            X86Addr16Form::BpDisp8 => "[BP+disp8]",
            X86Addr16Form::BxDisp8 => "[BX+disp8]",
            X86Addr16Form::BxSiDisp16 => "[BX+SI+disp16]",
            X86Addr16Form::BxDiDisp16 => "[BX+DI+disp16]",
            X86Addr16Form::BpSiDisp16 => "[BP+SI+disp16]",
            X86Addr16Form::BpDiDisp16 => "[BP+DI+disp16]",
            X86Addr16Form::SiDisp16 => "[SI+disp16]",
            X86Addr16Form::DiDisp16 => "[DI+disp16]",
            X86Addr16Form::BpDisp16 => "[BP+disp16]",
            X86Addr16Form::BxDisp16 => "[BX+disp16]",
            X86Addr16Form::Disp16 => "[disp16]",
        }
    }

    /// Decode a 16-bit ModR/M byte into its addressing form.
    pub fn decode(modrm: u8) -> Self {
        let mod_field = (modrm >> 6) & 0x3;
        let rm_field = modrm & 0x7;
        match (mod_field, rm_field) {
            (0, 0) => X86Addr16Form::BxSi,
            (0, 1) => X86Addr16Form::BxDi,
            (0, 2) => X86Addr16Form::BpSi,
            (0, 3) => X86Addr16Form::BpDi,
            (0, 4) => X86Addr16Form::Si,
            (0, 5) => X86Addr16Form::Di,
            (0, 6) => X86Addr16Form::Disp16,
            (0, 7) => X86Addr16Form::Bx,
            (1, 0) => X86Addr16Form::BxSiDisp8,
            (1, 1) => X86Addr16Form::BxDiDisp8,
            (1, 2) => X86Addr16Form::BpSiDisp8,
            (1, 3) => X86Addr16Form::BpDiDisp8,
            (1, 4) => X86Addr16Form::SiDisp8,
            (1, 5) => X86Addr16Form::DiDisp8,
            (1, 6) => X86Addr16Form::BpDisp8,
            (1, 7) => X86Addr16Form::BxDisp8,
            (2, 0) => X86Addr16Form::BxSiDisp16,
            (2, 1) => X86Addr16Form::BxDiDisp16,
            (2, 2) => X86Addr16Form::BpSiDisp16,
            (2, 3) => X86Addr16Form::BpDiDisp16,
            (2, 4) => X86Addr16Form::SiDisp16,
            (2, 5) => X86Addr16Form::DiDisp16,
            (2, 6) => X86Addr16Form::BpDisp16,
            (2, 7) => X86Addr16Form::BxDisp16,
            (3, _) => X86Addr16Form::Bx, // reg-direct mode; shouldn't be used for memory
            _ => X86Addr16Form::BxSi,    // unreachable
        }
    }
}

// ============================================================================
// Addressing Form Classification
// ============================================================================

/// Classification of x86 addressing mode forms for 32/64-bit mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AddressingForm {
    /// No memory reference (register direct).
    None,
    /// [base] — base register only.
    BaseOnly,
    /// [base + disp8] — base register with 8-bit displacement.
    BaseDisp8,
    /// [base + disp32] — base register with 32-bit displacement.
    BaseDisp32,
    /// [index * scale] — index register scaled, no base.
    IndexScale,
    /// [index * scale + disp32] — index scaled with displacement, no base.
    IndexScaleDisp,
    /// [base + index * scale] — base + scaled index, no displacement.
    BaseIndexScale,
    /// [base + index * scale + disp8] — full addressing with 8-bit displacement.
    BaseIndexScaleDisp8,
    /// [base + index * scale + disp32] — full addressing with 32-bit displacement.
    BaseIndexScaleDisp32,
    /// [RIP + disp32] — RIP-relative (64-bit only).
    RipRelative,
    /// [disp16] — 16-bit absolute address.
    Absolute16,
    /// [disp32] — 32-bit absolute address.
    Absolute32,
}

impl AddressingForm {
    /// Get the number of ModR/M + SIB + displacement bytes for this form.
    pub fn encoding_overhead(&self) -> u8 {
        match self {
            AddressingForm::None => 0,
            AddressingForm::BaseOnly => 1,             // ModR/M only
            AddressingForm::BaseDisp8 => 2,            // ModR/M + disp8
            AddressingForm::BaseDisp32 => 5,           // ModR/M + disp32
            AddressingForm::IndexScale => 2,           // ModR/M + SIB
            AddressingForm::IndexScaleDisp => 6,       // ModR/M + SIB + disp32
            AddressingForm::BaseIndexScale => 2,       // ModR/M + SIB
            AddressingForm::BaseIndexScaleDisp8 => 3,  // ModR/M + SIB + disp8
            AddressingForm::BaseIndexScaleDisp32 => 6, // ModR/M + SIB + disp32
            AddressingForm::RipRelative => 5,          // ModR/M + disp32
            AddressingForm::Absolute16 => 3,           // ModR/M + disp16
            AddressingForm::Absolute32 => 5,           // ModR/M + disp32
        }
    }

    /// Whether this form uses a SIB byte.
    pub fn uses_sib(&self) -> bool {
        matches!(
            self,
            AddressingForm::IndexScale
                | AddressingForm::IndexScaleDisp
                | AddressingForm::BaseIndexScale
                | AddressingForm::BaseIndexScaleDisp8
                | AddressingForm::BaseIndexScaleDisp32
        )
    }

    /// Human-readable name.
    pub fn name(&self) -> &'static str {
        match self {
            AddressingForm::None => "none",
            AddressingForm::BaseOnly => "[base]",
            AddressingForm::BaseDisp8 => "[base+disp8]",
            AddressingForm::BaseDisp32 => "[base+disp32]",
            AddressingForm::IndexScale => "[index*scale]",
            AddressingForm::IndexScaleDisp => "[index*scale+disp32]",
            AddressingForm::BaseIndexScale => "[base+index*scale]",
            AddressingForm::BaseIndexScaleDisp8 => "[base+index*scale+disp8]",
            AddressingForm::BaseIndexScaleDisp32 => "[base+index*scale+disp32]",
            AddressingForm::RipRelative => "[rip+disp32]",
            AddressingForm::Absolute16 => "[disp16]",
            AddressingForm::Absolute32 => "[disp32]",
        }
    }
}

// ============================================================================
// 3. X86AddressingModeBuilder — fluent builder for address modes
// ============================================================================

/// Fluent builder for constructing X86 address modes with automatic
/// canonicalization, zero-folding, and complexity scoring.
///
/// # Examples
/// ```ignore
/// let mode = X86AddressingModeBuilder::new(AddrWidth::Addr64)
///     .with_base(RAX)
///     .with_index(RSI, 4)
///     .with_disp(16)
///     .build();
/// ```
#[derive(Debug, Clone)]
pub struct X86AddressingModeBuilder {
    width: AddrWidth,
    base: Option<u16>,
    index: Option<u16>,
    scale: u8,
    displacement: i64,
    segment: Option<u16>,
    is_rip_relative: bool,
    is_frame_relative: bool,
    symbol: Option<String>,
    is_got_relative: bool,
}

impl X86AddressingModeBuilder {
    /// Create a new builder for the given addressing width.
    pub fn new(width: AddrWidth) -> Self {
        Self {
            width,
            base: None,
            index: None,
            scale: 0,
            displacement: 0,
            segment: None,
            is_rip_relative: false,
            is_frame_relative: false,
            symbol: None,
            is_got_relative: false,
        }
    }

    /// Create a new builder for 64-bit mode.
    pub fn new64() -> Self {
        Self::new(AddrWidth::Addr64)
    }

    /// Create a new builder for 32-bit mode.
    pub fn new32() -> Self {
        Self::new(AddrWidth::Addr32)
    }

    /// Create a new builder for 16-bit mode.
    pub fn new16() -> Self {
        Self::new(AddrWidth::Addr16)
    }

    /// Set the base register.
    pub fn with_base(mut self, reg: u16) -> Self {
        self.base = Some(reg);
        self
    }

    /// Set the base register (optional).
    pub fn with_base_opt(mut self, reg: Option<u16>) -> Self {
        self.base = reg;
        self
    }

    /// Set the index register with its scale.
    pub fn with_index(mut self, reg: u16, scale: u8) -> Self {
        self.index = Some(reg);
        self.scale = Self::canonicalize_scale(scale);
        self
    }

    /// Set the index register (optional).
    pub fn with_index_opt(mut self, reg: Option<u16>, scale: u8) -> Self {
        self.index = reg;
        if reg.is_some() {
            self.scale = Self::canonicalize_scale(scale);
        } else {
            self.scale = 0;
        }
        self
    }

    /// Canonicalize scale to valid values: 1, 2, 4, or 8.
    fn canonicalize_scale(scale: u8) -> u8 {
        match scale {
            1 | 2 | 4 | 8 => scale,
            s if s < 2 => 1,
            s if s < 4 => 2,
            s if s < 8 => 4,
            _ => 8,
        }
    }

    /// Set the displacement.
    pub fn with_disp(mut self, disp: i64) -> Self {
        self.displacement = disp;
        self
    }

    /// Set segment override.
    pub fn with_segment(mut self, seg: u16) -> Self {
        self.segment = Some(seg);
        self
    }

    /// Mark as RIP-relative.
    pub fn with_rip_relative(mut self, rr: bool) -> Self {
        self.is_rip_relative = rr;
        if rr {
            // RIP-relative implies no base register
            self.base = None;
        }
        self
    }

    /// Mark as frame-relative.
    pub fn with_frame_relative(mut self, fr: bool) -> Self {
        self.is_frame_relative = fr;
        self
    }

    /// Set a symbol reference.
    pub fn with_symbol(mut self, sym: &str) -> Self {
        self.symbol = Some(sym.to_string());
        self
    }

    /// Mark as GOT-relative.
    pub fn with_got_relative(mut self, gr: bool) -> Self {
        self.is_got_relative = gr;
        self
    }

    /// Canonicalize the addressing mode:
    /// - Fold zero displacement (except special cases like RBP).
    /// - Remove index when scale is zero.
    /// - Promote 16-bit disp to 32-bit disp when out of range.
    /// - Fold zero scale.
    pub fn canonicalize(mut self) -> Self {
        // Remove index if scale is 0
        if self.index.is_some() && self.scale == 0 {
            self.index = None;
        }

        // Fold zero displacement when safe
        if self.displacement == 0 {
            // Check if zero displacement is valid for this form
            if let Some(base) = self.base {
                let base_enc: u8 = (base & 0x7) as u8;
                if base_enc == 5
                    && self.width == AddrWidth::Addr32
                    && !self.requires_sib_fast(base_enc)
                {
                    // [EBP] needs disp8=0, not disp=0
                    // Don't fold — keep disp=0 but mark it as disp8
                }
            }
        }

        // Ensure displacement fits in address width
        if self.displacement != 0 {
            match self.width {
                AddrWidth::Addr16 => {
                    if !(-32768..=32767).contains(&self.displacement) {
                        self.displacement &= 0xFFFF;
                        if self.displacement > 32767 {
                            self.displacement -= 65536;
                        }
                    }
                }
                _ => {
                    if !(-2_147_483_648i64..=2_147_483_647i64).contains(&self.displacement) {
                        self.displacement &= 0xFFFF_FFFF;
                        if self.displacement > 2_147_483_647 {
                            self.displacement -= 4_294_967_296;
                        }
                    }
                }
            }
        }

        self
    }

    /// Quick check if SIB is needed for a given base encoding.
    fn requires_sib_fast(&self, base_enc: u8) -> bool {
        base_enc == 4 || (base_enc == 5 && self.width == AddrWidth::Addr64 && !self.is_rip_relative)
    }

    /// Fold displacement into an offset from a specified base, converting
    /// a large displacement into base+displacement form.
    pub fn fold_displacement_into_base(mut self, base_reg: u16) -> Self {
        if self.base.is_none() {
            self.base = Some(base_reg);
        }
        self
    }

    /// Add an offset to the displacement.
    pub fn add_disp(mut self, offset: i64) -> Self {
        self.displacement = self.displacement.wrapping_add(offset);
        self.canonicalize()
    }

    /// Compute the complexity score of the resulting addressing mode.
    pub fn complexity_score(&self) -> u32 {
        let mut score: u32 = 0;
        if self.base.is_some() {
            score += 1;
        }
        if self.index.is_some() && self.scale > 0 {
            score += 2;
        }
        if self.scale > 1 {
            score += 1;
        }
        if self.displacement != 0 {
            if self.displacement >= -128 && self.displacement <= 127 {
                score += 1;
            } else {
                score += 4;
            }
        }
        if self.segment.is_some() {
            score += 1;
        }
        if self.is_rip_relative {
            score += 1;
        }
        score
    }

    /// Determine the best addressing form for the current configuration,
    /// selecting minimal encoding.
    pub fn select_best_form(&self) -> AddressingForm {
        if self.is_rip_relative {
            return AddressingForm::RipRelative;
        }
        match (self.base, self.index, self.scale > 0, self.displacement) {
            (None, None, _, 0) => AddressingForm::None,
            (None, None, _, _) if self.width == AddrWidth::Addr16 => AddressingForm::Absolute16,
            (None, None, _, _) => AddressingForm::Absolute32,
            (Some(_), None, _, 0) => AddressingForm::BaseOnly,
            (Some(_), None, _, d) if d >= -128 && d <= 127 => AddressingForm::BaseDisp8,
            (Some(_), None, _, _) => AddressingForm::BaseDisp32,
            (None, Some(_), true, 0) => AddressingForm::IndexScale,
            (None, Some(_), true, _) => AddressingForm::IndexScaleDisp,
            (Some(_), Some(_), true, 0) => AddressingForm::BaseIndexScale,
            (Some(_), Some(_), true, d) if d >= -128 && d <= 127 => {
                AddressingForm::BaseIndexScaleDisp8
            }
            (Some(_), Some(_), true, _) => AddressingForm::BaseIndexScaleDisp32,
            _ => AddressingForm::BaseOnly,
        }
    }

    /// Build the canonical X86AddressMode.
    pub fn build(mut self) -> X86AddressMode {
        self = self.canonicalize();
        let mut mode = X86AddressMode {
            width: self.width,
            base: self.base,
            index: self.index,
            scale: self.scale,
            displacement: self.displacement,
            segment: self.segment,
            is_rip_relative: self.is_rip_relative,
            is_frame_relative: self.is_frame_relative,
            symbol: self.symbol.clone(),
            is_got_relative: self.is_got_relative,
            ..Default::default()
        };

        // For 16-bit mode, determine the addressing form
        if self.width == AddrWidth::Addr16 {
            mode.form_16bit = self.determine_16bit_form();
            mode.is_absolute_16 = mode.form_16bit == Some(X86Addr16Form::Disp16);
        }

        if self.width == AddrWidth::Addr32 && self.base.is_none() && self.index.is_none() {
            mode.is_absolute_32 = self.displacement != 0;
        }

        mode
    }

    /// Determine the 16-bit addressing form from the current configuration.
    fn determine_16bit_form(&self) -> Option<X86Addr16Form> {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};

        let base = self.base;
        let index = self.index;
        let has_disp = self.displacement != 0;
        let disp8 = self.displacement >= -128 && self.displacement <= 127;

        match (base, index, has_disp, disp8) {
            (None, None, true, _) => Some(X86Addr16Form::Disp16),
            (None, None, false, _) => None,
            (Some(b), None, false, _) => match b {
                r if r == BX => Some(X86Addr16Form::Bx),
                r if r == BP => Some(X86Addr16Form::Bp),
                r if r == SI => Some(X86Addr16Form::Si),
                r if r == DI => Some(X86Addr16Form::Di),
                _ => None,
            },
            (Some(b), None, true, true) => match b {
                r if r == BX => Some(X86Addr16Form::BxDisp8),
                r if r == BP => Some(X86Addr16Form::BpDisp8),
                r if r == SI => Some(X86Addr16Form::SiDisp8),
                r if r == DI => Some(X86Addr16Form::DiDisp8),
                _ => None,
            },
            (Some(b), None, true, false) => match b {
                r if r == BX => Some(X86Addr16Form::BxDisp16),
                r if r == BP => Some(X86Addr16Form::BpDisp16),
                r if r == SI => Some(X86Addr16Form::SiDisp16),
                r if r == DI => Some(X86Addr16Form::DiDisp16),
                _ => None,
            },
            (Some(b), Some(i), false, _) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => Some(X86Addr16Form::BxSi),
                (b_val, i_val) if b_val == BX && i_val == DI => Some(X86Addr16Form::BxDi),
                (b_val, i_val) if b_val == BP && i_val == SI => Some(X86Addr16Form::BpSi),
                (b_val, i_val) if b_val == BP && i_val == DI => Some(X86Addr16Form::BpDi),
                _ => None,
            },
            (Some(b), Some(i), true, true) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => Some(X86Addr16Form::BxSiDisp8),
                (b_val, i_val) if b_val == BX && i_val == DI => Some(X86Addr16Form::BxDiDisp8),
                (b_val, i_val) if b_val == BP && i_val == SI => Some(X86Addr16Form::BpSiDisp8),
                (b_val, i_val) if b_val == BP && i_val == DI => Some(X86Addr16Form::BpDiDisp8),
                _ => None,
            },
            (Some(b), Some(i), true, false) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => Some(X86Addr16Form::BxSiDisp16),
                (b_val, i_val) if b_val == BX && i_val == DI => Some(X86Addr16Form::BxDiDisp16),
                (b_val, i_val) if b_val == BP && i_val == SI => Some(X86Addr16Form::BpSiDisp16),
                (b_val, i_val) if b_val == BP && i_val == DI => Some(X86Addr16Form::BpDiDisp16),
                _ => None,
            },
            _ => None,
        }
    }
}

// ============================================================================
// 4. X86MemoryLowering — Memory operation lowering
// ============================================================================

/// Lowers IR-level memory operations (load, store, frame index, global
/// address, TLS, constant pool) into X86 machine instructions with
/// proper addressing modes.
///
/// # Lowering Pipeline
/// ```text
/// IR Load  ──→ X86 MOV with [base+index*scale+disp]
/// IR Store ──→ X86 MOV with [base+index*scale+disp]
/// FrameIdx ──→ [RBP/RSP + offset]
/// Global   ──→ [RIP + offset] (PIC 64-bit) or [absolute] (non-PIC 32-bit)
/// TLS      ──→ [FS:offset] (64-bit) or [GS:offset] (32-bit)
/// ConstPool──→ [RIP + offset]
/// ```
#[derive(Debug, Clone)]
pub struct X86MemoryLowering {
    /// The addressing engine.
    pub engine: X86AddressingFull,
    /// Whether to use RBP or RSP for frame-relative addressing.
    pub use_frame_pointer: bool,
    /// Stack size for frame offset calculations.
    pub stack_size: i64,
    /// Base offset for local frame indices.
    pub frame_base_offset: i64,
    /// Whether 32-bit absolute addressing is available (non-PIC).
    pub use_absolute_addressing: bool,
}

impl X86MemoryLowering {
    /// Create a new memory lowering instance.
    pub fn new(engine: X86AddressingFull) -> Self {
        Self {
            engine,
            use_frame_pointer: true,
            stack_size: 0,
            frame_base_offset: 0,
            use_absolute_addressing: false,
        }
    }

    /// Create for 64-bit mode with PIC.
    pub fn new_x86_64_pic() -> Self {
        Self::new(X86AddressingFull::new_x86_64().with_pic(true))
    }

    /// Create for 64-bit mode without PIC.
    pub fn new_x86_64_non_pic() -> Self {
        let mut s = Self::new(X86AddressingFull::new_x86_64().with_pic(false));
        s.use_absolute_addressing = true;
        s
    }

    /// Create for 32-bit mode.
    pub fn new_x86_32() -> Self {
        Self::new(X86AddressingFull::new_x86_32().with_pic(false))
    }

    // ---- Load Lowering ----

    /// Lower an IR load of given size into an X86 memory load instruction.
    ///
    /// Returns the address mode for the memory operand. The caller is
    /// responsible for emitting the actual MOV instruction with the
    /// returned address mode.
    ///
    /// # Arguments
    /// * `addr` - The effective address to load from.
    /// * `size` - Size in bytes of the load (1, 2, 4, 8, 16, 32, 64).
    /// * `is_signed` - Whether to sign-extend (MOVSX) or zero-extend (MOVZX).
    /// * `dest_size` - Destination register size (for MOVSX/MOVZX).
    pub fn lower_load(
        &self,
        addr: &X86AddressMode,
        size: u8,
        is_signed: bool,
        dest_size: Option<u8>,
    ) -> LoadLoweringResult {
        let effective_addr = self.resolve_address(addr);
        let opcode = if size <= dest_size.unwrap_or(size) && dest_size.is_some() {
            if is_signed {
                match (size, dest_size.unwrap()) {
                    (1, 2) => X86Opcode::MOVSX,
                    (1, 4) => X86Opcode::MOVSX,
                    (1, 8) => X86Opcode::MOVSX,
                    (2, 4) => X86Opcode::MOVSX,
                    (2, 8) => X86Opcode::MOVSX,
                    (4, 8) => X86Opcode::MOVSXD,
                    _ => self.select_mov_opcode(size),
                }
            } else {
                match (size, dest_size.unwrap()) {
                    (1, 2) => X86Opcode::MOVZX,
                    (1, 4) => X86Opcode::MOVZX,
                    (1, 8) => X86Opcode::MOVZX,
                    (2, 4) => X86Opcode::MOVZX,
                    (2, 8) => X86Opcode::MOVZX,
                    _ => self.select_mov_opcode(size),
                }
            }
        } else {
            self.select_mov_opcode(size)
        };

        let needs_rex = effective_addr.requires_rex();
        let needs_sib = effective_addr.requires_sib();
        LoadLoweringResult {
            address_mode: effective_addr,
            opcode,
            size,
            needs_rex,
            needs_sib,
        }
    }

    /// Lower a simple load (MOV only, no sign/zero extension).
    pub fn lower_simple_load(&self, addr: &X86AddressMode, size: u8) -> LoadLoweringResult {
        let effective_addr = self.resolve_address(addr);
        let needs_rex = effective_addr.requires_rex();
        let needs_sib = effective_addr.requires_sib();
        LoadLoweringResult {
            opcode: self.select_mov_opcode(size),
            address_mode: effective_addr,
            size,
            needs_rex,
            needs_sib,
        }
    }

    /// Select the appropriate MOV opcode for a given data size.
    fn select_mov_opcode(&self, size: u8) -> X86Opcode {
        match size {
            1 => X86Opcode::MOV,          // MOV r8, m8
            2 => X86Opcode::MOV,          // MOV r16, m16
            4 => X86Opcode::MOV,          // MOV r32, m32
            8 => X86Opcode::MOV,          // MOV r64, m64
            16 => X86Opcode::VMOVDQA32_Z, // VMOVDQA xmm, m128
            32 => X86Opcode::VMOVDQA32_Z, // VMOVDQA ymm, m256
            64 => X86Opcode::VMOVDQA32_Z, // VMOVDQA zmm, m512
            _ => X86Opcode::MOV,
        }
    }

    // ---- Store Lowering ----

    /// Lower an IR store of given size into an X86 memory store instruction.
    pub fn lower_store(
        &self,
        addr: &X86AddressMode,
        size: u8,
        value_is_float: bool,
    ) -> StoreLoweringResult {
        let effective_addr = self.resolve_address(addr);
        let opcode = if value_is_float {
            match size {
                4 => X86Opcode::MOVSS,
                8 => X86Opcode::MOVSD,
                _ => self.select_mov_store_opcode(size),
            }
        } else {
            self.select_mov_store_opcode(size)
        };

        let needs_rex = effective_addr.requires_rex();
        let needs_sib = effective_addr.requires_sib();
        StoreLoweringResult {
            address_mode: effective_addr,
            opcode,
            size,
            needs_rex,
            needs_sib,
        }
    }

    fn select_mov_store_opcode(&self, size: u8) -> X86Opcode {
        match size {
            1 => X86Opcode::MOV,
            2 => X86Opcode::MOV,
            4 => X86Opcode::MOV,
            8 => X86Opcode::MOV,
            16 => X86Opcode::VMOVDQA32_Z,
            32 => X86Opcode::VMOVDQA32_Z,
            64 => X86Opcode::VMOVDQA32_Z,
            _ => X86Opcode::MOV,
        }
    }

    // ---- Frame Index Lowering ----

    /// Lower a frame index (stack slot) to a frame-relative address.
    ///
    /// Stack slot addresses are resolved as:
    /// - With frame pointer: [RBP/EBP - offset]
    /// - Without frame pointer: [RSP/ESP + offset]
    ///
    /// The offset depends on the frame layout, including:
    /// - Outgoing argument area
    /// - Local variable area
    /// - Callee-saved register spills
    /// - Call frame size
    pub fn lower_frame_index(&self, frame_index: i32, _size: u8) -> X86AddressMode {
        let offset = self.compute_frame_offset(frame_index);
        let (base_reg, is_neg) = if self.use_frame_pointer {
            match self.engine.addr_width {
                AddrWidth::Addr64 => (x86_register_info::RBP, true),
                AddrWidth::Addr32 => (x86_register_info::EBP, true),
                AddrWidth::Addr16 => (x86_register_info::BP, true),
            }
        } else {
            match self.engine.addr_width {
                AddrWidth::Addr64 => (x86_register_info::RSP, false),
                AddrWidth::Addr32 => (x86_register_info::ESP, false),
                AddrWidth::Addr16 => (x86_register_info::SP, false),
            }
        };

        let disp = if is_neg { -offset } else { offset };

        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base(base_reg)
            .with_disp(disp)
            .with_frame_relative(true)
            .build()
    }

    /// Compute the byte offset for a given frame index.
    fn compute_frame_offset(&self, frame_index: i32) -> i64 {
        // Simplified frame layout:
        // - Negative frame indices: local variables below frame pointer
        // - Positive: incoming arguments above frame pointer
        let base = if frame_index < 0 {
            // Local variable: [RBP - offset]
            self.frame_base_offset + (-frame_index as i64 * 8) + 8
        } else {
            // Incoming argument: [RBP + offset]
            (frame_index as i64 + 2) * 8
        };
        base
    }

    // ---- Global Address Lowering ----

    /// Lower a global symbol reference into the appropriate addressing mode.
    ///
    /// # 64-bit PIC (small code model)
    /// Uses RIP-relative: `[RIP + symbol - .]`
    ///
    /// # 64-bit non-PIC
    /// Uses MOVABS: `movabs rax, symbol` then `mov ..., [rax]`
    /// or absolute addressing if within 2GB.
    ///
    /// # 32-bit
    /// Uses absolute addressing: `[symbol]` (or GOT-relative for PIC).
    ///
    /// # 16-bit
    /// Uses 16-bit absolute or segment:offset addressing.
    pub fn lower_global_address(
        &self,
        symbol: &str,
        offset: i64,
        is_external: bool,
    ) -> X86AddressMode {
        match self.engine.addr_width {
            AddrWidth::Addr64 => {
                if self.engine.is_pic {
                    // RIP-relative: [RIP + symbol + offset]
                    X86AddressMode::rip_symbol(symbol, offset).with_got_relative(is_external)
                } else if self.engine.code_model == CodeModel::Small {
                    // Non-PIC small: [RIP + symbol + offset] or [abs]
                    X86AddressMode::rip_symbol(symbol, offset)
                } else {
                    // Large/Medium: absolute via movabs
                    // Represent as symbol without RIP-relative
                    X86AddressMode {
                        width: AddrWidth::Addr64,
                        displacement: offset,
                        symbol: Some(symbol.to_string()),
                        is_absolute_32: true,
                        ..Default::default()
                    }
                }
            }
            AddrWidth::Addr32 => {
                if self.engine.is_pic {
                    // GOT-relative: [symbol@GOT]
                    X86AddressMode {
                        width: AddrWidth::Addr32,
                        displacement: offset,
                        symbol: Some(format!("{}@GOT", symbol)),
                        is_got_relative: true,
                        ..Default::default()
                    }
                } else {
                    // Absolute: [symbol]
                    X86AddressMode {
                        width: AddrWidth::Addr32,
                        displacement: offset,
                        symbol: Some(symbol.to_string()),
                        is_absolute_32: true,
                        ..Default::default()
                    }
                }
            }
            AddrWidth::Addr16 => {
                // 16-bit absolute or segment:offset
                X86AddressMode {
                    width: AddrWidth::Addr16,
                    displacement: offset,
                    symbol: Some(symbol.to_string()),
                    is_absolute_16: true,
                    ..Default::default()
                }
            }
        }
    }

    /// Lower a global address to a GOT entry (PIC).
    /// Emits `mov reg, [RIP + symbol@GOTPCREL]`.
    pub fn lower_global_got(&self, symbol: &str) -> X86AddressMode {
        X86AddressMode {
            width: AddrWidth::Addr64,
            displacement: 0,
            is_rip_relative: true,
            symbol: Some(format!("{}@GOTPCREL", symbol)),
            is_got_relative: true,
            ..Default::default()
        }
    }

    // ---- TLS Address Lowering ----

    /// Lower a thread-local storage address.
    ///
    /// # TLS Models
    /// - **Local Exec**: `mov reg, [FS:offset]` or `mov reg, [GS:offset]`
    ///   (fastest, thread pointer at FS/GS base)
    /// - **Initial Exec**: `mov reg, [FS:symbol@TPOFF]` — TLS block in GOT
    /// - **General Dynamic**: `call __tls_get_addr` — full dynamic TLS resolution
    /// - **Local Dynamic**: Optimized GD for module-local TLS
    ///
    /// # Register Convention
    /// - 64-bit: FS segment base points to the thread control block (Linux)
    /// - 32-bit: GS segment base (Linux) or FS (Windows)
    /// - OS X / macOS: GS base (set via MSR)
    pub fn lower_tls_address(&self, symbol: &str, offset: i64, is_local: bool) -> X86AddressMode {
        let segment = self.get_tls_segment_reg();

        match self.engine.tls_model {
            TlsModel::LocalExec => {
                // Local exec: direct FS/GS:offset access
                X86AddressingModeBuilder::new(self.engine.addr_width)
                    .with_disp(offset)
                    .with_segment(segment)
                    .with_symbol(symbol)
                    .build()
            }
            TlsModel::InitialExec => {
                // Initial exec: load GOT entry via RIP-relative,
                // then use the loaded address as base
                X86AddressMode {
                    width: self.engine.addr_width,
                    displacement: offset,
                    segment: Some(segment),
                    symbol: Some(format!("{}@TPOFF", symbol)),
                    is_got_relative: true,
                    ..Default::default()
                }
            }
            TlsModel::GeneralDynamic => {
                // General dynamic: requires __tls_get_addr call
                // Represent as: lea rdi, [RIP + symbol@TLSGD] ; call __tls_get_addr
                X86AddressMode {
                    width: self.engine.addr_width,
                    symbol: Some(format!("{}@TLSGD", symbol)),
                    is_rip_relative: true,
                    ..Default::default()
                }
            }
            TlsModel::LocalDynamic => {
                // Local dynamic: lea rdi, [RIP + symbol@TLSLD] ; call __tls_get_addr
                X86AddressMode {
                    width: self.engine.addr_width,
                    symbol: Some(format!("{}@TLSLD", symbol)),
                    is_rip_relative: true,
                    ..Default::default()
                }
            }
        }
    }

    /// Get the segment register used for TLS (FS on Linux x86-64, GS on 32-bit).
    fn get_tls_segment_reg(&self) -> u16 {
        match self.engine.addr_width {
            AddrWidth::Addr64 => {
                // Linux x86-64: FS for TLS
                // macOS x86-64: GS for TLS
                // For portable code, typically FS is the convention
                x86_register_info::FS
            }
            AddrWidth::Addr32 => {
                // 32-bit Linux: GS for TLS
                x86_register_info::GS
            }
            AddrWidth::Addr16 => {
                // 16-bit: no standard TLS
                0
            }
        }
    }

    // ---- Constant Pool Lowering ----

    /// Lower a constant pool reference.
    ///
    /// Constants are placed in a read-only data section and accessed via
    /// RIP-relative addressing (64-bit) or absolute (32-bit).
    pub fn lower_constant_pool(&self, pool_index: u32, offset: i64) -> X86AddressMode {
        let label = format!(".LCPI{}", pool_index);
        if self.engine.addr_width == AddrWidth::Addr64 {
            // RIP-relative to the constant pool entry
            X86AddressMode::rip_symbol(&label, offset)
        } else {
            // 32-bit absolute reference
            X86AddressMode {
                width: AddrWidth::Addr32,
                displacement: offset,
                symbol: Some(label),
                is_absolute_32: true,
                ..Default::default()
            }
        }
    }

    /// Lower a jump table reference (switch lowering).
    pub fn lower_jump_table(&self, table_index: u32, offset: i64) -> X86AddressMode {
        let label = format!(".LJTI{}", table_index);
        if self.engine.addr_width == AddrWidth::Addr64 {
            X86AddressMode::rip_symbol(&label, offset)
        } else {
            X86AddressMode {
                width: AddrWidth::Addr32,
                displacement: offset,
                symbol: Some(label),
                is_absolute_32: true,
                ..Default::default()
            }
        }
    }

    // ---- Address Resolution ----

    /// Resolve an address mode by applying the current addressing context
    /// (frame pointer offset, code model, etc.).
    fn resolve_address(&self, addr: &X86AddressMode) -> X86AddressMode {
        let mut resolved = addr.clone();

        // If this is a frame-relative address, adjust for the frame base offset
        if addr.is_frame_relative {
            resolved.displacement += self.frame_base_offset;
        }

        // For global symbols in PIC mode, ensure GOT-relative flag is set
        if addr.symbol.is_some() && self.engine.is_pic && addr.width == AddrWidth::Addr64 {
            if !addr.is_got_relative && !addr.is_rip_relative {
                resolved.is_got_relative = true;
            }
        }

        resolved
    }
}

// ============================================================================
// Memory Lowering Result Types
// ============================================================================

/// Result of lowering an IR load operation.
#[derive(Debug, Clone)]
pub struct LoadLoweringResult {
    /// The resolved addressing mode for the memory operand.
    pub address_mode: X86AddressMode,
    /// The X86 opcode for the load instruction.
    pub opcode: X86Opcode,
    /// Size of the load in bytes.
    pub size: u8,
    /// Whether REX prefix is needed.
    pub needs_rex: bool,
    /// Whether SIB byte is needed.
    pub needs_sib: bool,
}

/// Result of lowering an IR store operation.
#[derive(Debug, Clone)]
pub struct StoreLoweringResult {
    /// The resolved addressing mode for the memory operand.
    pub address_mode: X86AddressMode,
    /// The X86 opcode for the store instruction.
    pub opcode: X86Opcode,
    /// Size of the store in bytes.
    pub size: u8,
    /// Whether REX prefix is needed.
    pub needs_rex: bool,
    /// Whether SIB byte is needed.
    pub needs_sib: bool,
}

// ============================================================================
// 5. X86AddressOptimization — Address mode optimization
// ============================================================================

/// Optimizes X86 address computations by:
/// 1. **LEA formation**: Converting `add + shift` patterns into LEA with scale.
/// 2. **Address sinking**: Pushing address computation closer to the memory use.
/// 3. **Common base/index factoring**: Sharing base registers across accesses.
/// 4. **Loop invariant hoisting**: Moving address calculations out of loops.
///
/// # LEA Formation
/// ```text
/// Instead of:   lea rax, [rbx + 4*rcx + 8]
///               OR:   mov rax, rbx ; shl rcx, 2 ; add rax, rcx ; add rax, 8
/// Emit:         lea rax, [rbx + rcx*4 + 8]
/// ```
///
/// LEA avoids using the ALU and does not modify flags — it's a pure
/// address calculation in the AGU (Address Generation Unit).
#[derive(Debug, Clone)]
pub struct X86AddressOptimization {
    engine: X86AddressingFull,
    /// Whether to optimize for size (-Os).
    optimize_for_size: bool,
    /// Whether LEA formation is enabled.
    enable_lea_formation: bool,
    /// Whether address sinking is enabled.
    enable_sinking: bool,
    /// Whether base/index factoring is enabled.
    enable_factoring: bool,
    /// Whether loop-invariant hoisting is enabled.
    enable_hoisting: bool,
    /// Maximum number of instructions to search back for sinking.
    max_sink_distance: usize,
}

impl X86AddressOptimization {
    /// Create a new optimizer.
    pub fn new(engine: X86AddressingFull) -> Self {
        Self {
            engine,
            optimize_for_size: false,
            enable_lea_formation: true,
            enable_sinking: true,
            enable_factoring: true,
            enable_hoisting: true,
            max_sink_distance: 4,
        }
    }

    /// Set optimization for size.
    pub fn with_size_opt(mut self, size_opt: bool) -> Self {
        self.optimize_for_size = size_opt;
        self
    }

    /// Disable LEA formation.
    pub fn without_lea_formation(mut self) -> Self {
        self.enable_lea_formation = false;
        self
    }

    // ---- LEA Formation ----

    /// Try to form an LEA instruction from an ADD operation.
    ///
    /// Recognizes patterns like:
    /// - `add reg, reg` → `lea reg, [reg + reg]`
    /// - `add reg, imm` → `lea reg, [reg + imm]`
    /// - `lea reg, [reg + reg*n]` (existing)
    ///
    /// Returns Some(LEA address mode) if LEA can be formed, None otherwise.
    pub fn try_form_lea(
        &self,
        opcode: X86Opcode,
        dst: u16,
        src1: u16,
        src2: Option<u64>,
    ) -> Option<X86AddressMode> {
        if !self.enable_lea_formation {
            return None;
        }

        match opcode {
            X86Opcode::ADD | X86Opcode::SUB => {
                // Case 1: ADD dst, src → try LEA dst, [dst + src]
                if src2.is_none() {
                    // reg + reg form
                    return Some(
                        X86AddressingModeBuilder::new(self.engine.addr_width)
                            .with_base(dst)
                            .with_index(src1, 1)
                            .build(),
                    );
                }
                // Case 2: ADD dst, imm → try LEA dst, [dst + imm]
                let imm = src2.unwrap() as i64;
                let scaled_imm = if opcode == X86Opcode::SUB { -imm } else { imm };
                return Some(
                    X86AddressingModeBuilder::new(self.engine.addr_width)
                        .with_base(dst)
                        .with_disp(scaled_imm)
                        .build(),
                );
            }
            X86Opcode::SHL => {
                // SHL reg, shift → can be combined with base in LEA
                if let Some(shift) = src2 {
                    let scale = 1u8 << shift;
                    if scale == 2 || scale == 4 || scale == 8 {
                        return Some(
                            X86AddressingModeBuilder::new(self.engine.addr_width)
                                .with_base(dst)
                                .with_index(src1, scale)
                                .build(),
                        );
                    }
                }
            }
            X86Opcode::MUL | X86Opcode::IMUL => {
                // IMUL reg, imm → can be LEA [reg + reg*(imm-1)]
                // But this is complex; skip for now
                return None;
            }
            _ => {}
        }

        None
    }

    /// Form complex LEA from a chain of ADD/MUL operations.
    ///
    /// This recognizes patterns spanning multiple instructions:
    /// ```text
    /// shl reg, 3        ; reg *= 8
    /// add base, reg     ; base += reg
    /// add base, disp    ; base += disp
    /// → lea base, [base + reg*8 + disp]
    /// ```
    pub fn try_form_complex_lea(
        &self,
        base: u16,
        index: u16,
        scale: u8,
        displacement: i64,
    ) -> Option<X86AddressMode> {
        if !self.enable_lea_formation {
            return None;
        }

        // Check if the scale is valid for LEA
        if scale != 1 && scale != 2 && scale != 4 && scale != 8 {
            return None;
        }

        let disp_fits = displacement >= -2_147_483_648 && displacement <= 2_147_483_647;

        if !disp_fits {
            return None;
        }

        Some(
            X86AddressingModeBuilder::new(self.engine.addr_width)
                .with_base(base)
                .with_index(index, scale)
                .with_disp(displacement)
                .build(),
        )
    }

    /// Determine if using LEA is better than separate ADD instructions.
    pub fn should_use_lea(&self, _addr_mode: &X86AddressMode, num_adds: usize) -> bool {
        if !self.enable_lea_formation {
            return false;
        }

        if self.optimize_for_size {
            // LEA is 1 byte longer than ADD reg,reg but shorter than multiple ADDs
            return num_adds >= 2;
        }

        // For performance: LEA has 1 cycle latency on most modern CPUs,
        // while ADD has 1 cycle. But LEA avoids modifying flags.
        // Prefer LEA when it saves at least one instruction.
        num_adds >= 2
    }

    // ---- Address Sinking ----

    /// Compute the "sink distance" — how many instructions an address
    /// computation can be sunk toward its use.
    ///
    /// Address sinking moves the address computation closer to the memory
    /// reference. This can reduce register pressure by shortening the live
    /// range of temporary registers used in address computation.
    pub fn compute_sink_distance(
        &self,
        addr_mode: &X86AddressMode,
        num_intervening_uses: usize,
    ) -> usize {
        if !self.enable_sinking {
            return 0;
        }

        // Only sink if there are intervening instructions that don't use the address
        if num_intervening_uses == 0 {
            return 0;
        }

        // Don't sink too far — limits register pressure impact
        let max_dist = self.max_sink_distance;
        let complexity = addr_mode.complexity_score();

        // Simpler addresses can be sunk further (less register pressure)
        if complexity <= 2 {
            max_dist
        } else if complexity <= 4 {
            max_dist / 2
        } else {
            0 // Complex addresses shouldn't be sunk
        }
    }

    /// Check if an address computation can be sunk to the given position.
    pub fn can_sink_to(&self, addr_mode: &X86AddressMode, is_in_loop: bool) -> bool {
        if !self.enable_sinking {
            return false;
        }

        if !is_in_loop {
            return false;
        }

        // Don't sink frame-relative or global addresses
        if addr_mode.is_frame_relative || addr_mode.symbol.is_some() {
            return false;
        }

        // Simple address computations can be sunk
        addr_mode.complexity_score() <= 3
    }

    // ---- Common Base/Index Factoring ----

    /// Factor common base registers across multiple memory accesses.
    ///
    /// Given a set of addresses all using the same base register,
    /// emit a single base computation and reuse it.
    ///
    /// # Example
    /// ```text
    /// Before:
    ///     mov eax, [rbx + 0]
    ///     mov ecx, [rbx + 4]
    ///     mov edx, [rbx + 8]
    ///
    /// After (factored):
    ///     lea rsi, [rbx]         ; base factored out
    ///     mov eax, [rsi + 0]
    ///     mov ecx, [rsi + 4]
    ///     mov edx, [rsi + 8]
    /// ```
    pub fn factor_common_base(
        &self,
        addresses: &[X86AddressMode],
    ) -> (Option<u16>, Vec<X86AddressMode>) {
        if !self.enable_factoring || addresses.is_empty() {
            return (None, addresses.to_vec());
        }

        // Find the most common base register
        let mut base_counts: HashMap<u16, usize> = HashMap::new();
        for addr in addresses {
            if let Some(base) = addr.base {
                *base_counts.entry(base).or_insert(0) += 1;
            }
        }

        // Only factor if a base appears at least 2 times and in >50% of addresses
        let threshold = (addresses.len() + 1) / 2;
        let mut best_base: Option<u16> = None;
        let mut best_count: usize = 0;

        for (base, count) in &base_counts {
            if *count > best_count && *count >= 2 && *count >= threshold {
                best_count = *count;
                best_base = Some(*base);
            }
        }

        if let Some(common_base) = best_base {
            // Rebase all addresses to the common base
            let new_addresses: Vec<X86AddressMode> = addresses
                .iter()
                .map(|addr| {
                    let mut new_addr = addr.clone();
                    if new_addr.base == Some(common_base) {
                        // Keep the base; these addresses share it
                    } else if new_addr.base.is_some() {
                        // Different base — compute relative offset
                        // This is simplified; real implementation would need
                        // to track actual offsets
                    }
                    new_addr
                })
                .collect();
            (Some(common_base), new_addresses)
        } else {
            (None, addresses.to_vec())
        }
    }

    /// Factor common index registers across multiple memory accesses.
    pub fn factor_common_index(
        &self,
        addresses: &[X86AddressMode],
    ) -> (Option<(u16, u8)>, Vec<X86AddressMode>) {
        if !self.enable_factoring || addresses.is_empty() {
            return (None, addresses.to_vec());
        }

        let mut index_counts: HashMap<(u16, u8), usize> = HashMap::new();
        for addr in addresses {
            if let Some(index) = addr.index {
                if addr.scale > 0 {
                    *index_counts.entry((index, addr.scale)).or_insert(0) += 1;
                }
            }
        }

        let threshold = (addresses.len() + 1) / 2;
        let mut best_index: Option<(u16, u8)> = None;
        let mut best_count: usize = 0;

        for (idx, count) in &index_counts {
            if *count > best_count && *count >= 2 && *count >= threshold {
                best_count = *count;
                best_index = Some(*idx);
            }
        }

        (best_index, addresses.to_vec())
    }

    // ---- Loop Invariant Address Hoisting ----

    /// Check if an address computation is loop-invariant and can be hoisted.
    ///
    /// Loop-invariant address computations produce the same value on every
    /// iteration. Hoisting them out of the loop reduces the number of
    /// address calculations performed.
    pub fn is_loop_invariant(&self, addr_mode: &X86AddressMode) -> bool {
        // Frame-relative and global addresses are invariant by definition
        if addr_mode.is_frame_relative || addr_mode.symbol.is_some() {
            return true;
        }

        // Absolute addresses are invariant
        if addr_mode.is_absolute_16 || addr_mode.is_absolute_32 || addr_mode.is_rip_relative {
            return true;
        }

        // Simple base+disp with no index is invariant if the base is
        // a frame/stack pointer
        if !addr_mode.has_index() {
            if let Some(base) = addr_mode.base {
                let base_enc = base & 0x7;
                // RSP/RBP/ESP/EBP are typically loop-invariant
                if base_enc == 4 || base_enc == 5 {
                    return true;
                }
            }
        }

        false
    }

    /// Hoist a loop-invariant address computation.
    ///
    /// Returns the new address mode to be computed before the loop.
    pub fn hoist_address(&self, addr_mode: &X86AddressMode) -> Option<X86AddressMode> {
        if !self.enable_hoisting {
            return None;
        }

        if self.is_loop_invariant(addr_mode) {
            // Pre-compute the effective address into a register
            // The caller is responsible for emitting the LEA before the loop
            Some(addr_mode.clone())
        } else {
            None
        }
    }

    // ---- General Optimization ----

    /// Optimize an addressing mode for minimal encoding overhead.
    ///
    /// This is the main entry point for address optimization.
    pub fn optimize(&self, addr_mode: &X86AddressMode) -> X86AddressMode {
        let mut optimized = addr_mode.clone();

        // 1. Fold zero displacement
        optimized = self.fold_zero_disp(optimized);

        // 2. Try to use 8-bit displacement
        optimized = self.try_disp8(optimized);

        // 3. Canonicalize the form
        optimized = self.canonicalize_form(optimized);

        optimized
    }

    /// Fold a zero displacement when possible.
    fn fold_zero_disp(&self, addr: X86AddressMode) -> X86AddressMode {
        if addr.displacement == 0 && !addr.is_rip_relative {
            // Check if zero displacement is valid
            if let Some(base) = addr.base {
                let base_enc = base & 0x7;
                if base_enc == 5 && addr.width == AddrWidth::Addr32 && !addr.requires_sib() {
                    // [EBP] needs mod≠00, so keep disp=0 but use mod=01
                    // No change needed — caller handles this
                }
            }
        }
        addr
    }

    /// Try to reduce a 32-bit displacement to 8-bit.
    fn try_disp8(&self, addr: X86AddressMode) -> X86AddressMode {
        if addr.displacement == 0 {
            return addr;
        }
        if addr.fits_disp8() {
            // Already fits; no change needed
            return addr;
        }
        // Cannot reduce if displacement is >127 or <-128
        addr
    }

    /// Canonicalize the addressing form for minimal encoding.
    fn canonicalize_form(&self, addr: X86AddressMode) -> X86AddressMode {
        // Remove index if scale is 0
        if addr.scale == 0 && addr.index.is_some() {
            let mut a = addr;
            a.index = None;
            return a;
        }
        addr
    }

    /// Compare two addressing modes and choose the better one.
    ///
    /// # Selection criteria (in order):
    /// 1. Smaller encoding (fewer bytes)
    /// 2. Lower complexity score
    /// 3. No REX prefix preferred (in 64-bit mode with low registers)
    /// 4. No SIB byte preferred
    pub fn select_best(&self, a: &X86AddressMode, b: &X86AddressMode) -> X86AddressMode {
        let form_a = a.classify();
        let form_b = b.classify();

        let overhead_a = form_a.encoding_overhead();
        let overhead_b = form_b.encoding_overhead();

        if overhead_a < overhead_b {
            return a.clone();
        }
        if overhead_b < overhead_a {
            return b.clone();
        }

        let score_a = a.complexity_score();
        let score_b = b.complexity_score();

        if score_a <= score_b {
            a.clone()
        } else {
            b.clone()
        }
    }
}

// ============================================================================
// 6. X86SegmentHandling — Segment register handling
// ============================================================================

/// Handles segment register overrides for X86 addressing.
///
/// # Segment Registers
/// - **CS** (Code Segment): Instruction fetches
/// - **DS** (Data Segment): Default for most data accesses
/// - **SS** (Stack Segment): Default for stack operations (ESP/RSP, EBP/RBP base)
/// - **ES** (Extra Segment): String operations destination
/// - **FS** (General-purpose): TLS base on Linux x86-64, OS-internal data on Windows
/// - **GS** (General-purpose): TLS base on Linux x86-32, CPU-local data
///
/// # Segment Override Prefixes
/// - `0x2E` — CS segment override
/// - `0x36` — SS segment override
/// - `0x3E` — DS segment override
/// - `0x26` — ES segment override
/// - `0x64` — FS segment override
/// - `0x65` — GS segment override
///
/// # Default Segment Selection
/// The default segment is determined by the base register:
/// - RSP/RBP/ESP/EBP/SP/BP → SS (stack segment)
/// - RIP/EIP/IP → CS (code segment)
/// - All others → DS (data segment)
///
/// # 64-bit Mode Simplification
/// In 64-bit mode (long mode), segmentation is largely disabled:
/// - CS, DS, ES, SS base addresses are forced to 0
/// - FS and GS are the only segments with programmable bases
/// - Segment override prefixes for CS/DS/ES/SS are generally ignored
///   (except for string instructions)
#[derive(Debug, Clone)]
pub struct X86SegmentHandling {
    /// The addressing engine.
    engine: X86AddressingFull,
    /// Whether this is 64-bit mode (segmentation mostly disabled).
    is_64bit: bool,
    /// Default data segment.
    default_ds: u16,
    /// Thread-local segment.
    tls_segment: u16,
}

impl X86SegmentHandling {
    /// Create a new segment handler.
    pub fn new(engine: X86AddressingFull) -> Self {
        let is_64bit = engine.addr_width == AddrWidth::Addr64;
        let (default_ds, tls_segment) = if is_64bit {
            (x86_register_info::DS, x86_register_info::FS)
        } else {
            (x86_register_info::DS, x86_register_info::GS)
        };
        Self {
            engine,
            is_64bit,
            default_ds,
            tls_segment,
        }
    }

    // ---- Segment Selection ----

    /// Determine the default segment for a given base register.
    ///
    /// - Stack operations (RSP, RBP, ESP, EBP, SP, BP) → SS
    /// - Instruction fetches (RIP, EIP, IP) → CS
    /// - String destination (EDI, DI) → ES
    /// - All others → DS
    pub fn default_segment_for_base(&self, base: u16) -> u16 {
        use crate::x86::x86_register_info::{BP, DI, EBP, EDI, EIP, ESP, RBP, RIP, RSP, SP};
        match base {
            r if r == RSP || r == RBP || r == ESP || r == EBP || r == SP || r == BP => {
                x86_register_info::SS
            }
            r if r == RIP || r == EIP => x86_register_info::CS,
            r if r == DI || r == EDI => x86_register_info::ES,
            _ => x86_register_info::DS,
        }
    }

    /// Determine the default segment for an address mode.
    pub fn default_segment(&self, addr: &X86AddressMode) -> u16 {
        if let Some(base) = addr.base {
            self.default_segment_for_base(base)
        } else {
            // Absolute addresses default to DS
            x86_register_info::DS
        }
    }

    /// Check if a segment override is needed for the given address mode.
    pub fn needs_segment_override(&self, addr: &X86AddressMode) -> bool {
        if let Some(seg) = addr.segment {
            let default = self.default_segment(addr);
            seg != default
        } else {
            false
        }
    }

    /// Get the segment override prefix byte for a given segment register.
    ///
    /// Returns the prefix byte (e.g., 0x64 for FS) or None if no override needed.
    pub fn segment_override_prefix(&self, addr: &X86AddressMode) -> Option<u8> {
        if !self.needs_segment_override(addr) {
            return None;
        }
        let seg = addr.segment?;
        Some(self.encode_segment_prefix(seg))
    }

    /// Encode a segment register to its override prefix byte.
    pub fn encode_segment_prefix(&self, seg_reg: u16) -> u8 {
        use crate::x86::x86_register_info::{CS, DS, ES, FS, GS, SS};
        match seg_reg {
            r if r == CS => 0x2E,
            r if r == SS => 0x36,
            r if r == DS => 0x3E,
            r if r == ES => 0x26,
            r if r == FS => 0x64,
            r if r == GS => 0x65,
            _ => 0x00, // Unknown — no override
        }
    }

    /// Decode a segment override prefix byte back to a segment register.
    pub fn decode_segment_prefix(&self, prefix: u8) -> Option<u16> {
        use crate::x86::x86_register_info::{CS, DS, ES, FS, GS, SS};
        match prefix {
            0x2E => Some(CS),
            0x36 => Some(SS),
            0x3E => Some(DS),
            0x26 => Some(ES),
            0x64 => Some(FS),
            0x65 => Some(GS),
            _ => None,
        }
    }

    // ---- TLS Segment Handling ----

    /// Get the segment register used for TLS.
    pub fn tls_segment_reg(&self) -> u16 {
        self.tls_segment
    }

    /// Create a TLS-relative address mode: `[FS:offset]` or `[GS:offset]`.
    pub fn create_tls_address(&self, offset: i64) -> X86AddressMode {
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_disp(offset)
            .with_segment(self.tls_segment)
            .build()
    }

    /// Create a TLS-relative address mode with a symbol.
    pub fn create_tls_symbol_address(&self, symbol: &str, offset: i64) -> X86AddressMode {
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_disp(offset)
            .with_segment(self.tls_segment)
            .with_symbol(symbol)
            .build()
    }

    // ---- Stack Segment Handling ----

    /// Check if an address refers to the stack (SS segment).
    pub fn is_stack_access(&self, addr: &X86AddressMode) -> bool {
        self.default_segment(addr) == x86_register_info::SS
    }

    /// Create a stack-relative address with an explicit SS override.
    /// This is usually redundant (SS is default for RSP/RBP-based addressing)
    /// but is needed in some edge cases (e.g., string operations).
    pub fn create_stack_address(&self, base: u16, offset: i64) -> X86AddressMode {
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base(base)
            .with_disp(offset)
            .with_segment(x86_register_info::SS)
            .with_frame_relative(true)
            .build()
    }

    // ---- Segment in 32-bit Mode ----

    /// In 32-bit mode, all 6 segment registers are available with their
    /// own base addresses set via descriptor tables (GDT/LDT).
    ///
    /// CS: Code segment (instruction fetch)
    /// DS: Data segment (default data)
    /// SS: Stack segment
    /// ES: Extra segment (string destination)
    /// FS: General-purpose (often used for OS data)
    /// GS: General-purpose (often used for TLS on Linux)
    pub fn get_available_segments_32(&self) -> Vec<u16> {
        vec![
            x86_register_info::CS,
            x86_register_info::DS,
            x86_register_info::SS,
            x86_register_info::ES,
            x86_register_info::FS,
            x86_register_info::GS,
        ]
    }

    /// In 64-bit mode, CS/DS/ES/SS bases are forced to 0. Only FS/GS
    /// have programmable bases (via MSRs).
    pub fn get_available_segments_64(&self) -> Vec<u16> {
        vec![x86_register_info::FS, x86_register_info::GS]
    }

    /// Get available segments for the current mode.
    pub fn get_available_segments(&self) -> Vec<u16> {
        if self.is_64bit {
            self.get_available_segments_64()
        } else {
            self.get_available_segments_32()
        }
    }

    // ---- Segment Override Encoding ----

    /// Generate all prefix bytes needed for an address mode, including
    /// segment override and REX prefix.
    pub fn generate_prefixes(&self, addr: &X86AddressMode) -> Vec<u8> {
        let mut prefixes = Vec::new();

        // 1. Segment override (if needed)
        if let Some(seg_prefix) = self.segment_override_prefix(addr) {
            prefixes.push(seg_prefix);
        }

        // 2. Address size override prefix (0x67) for 16/32-bit addressing
        // in 64-bit mode or vice versa
        // For simplicity: only emit when modes differ
        if self.is_64bit && addr.width == AddrWidth::Addr32 {
            prefixes.push(0x67); // 32-bit address in 64-bit mode
        } else if !self.is_64bit
            && addr.width == AddrWidth::Addr16
            && self.engine.addr_width == AddrWidth::Addr32
        {
            prefixes.push(0x67); // 16-bit address in 32-bit mode
        }

        // 3. REX prefix (if needed)
        if addr.requires_rex() {
            let mut rex: u8 = 0x40; // REX base
                                    // REX.W: use 64-bit operand size
            if self.is_64bit {
                rex |= 0x08; // REX.W
            }
            // REX.R: extension of ModR/M reg field (handled by caller)
            // REX.X: extension of SIB index field
            if let Some(idx) = addr.index {
                if idx >= 8 {
                    rex |= 0x02; // REX.X
                }
            }
            // REX.B: extension of ModR/M r/m, SIB base, or opcode reg
            if let Some(base) = addr.base {
                if base >= 8 {
                    rex |= 0x01; // REX.B
                }
            }
            if rex != 0x48 {
                prefixes.push(rex);
            } else {
                prefixes.push(0x48); // Standard REX.W for 64-bit
            }
        } else if self.is_64bit && self.needs_rex_w(addr) {
            prefixes.push(0x48); // REX.W for 64-bit operands
        }

        prefixes
    }

    /// Check if a REX.W prefix is needed for 64-bit operand size.
    fn needs_rex_w(&self, _addr: &X86AddressMode) -> bool {
        // REX.W is typically set by the instruction, not the addressing mode.
        // It's needed when the operand size is 64-bit and the instruction
        // defaults to 32-bit.
        self.is_64bit
    }
}

// ============================================================================
// Addressing Mode Matcher — pattern matching for ModR/M + SIB
// ============================================================================

/// Matches ModR/M + SIB patterns and extracts addressing modes.
///
/// This is the inverse of encoding — given raw bytes, decode the
/// ModR/M byte and optional SIB byte into an X86AddressMode.
#[derive(Debug, Clone)]
pub struct AddressingModeMatcher {
    width: AddrWidth,
}

impl AddressingModeMatcher {
    /// Create a new matcher for the given addressing width.
    pub fn new(width: AddrWidth) -> Self {
        Self { width }
    }

    /// Decode a ModR/M byte (and optional SIB byte, displacement) into
    /// an X86AddressMode.
    ///
    /// # Arguments
    /// * `modrm` - The ModR/M byte.
    /// * `sib` - The SIB byte (None if no SIB byte).
    /// * `displacement` - The displacement bytes (empty vector = no displacement).
    /// * `has_rex` - Whether there was a REX prefix.
    /// * `rex_b` - REX.B bit (extends r/m or SIB base).
    /// * `rex_x` - REX.X bit (extends SIB index).
    pub fn decode(
        &self,
        modrm: u8,
        sib: Option<u8>,
        displacement: &[u8],
        has_rex: bool,
        rex_b: bool,
        rex_x: bool,
    ) -> X86AddressMode {
        let _mod_field = (modrm >> 6) & 0x3;
        let _reg_field = (modrm >> 3) & 0x7;
        let _rm_field = modrm & 0x7;

        match self.width {
            AddrWidth::Addr16 => self.decode_16bit(modrm, displacement),
            AddrWidth::Addr32 | AddrWidth::Addr64 => {
                self.decode_32_64(modrm, sib, displacement, has_rex, rex_b, rex_x)
            }
        }
    }

    /// Decode 16-bit ModR/M addressing.
    fn decode_16bit(&self, _modrm: u8, displacement: &[u8]) -> X86AddressMode {
        let form = X86Addr16Form::decode(_modrm);
        let disp = match displacement.len() {
            0 => 0i64,
            1 => displacement[0] as i8 as i64,
            2 => {
                let val = u16::from_le_bytes([displacement[0], displacement[1]]);
                val as i16 as i64
            }
            _ => 0i64,
        };

        let mut mode = X86AddressMode {
            width: AddrWidth::Addr16,
            base: form.effective_base(),
            index: form.effective_index(),
            scale: 1, // 16-bit mode doesn't have scaling
            displacement: disp,
            form_16bit: Some(form),
            ..Default::default()
        };

        if form == X86Addr16Form::Disp16 {
            mode.is_absolute_16 = true;
        }

        mode
    }

    /// Decode 32/64-bit ModR/M + SIB addressing.
    fn decode_32_64(
        &self,
        modrm: u8,
        sib: Option<u8>,
        displacement: &[u8],
        has_rex: bool,
        rex_b: bool,
        rex_x: bool,
    ) -> X86AddressMode {
        let mod_field = (modrm >> 6) & 0x3;
        let rm_field = modrm & 0x7;

        let disp: i64 = match displacement.len() {
            0 => 0,
            1 => displacement[0] as i8 as i64,
            4 => {
                let val = u32::from_le_bytes([
                    displacement[0],
                    displacement[1],
                    displacement[2],
                    displacement[3],
                ]);
                val as i32 as i64
            }
            _ => 0,
        };

        // Check for RIP-relative (64-bit mode: mod=00, r/m=5)
        if self.width == AddrWidth::Addr64 && mod_field == 0 && rm_field == 5 {
            return X86AddressMode {
                width: AddrWidth::Addr64,
                displacement: disp,
                is_rip_relative: true,
                ..Default::default()
            };
        }

        // Check for absolute [disp32] (32-bit mode: mod=00, r/m=5)
        if self.width == AddrWidth::Addr32 && mod_field == 0 && rm_field == 5 {
            return X86AddressMode {
                width: AddrWidth::Addr32,
                displacement: disp,
                is_absolute_32: true,
                ..Default::default()
            };
        }

        // Check for SIB (r/m=4)
        if rm_field == 4 {
            return self.decode_sib(modrm, sib, displacement, has_rex, rex_b, rex_x);
        }

        // Direct base register encoding
        let base_id: u16 = if has_rex && rex_b {
            rm_field as u16 + 8
        } else {
            rm_field as u16
        };

        X86AddressMode {
            width: self.width,
            base: Some(base_id),
            displacement: disp,
            ..Default::default()
        }
    }

    /// Decode SIB byte.
    fn decode_sib(
        &self,
        _modrm: u8,
        sib: Option<u8>,
        displacement: &[u8],
        has_rex: bool,
        rex_b: bool,
        rex_x: bool,
    ) -> X86AddressMode {
        let mod_field = (_modrm >> 6) & 0x3;
        let sib_byte = sib.unwrap_or(0x24); // default: scale=0, index=4, base=4

        let scale_field = (sib_byte >> 6) & 0x3;
        let index_field = (sib_byte >> 3) & 0x7;
        let base_field = sib_byte & 0x7;

        let scale: u8 = match scale_field {
            0 => 1,
            1 => 2,
            2 => 4,
            3 => 8,
            _ => 1,
        };

        let index: Option<u16> = if index_field == 4 {
            None // No index
        } else {
            let id = if has_rex && rex_x {
                index_field as u16 + 8
            } else {
                index_field as u16
            };
            Some(id)
        };

        let base: Option<u16> = if mod_field == 0 && base_field == 5 {
            // mod=00, base=5: no base (disp32 form)
            None
        } else {
            let id = if has_rex && rex_b {
                base_field as u16 + 8
            } else {
                base_field as u16
            };
            Some(id)
        };

        let disp: i64 = match displacement.len() {
            0 => 0,
            1 => displacement[0] as i8 as i64,
            4 => {
                let val = u32::from_le_bytes([
                    displacement[0],
                    displacement[1],
                    displacement[2],
                    displacement[3],
                ]);
                val as i32 as i64
            }
            _ => 0,
        };

        X86AddressMode {
            width: self.width,
            base,
            index,
            scale,
            displacement: disp,
            is_absolute_32: base.is_none() && index.is_none(),
            ..Default::default()
        }
    }
}

// ============================================================================
// Complete ModR/M Encoding Table (32/64-bit)
// ============================================================================

/// Generate all valid ModR/M combinations for 32/64-bit addressing.
///
/// Returns a vector of (modrm byte, description, base, index, scale, disp).
pub fn generate_all_modrm_combinations_32_64(width: AddrWidth) -> Vec<ModRMEntry> {
    let mut entries = Vec::new();

    // mod=00: [reg] forms
    for rm in 0..8u8 {
        if rm == 4 {
            // SIB required; handled separately
            continue;
        }
        if rm == 5 {
            if width == AddrWidth::Addr64 {
                // [RIP + disp32]
                entries.push(ModRMEntry {
                    modrm: (Mod00 << 6) | rm,
                    form: ModRMForm::RIPRelative,
                    base: None,
                    index: None,
                    scale: 1,
                    displacement: 0,
                });
            } else {
                // [disp32]
                entries.push(ModRMEntry {
                    modrm: (Mod00 << 6) | rm,
                    form: ModRMForm::Absolute,
                    base: None,
                    index: None,
                    scale: 1,
                    displacement: 0,
                });
            }
            continue;
        }
        entries.push(ModRMEntry {
            modrm: (Mod00 << 6) | rm,
            form: ModRMForm::BaseOnly,
            base: Some(rm as u16),
            index: None,
            scale: 1,
            displacement: 0,
        });
    }

    // mod=00, rm=4: SIB with no displacement
    for base in 0..8u8 {
        for index in 0..8u8 {
            if index == 4 && base == 5 {
                // Special: mod=00, base=5, index=4 → [disp32]
                entries.push(ModRMEntry {
                    modrm: (Mod00 << 6) | 4,
                    form: ModRMForm::Absolute,
                    base: None,
                    index: None,
                    scale: 1,
                    displacement: 0,
                });
                continue;
            }
            for scale in 0..4u8 {
                let _sib = (scale << 6) | ((index & 0x7) << 3) | (base & 0x7);
                let actual_base = if base == 5 && index == 4 {
                    None // disp32 form
                } else {
                    Some(base as u16)
                };
                let actual_index = if index == 4 { None } else { Some(index as u16) };
                let actual_scale: u8 = match scale {
                    0 => 1,
                    1 => 2,
                    2 => 4,
                    3 => 8,
                    _ => 1,
                };

                let form = match (actual_base, actual_index) {
                    (Some(_), Some(_)) => ModRMForm::BaseIndexScale,
                    (Some(_), None) => ModRMForm::BaseOnly,
                    (None, Some(_)) => ModRMForm::IndexScale,
                    (None, None) => ModRMForm::Absolute,
                };

                entries.push(ModRMEntry {
                    modrm: (Mod00 << 6) | 4,
                    form,
                    base: actual_base,
                    index: actual_index,
                    scale: actual_scale,
                    displacement: 0,
                });
            }
        }
    }

    // mod=01: [reg + disp8] forms
    for rm in 0..8u8 {
        if rm == 4 {
            // SIB with disp8: handled below
            continue;
        }
        entries.push(ModRMEntry {
            modrm: (Mod01 << 6) | rm,
            form: ModRMForm::BaseDisp8,
            base: Some(rm as u16),
            index: None,
            scale: 1,
            displacement: 0,
        });
    }

    // mod=01, rm=4: SIB with disp8 (simplified)
    entries.push(ModRMEntry {
        modrm: (Mod01 << 6) | 4,
        form: ModRMForm::BaseDisp8,
        base: Some(4), // RSP
        index: None,
        scale: 1,
        displacement: 0,
    });

    // mod=10: [reg + disp32]
    for rm in 0..8u8 {
        if rm == 4 {
            continue;
        }
        entries.push(ModRMEntry {
            modrm: (Mod10 << 6) | rm,
            form: ModRMForm::BaseDisp32,
            base: Some(rm as u16),
            index: None,
            scale: 1,
            displacement: 0,
        });
    }

    entries
}

/// A single ModR/M entry in the encoding table.
#[derive(Debug, Clone)]
pub struct ModRMEntry {
    /// The ModR/M byte (reg field = 0).
    pub modrm: u8,
    /// The addressing form.
    pub form: ModRMForm,
    /// Base register (if any, 3-bit encoding).
    pub base: Option<u16>,
    /// Index register (if any, 3-bit encoding).
    pub index: Option<u16>,
    /// Scale factor.
    pub scale: u8,
    /// Displacement (0 indicates no displacement / variable / filled in).
    pub displacement: i64,
}

/// ModR/M encoding forms.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ModRMForm {
    BaseOnly,
    BaseDisp8,
    BaseDisp32,
    IndexScale,
    BaseIndexScale,
    BaseIndexScaleDisp8,
    BaseIndexScaleDisp32,
    RIPRelative,
    Absolute,
    RegisterDirect,
}

// ============================================================================
// Complete SIB Combination Table
// ============================================================================

/// Generate all valid SIB byte combinations.
///
/// Returns a vector of (sib byte, scale, index register, base register, description).
pub fn generate_all_sib_combinations() -> Vec<SIBEntry> {
    let mut entries = Vec::new();
    for scale in 0..4u8 {
        for index in 0..8u8 {
            for base in 0..8u8 {
                let sib = (scale << 6) | ((index & 0x7) << 3) | (base & 0x7);
                let scale_val: u8 = match scale {
                    0 => 1,
                    1 => 2,
                    2 => 4,
                    3 => 8,
                    _ => 1,
                };
                let has_index = index != 4;

                entries.push(SIBEntry {
                    sib,
                    scale: scale_val,
                    index: if has_index { Some(index as u16) } else { None },
                    base: Some(base as u16),
                    is_valid: !(index == 4 && base == 5), // Special case for mod=00
                });
            }
        }
    }
    entries
}

/// A single SIB byte entry.
#[derive(Debug, Clone)]
pub struct SIBEntry {
    pub sib: u8,
    pub scale: u8,
    pub index: Option<u16>,
    pub base: Option<u16>,
    pub is_valid: bool,
}

// ============================================================================
// Addressing Mode Selection — choose optimal form
// ============================================================================

/// Address mode selector that chooses the optimal addressing form
/// for a given set of constraints.
#[derive(Debug, Clone)]
pub struct AddressModeSelector {
    /// The addressing engine.
    engine: X86AddressingFull,
    /// Prefer 8-bit displacement when possible.
    prefer_disp8: bool,
    /// Prefer no-SIB forms.
    prefer_no_sib: bool,
    /// Allow RIP-relative addressing.
    allow_rip_relative: bool,
    /// Allow SIB byte.
    allow_sib: bool,
    /// Maximum displacement bits.
    max_disp_bits: u8,
}

impl AddressModeSelector {
    /// Create a new selector.
    pub fn new(engine: X86AddressingFull) -> Self {
        Self {
            max_disp_bits: engine.addr_width.max_disp_bits() as u8,
            engine,
            prefer_disp8: true,
            prefer_no_sib: true,
            allow_rip_relative: true,
            allow_sib: true,
        }
    }

    /// Select the best addressing mode for a base+disp pair.
    pub fn select_base_disp(&self, base: u16, disp: i64) -> X86AddressMode {
        let builder = X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base(base)
            .with_disp(disp)
            .canonicalize();
        builder.build()
    }

    /// Select the best addressing mode for a base+index*scale+disp quadruple.
    pub fn select_full(&self, base: u16, index: u16, scale: u8, disp: i64) -> X86AddressMode {
        let mut builder = X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base(base)
            .with_index(index, scale)
            .with_disp(disp);

        // Try to avoid SIB if possible
        if self.prefer_no_sib && index == 0 && scale <= 1 {
            builder = builder.with_index_opt(None, 0);
        }

        // Try to use disp8 if possible
        if self.prefer_disp8 && disp != 0 {
            if disp >= -128 && disp <= 127 {
                // Already fits; no change
            } else if disp >= -120 && disp <= 120 {
                // Near-miss: try adjusting the base to make it fit
            }
        }

        builder.canonicalize().build()
    }

    /// Select the best addressing mode for a RIP-relative reference.
    pub fn select_rip_relative(&self, disp: i64) -> X86AddressMode {
        if !self.allow_rip_relative {
            // Fall back to absolute if RIP-relative not allowed
            return X86AddressMode {
                width: self.engine.addr_width,
                displacement: disp,
                is_absolute_32: true,
                ..Default::default()
            };
        }
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_disp(disp)
            .with_rip_relative(true)
            .build()
    }

    /// Select the best addressing mode for an absolute address.
    pub fn select_absolute(&self, addr: i64) -> X86AddressMode {
        match self.engine.addr_width {
            AddrWidth::Addr16 => X86AddressMode::absolute16(addr),
            AddrWidth::Addr32 => X86AddressMode::absolute32(addr),
            AddrWidth::Addr64 => {
                if self.allow_rip_relative {
                    X86AddressMode::rip_relative(addr)
                } else {
                    X86AddressMode {
                        width: AddrWidth::Addr64,
                        displacement: addr,
                        is_absolute_32: true,
                        ..Default::default()
                    }
                }
            }
        }
    }

    /// Select the best 16-bit addressing form.
    pub fn select_16bit(&self, base: Option<u16>, index: Option<u16>, disp: i64) -> X86AddressMode {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};

        let disp_fits_8 = disp >= -128 && disp <= 127;
        let disp_fits_16 = disp >= -32768 && disp <= 32767;
        let has_disp = disp != 0;

        let form = match (base, index, has_disp, disp_fits_8) {
            (None, None, true, _) => X86Addr16Form::Disp16,

            (Some(b), None, false, _) => match b {
                r if r == BX => X86Addr16Form::Bx,
                r if r == BP => X86Addr16Form::Bp,
                r if r == SI => X86Addr16Form::Si,
                r if r == DI => X86Addr16Form::Di,
                _ => X86Addr16Form::Disp16,
            },

            (Some(b), None, true, true) => match b {
                r if r == BX => X86Addr16Form::BxDisp8,
                r if r == BP => X86Addr16Form::BpDisp8,
                r if r == SI => X86Addr16Form::SiDisp8,
                r if r == DI => X86Addr16Form::DiDisp8,
                _ => X86Addr16Form::Disp16,
            },

            (Some(b), None, true, false) => match b {
                r if r == BX => X86Addr16Form::BxDisp16,
                r if r == BP => X86Addr16Form::BpDisp16,
                r if r == SI => X86Addr16Form::SiDisp16,
                r if r == DI => X86Addr16Form::DiDisp16,
                _ => X86Addr16Form::Disp16,
            },

            (Some(b), Some(i), false, _) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => X86Addr16Form::BxSi,
                (b_val, i_val) if b_val == BX && i_val == DI => X86Addr16Form::BxDi,
                (b_val, i_val) if b_val == BP && i_val == SI => X86Addr16Form::BpSi,
                (b_val, i_val) if b_val == BP && i_val == DI => X86Addr16Form::BpDi,
                _ => X86Addr16Form::Disp16,
            },

            (Some(b), Some(i), true, true) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => X86Addr16Form::BxSiDisp8,
                (b_val, i_val) if b_val == BX && i_val == DI => X86Addr16Form::BxDiDisp8,
                (b_val, i_val) if b_val == BP && i_val == SI => X86Addr16Form::BpSiDisp8,
                (b_val, i_val) if b_val == BP && i_val == DI => X86Addr16Form::BpDiDisp8,
                _ => X86Addr16Form::Disp16,
            },

            (Some(b), Some(i), true, false) => match (b, i) {
                (b_val, i_val) if b_val == BX && i_val == SI => X86Addr16Form::BxSiDisp16,
                (b_val, i_val) if b_val == BX && i_val == DI => X86Addr16Form::BxDiDisp16,
                (b_val, i_val) if b_val == BP && i_val == SI => X86Addr16Form::BpSiDisp16,
                (b_val, i_val) if b_val == BP && i_val == DI => X86Addr16Form::BpDiDisp16,
                _ => X86Addr16Form::Disp16,
            },

            _ => X86Addr16Form::Disp16,
        };

        X86AddressMode {
            width: AddrWidth::Addr16,
            base,
            index,
            scale: 1,
            displacement: disp,
            form_16bit: Some(form),
            is_absolute_16: form == X86Addr16Form::Disp16,
            ..Default::default()
        }
    }
}

// ============================================================================
// Addressing Mode Utilities
// ============================================================================

/// Check if a register is a valid base register for the given address width.
pub fn is_valid_base_reg(reg: u16, width: AddrWidth) -> bool {
    match width {
        AddrWidth::Addr64 => {
            use crate::x86::x86_register_info::{R10, R11, R12, R13, R14, R15, R8, R9};
            matches!(
                reg,
                x86_register_info::RAX
                    | x86_register_info::RCX
                    | x86_register_info::RDX
                    | x86_register_info::RBX
                    | x86_register_info::RSP
                    | x86_register_info::RBP
                    | x86_register_info::RSI
                    | x86_register_info::RDI
                    | R8
                    | R9
                    | R10
                    | R11
                    | R12
                    | R13
                    | R14
                    | R15
            )
        }
        AddrWidth::Addr32 => {
            use crate::x86::x86_register_info::{R10D, R11D, R12D, R13D, R14D, R15D, R8D, R9D};
            matches!(
                reg,
                x86_register_info::EAX
                    | x86_register_info::ECX
                    | x86_register_info::EDX
                    | x86_register_info::EBX
                    | x86_register_info::ESP
                    | x86_register_info::EBP
                    | x86_register_info::ESI
                    | x86_register_info::EDI
                    | R8D
                    | R9D
                    | R10D
                    | R11D
                    | R12D
                    | R13D
                    | R14D
                    | R15D
            )
        }
        AddrWidth::Addr16 => {
            use crate::x86::x86_register_info::{BP, BX, DI, SI};
            matches!(reg, BX | BP | SI | DI)
        }
    }
}

/// Check if a register is a valid index register for the given address width.
pub fn is_valid_index_reg(reg: u16, width: AddrWidth) -> bool {
    match width {
        AddrWidth::Addr64 => {
            // Same as base but RSP cannot be an index
            use crate::x86::x86_register_info::{R10, R11, R12, R13, R14, R15, R8, R9};
            matches!(
                reg,
                x86_register_info::RAX
                    | x86_register_info::RCX
                    | x86_register_info::RDX
                    | x86_register_info::RBX
                    | x86_register_info::RBP
                    | x86_register_info::RSI
                    | x86_register_info::RDI
                    | R8
                    | R9
                    | R10
                    | R11
                    | R12
                    | R13
                    | R14
                    | R15
            )
        }
        AddrWidth::Addr32 => {
            use crate::x86::x86_register_info::{R10D, R11D, R12D, R13D, R14D, R15D, R8D, R9D};
            matches!(
                reg,
                x86_register_info::EAX
                    | x86_register_info::ECX
                    | x86_register_info::EDX
                    | x86_register_info::EBX
                    | x86_register_info::EBP
                    | x86_register_info::ESI
                    | x86_register_info::EDI
                    | R8D
                    | R9D
                    | R10D
                    | R11D
                    | R12D
                    | R13D
                    | R14D
                    | R15D
            )
        }
        AddrWidth::Addr16 => {
            // In 16-bit mode, only SI and DI can be index registers
            use crate::x86::x86_register_info::{DI, SI};
            matches!(reg, SI | DI)
        }
    }
}

/// Check if a scale factor is valid.
pub fn is_valid_scale(scale: u8) -> bool {
    matches!(scale, 1 | 2 | 4 | 8)
}

/// Compute the effective address value given a base, index, scale, and displacement.
pub fn compute_effective_address(
    base_val: Option<u64>,
    index_val: Option<u64>,
    scale: u8,
    disp: i64,
) -> u64 {
    let b = base_val.unwrap_or(0);
    let i = index_val.unwrap_or(0);
    let s = scale as u64;
    b.wrapping_add(i.wrapping_mul(s)).wrapping_add(disp as u64)
}

/// Check if two addressing modes refer to the same effective address.
pub fn are_addresses_equal(a: &X86AddressMode, b: &X86AddressMode) -> bool {
    a.base == b.base
        && a.index == b.index
        && a.scale == b.scale
        && a.displacement == b.displacement
        && a.segment == b.segment
        && a.is_rip_relative == b.is_rip_relative
        && (a.symbol.as_deref() == b.symbol.as_deref())
}

/// Compute the difference between two addressing modes as an offset.
/// Returns None if the addresses have different bases or indices.
pub fn address_difference(a: &X86AddressMode, b: &X86AddressMode) -> Option<i64> {
    if a.base != b.base
        || a.index != b.index
        || a.scale != b.scale
        || a.segment != b.segment
        || a.is_rip_relative != b.is_rip_relative
    {
        return None;
    }
    Some(b.displacement - a.displacement)
}

/// Merge two addresses when one is a simple offset of the other.
/// Returns the common base address mode and the offsets.
pub fn merge_addresses(
    a: &X86AddressMode,
    b: &X86AddressMode,
) -> Option<(X86AddressMode, i64, i64)> {
    if a.base != b.base || a.index != b.index || a.scale != b.scale {
        return None;
    }

    let base_disp = a.displacement.min(b.displacement);
    let mut common = a.clone();
    common.displacement = base_disp;

    Some((
        common,
        a.displacement - base_disp,
        b.displacement - base_disp,
    ))
}

// ============================================================================
// Addressing Mode Encoding Utilities
// ============================================================================

/// Encode an addressing mode into a full byte sequence:
/// [segment override] [REX] [opcode...] [ModR/M] [SIB] [disp] [imm...]
///
/// This function produces the memory operand portion of an encoded instruction.
pub fn encode_addressing_mode(addr: &X86AddressMode, reg_field: u8) -> Vec<u8> {
    let mut bytes = Vec::new();

    // Segment override (if any)
    let seg_handler = X86SegmentHandling::new(X86AddressingFull::new(addr.width));
    if let Some(pref) = seg_handler.segment_override_prefix(addr) {
        bytes.push(pref);
    }

    // REX prefix (if needed)
    if addr.requires_rex() {
        let mut rex: u8 = 0x40;
        if addr.width == AddrWidth::Addr64 {
            rex |= 0x08; // REX.W
        }
        if let Some(idx) = addr.index {
            if idx >= 8 {
                rex |= 0x02; // REX.X
            }
        }
        if let Some(base) = addr.base {
            if base >= 8 {
                rex |= 0x01; // REX.B
            }
        }
        bytes.push(rex);
    }

    // ModR/M byte
    bytes.push(addr.encode_modrm(reg_field));

    // SIB byte (if needed)
    if addr.requires_sib() {
        bytes.push(addr.encode_sib());
    }

    // Displacement
    bytes.extend(addr.encode_displacement());

    bytes
}

/// Decode bytes into an addressing mode starting at the given offset.
/// Returns (address_mode, bytes_consumed).
pub fn decode_addressing_mode(
    bytes: &[u8],
    offset: usize,
    width: AddrWidth,
    has_rex: bool,
    rex_b: bool,
    rex_x: bool,
) -> Option<(X86AddressMode, usize)> {
    if offset >= bytes.len() {
        return None;
    }

    let matcher = AddressingModeMatcher::new(width);
    let modrm = bytes[offset];
    let mod_field = (modrm >> 6) & 0x3;
    let rm_field = modrm & 0x7;

    let mut consumed: usize = 1; // ModR/M byte

    // Check for SIB
    let needs_sib = rm_field == 4;
    let sib = if needs_sib {
        if offset + 1 >= bytes.len() {
            return None;
        }
        consumed += 1;
        Some(bytes[offset + 1])
    } else {
        None
    };

    // Compute displacement size
    let disp_size: usize = if mod_field == 0 && rm_field == 5 {
        // [disp32] or [RIP + disp32]
        4
    } else if mod_field == 1 {
        // disp8
        1
    } else if mod_field == 2 {
        // disp32
        4
    } else if mod_field == 0 && sib.is_some() {
        // SIB with mod=00
        let sib_byte = sib.unwrap();
        let sib_base = sib_byte & 0x7;
        if sib_base == 5 {
            // [disp32] form
            4
        } else {
            0
        }
    } else {
        0
    };

    let disp_bytes = if disp_size > 0 && offset + consumed + disp_size <= bytes.len() {
        bytes[offset + consumed..offset + consumed + disp_size].to_vec()
    } else {
        vec![]
    };
    consumed += disp_size;

    let addr = matcher.decode(modrm, sib, &disp_bytes, has_rex, rex_b, rex_x);

    Some((addr, consumed))
}

/// Encode a 16-bit ModR/M byte for a given addressing form and register field.
pub fn encode_16bit_modrm(form: X86Addr16Form, reg_field: u8) -> u8 {
    (form.mod_field() << 6) | ((reg_field & 0x7) << 3) | (form.rm_field() & 0x7)
}

/// Format an address mode as Intel syntax string.
pub fn format_intel(addr: &X86AddressMode, _reg_info: &X86RegisterInfo) -> String {
    let mut s = String::new();

    // Size prefix
    match addr.width {
        AddrWidth::Addr64 => s.push_str("qword ptr "),
        AddrWidth::Addr32 => s.push_str("dword ptr "),
        AddrWidth::Addr16 => s.push_str("word ptr "),
    }

    s.push('[');

    // Segment override
    if let Some(seg) = addr.segment {
        s.push_str(X86RegisterInfo::get_intel_name(seg));
        s.push(':');
    }

    // Base
    if addr.is_rip_relative {
        s.push_str("rip");
    } else if let Some(base) = addr.base {
        s.push_str(X86RegisterInfo::get_intel_name(base));
    }

    // Index * scale
    if let Some(index) = addr.index {
        if addr.base.is_some() || addr.is_rip_relative {
            s.push_str(" + ");
        }
        s.push_str(X86RegisterInfo::get_intel_name(index));
        if addr.scale > 1 {
            s.push_str(&format!("*{}", addr.scale));
        }
    }

    // Displacement
    if addr.displacement != 0 {
        if addr.base.is_some() || addr.index.is_some() || addr.is_rip_relative {
            if addr.displacement > 0 {
                s.push_str(&format!(" + {}", addr.displacement));
            } else {
                s.push_str(&format!(" - {}", -addr.displacement));
            }
        } else {
            s.push_str(&format!("{}", addr.displacement));
        }
    }

    s.push(']');

    s
}

/// Format an address mode as AT&T syntax string.
pub fn format_att(addr: &X86AddressMode, _reg_info: &X86RegisterInfo) -> String {
    let mut s = String::new();

    // Segment override
    if let Some(seg) = addr.segment {
        s.push_str(&format!("%{}:", X86RegisterInfo::get_asm_name(seg)));
    }

    // Displacement first in AT&T syntax
    if addr.displacement != 0 {
        s.push_str(&format!("{}", addr.displacement));
    }

    s.push('(');

    // Base
    if addr.is_rip_relative {
        s.push_str("%rip");
    } else if let Some(base) = addr.base {
        s.push_str(&format!("%{}", X86RegisterInfo::get_asm_name(base)));
    }

    // Index and scale
    if let Some(index) = addr.index {
        s.push(',');
        s.push_str(&format!("%{}", X86RegisterInfo::get_asm_name(index)));
        if addr.scale > 1 {
            s.push_str(&format!(",{}", addr.scale));
        }
    }

    s.push(')');

    s
}

// ============================================================================
// Constant Pool and Symbol Addressing
// ============================================================================

/// Information about a constant pool entry for addressing.
#[derive(Debug, Clone)]
pub struct ConstantPoolEntry {
    /// Unique index in the pool.
    pub index: u32,
    /// Alignment of the constant.
    pub alignment: u8,
    /// Size in bytes of the constant.
    pub size: u16,
    /// Whether the constant is a float/double value.
    pub is_float: bool,
    /// RIP-relative offset to this entry.
    pub rip_offset: i64,
}

/// Constant pool manager for addressing constants relative to RIP.
#[derive(Debug, Clone, Default)]
pub struct ConstantPool {
    entries: Vec<ConstantPoolEntry>,
}

impl ConstantPool {
    /// Create a new constant pool.
    pub fn new() -> Self {
        Self { entries: vec![] }
    }

    /// Add an entry to the constant pool.
    pub fn add_entry(&mut self, alignment: u8, size: u16, is_float: bool) -> u32 {
        let index = self.entries.len() as u32;
        self.entries.push(ConstantPoolEntry {
            index,
            alignment,
            size,
            is_float,
            rip_offset: 0,
        });
        index
    }

    /// Get the address mode for a constant pool entry.
    pub fn get_address(&self, index: u32) -> Option<X86AddressMode> {
        self.entries.get(index as usize).map(|entry| {
            let label = format!(".LCPI{}", entry.index);
            X86AddressMode::rip_symbol(&label, entry.rip_offset)
        })
    }

    /// Number of entries in the pool.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Whether the pool is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

// ============================================================================
// Address Mode Cost Model — instruction selection cost database
// ============================================================================

/// Cost model for selecting the optimal addressing mode for memory operations.
///
/// This cost model considers:
/// - Instruction encoding size (bytes)
/// - Execution latency (cycles)
/// - Throughput (μops per cycle)
/// - Register pressure impact
/// - Cache line crossing penalty
///
/// # Cost Factors
/// ```text
/// Encoding size:
///   BaseOnly            = 1 byte (ModR/M)
///   BaseDisp8           = 2 bytes (ModR/M + disp8)
///   BaseDisp32          = 5 bytes (ModR/M + disp32)
///   BaseIndexScale      = 2 bytes (ModR/M + SIB)
///   BaseIndexScaleDisp8 = 3 bytes (ModR/M + SIB + disp8)
///   BaseIndexScaleDisp32= 6 bytes (ModR/M + SIB + disp32)
///   RIPRelative         = 5 bytes (ModR/M + disp32)
///   Absolute32          = 5 bytes (ModR/M + disp32)
///
/// Execution:
///   Simple addressing    = 1 μop (fused)
///   Complex addressing   = 2 μops (unfused on some μarchs)
///   RIP-relative         = 1 μop (fused on modern CPUs)
/// ```
#[derive(Debug, Clone)]
pub struct AddressCostModel {
    /// Cost per byte of encoding (size optimization weight).
    pub byte_cost: u32,
    /// Cost per μop (performance optimization weight).
    pub uop_cost: u32,
    /// Penalty for requiring a SIB byte.
    pub sib_penalty: u32,
    /// Penalty for requiring a REX prefix.
    pub rex_penalty: u32,
    /// Penalty for crossing a cache line boundary.
    pub cache_line_penalty: u32,
    /// Penalty for requiring a segment override.
    pub segment_penalty: u32,
    /// Whether the microarchitecture can fuse complex addressing.
    pub fuse_complex: bool,
    /// Whether the microarchitecture can fuse RIP-relative loads.
    pub fuse_rip_relative: bool,
}

impl Default for AddressCostModel {
    fn default() -> Self {
        Self {
            byte_cost: 1,
            uop_cost: 10,
            sib_penalty: 5,
            rex_penalty: 2,
            cache_line_penalty: 20,
            segment_penalty: 8,
            fuse_complex: true,
            fuse_rip_relative: true,
        }
    }
}

impl AddressCostModel {
    /// Cost model for Intel Skylake / Ice Lake / Alder Lake.
    pub fn skylake() -> Self {
        Self {
            byte_cost: 1,
            uop_cost: 10,
            sib_penalty: 2,
            rex_penalty: 1,
            cache_line_penalty: 18,
            segment_penalty: 5,
            fuse_complex: true,
            fuse_rip_relative: true,
        }
    }

    /// Cost model for AMD Zen 3 / Zen 4 / Zen 5.
    pub fn zen() -> Self {
        Self {
            byte_cost: 1,
            uop_cost: 12,
            sib_penalty: 3,
            rex_penalty: 1,
            cache_line_penalty: 15,
            segment_penalty: 6,
            fuse_complex: true,
            fuse_rip_relative: true,
        }
    }

    /// Cost model optimized for code size (-Os / -Oz).
    pub fn size_optimized() -> Self {
        Self {
            byte_cost: 100,
            uop_cost: 1,
            sib_penalty: 50,
            rex_penalty: 30,
            cache_line_penalty: 0,
            segment_penalty: 30,
            fuse_complex: false,
            fuse_rip_relative: false,
        }
    }

    /// Compute the total cost of an addressing mode.
    pub fn compute_cost(&self, addr: &X86AddressMode) -> u64 {
        let mut cost: u64 = 0;

        // Encoding size cost
        let encoding_size = addr.classify().encoding_overhead() as u64;
        cost += encoding_size * self.byte_cost as u64;

        // SIB byte penalty
        if addr.requires_sib() {
            cost += self.sib_penalty as u64;
        }

        // REX prefix penalty
        if addr.requires_rex() {
            cost += self.rex_penalty as u64;
        }

        // Segment override penalty
        if addr.segment.is_some() {
            cost += self.segment_penalty as u64;
        }

        // μop cost
        let uops = self.estimate_uops(addr);
        cost += uops * self.uop_cost as u64;

        // Cache line crossing potential
        if self.may_cross_cache_line(addr) {
            cost += self.cache_line_penalty as u64;
        }

        cost
    }

    /// Estimate the number of μops for this addressing mode.
    fn estimate_uops(&self, addr: &X86AddressMode) -> u64 {
        if addr.is_rip_relative {
            if self.fuse_rip_relative {
                return 1; // Fused RIP-relative load
            }
            return 2; // Unfused: address calc + load
        }

        if !addr.has_index() {
            // Base+disp is always 1 μop (fused)
            return 1;
        }

        // Base+index*scale
        if self.fuse_complex {
            match addr.scale {
                1 | 2 | 4 | 8 => 1, // Fused
                _ => 2,             // Unfused
            }
        } else {
            2 // Always unfused on older μarchs
        }
    }

    /// Check if the addressing mode may cross a cache line boundary.
    ///
    /// Accesses that span two cache lines (64-byte aligned) have a
    /// latency penalty on most CPUs.
    fn may_cross_cache_line(&self, addr: &X86AddressMode) -> bool {
        // Only relevant for larger accesses near cache line boundaries
        // For simplicity: check if displacement is near a 64-byte boundary
        if addr.displacement == 0 {
            return false;
        }

        let offset = (addr.displacement as u64) & 0x3F;
        // If the access could start near the end of a cache line
        offset > 56
    }

    /// Compare two address modes and return the lower-cost one.
    pub fn select_cheaper(&self, a: &X86AddressMode, b: &X86AddressMode) -> X86AddressMode {
        let cost_a = self.compute_cost(a);
        let cost_b = self.compute_cost(b);
        if cost_a <= cost_b {
            a.clone()
        } else {
            b.clone()
        }
    }
}

// ============================================================================
// Address Register Pressure Analysis
// ============================================================================

/// Analyzes register pressure impact of various addressing mode choices.
///
/// Complex addressing modes (base+index*scale) consume an extra register
/// (the index), which may increase register pressure. In high-pressure
/// situations, it may be better to use a simpler addressing mode even
/// if it requires an extra instruction.
#[derive(Debug, Clone)]
pub struct RegisterPressureAnalysis {
    /// Maximum number of allocatable GPRs for the current mode.
    pub available_gprs: u8,
    /// Current register pressure (0.0-1.0, fraction of GPRs in use).
    pub current_pressure: f64,
    /// Threshold above which we avoid complex addressing.
    pub pressure_threshold: f64,
}

impl Default for RegisterPressureAnalysis {
    fn default() -> Self {
        Self {
            available_gprs: 14, // Excluding RSP and RBP
            current_pressure: 0.0,
            pressure_threshold: 0.7,
        }
    }
}

impl RegisterPressureAnalysis {
    /// Create an analysis for 64-bit mode.
    pub fn new64() -> Self {
        Self {
            available_gprs: 14,
            ..Default::default()
        }
    }

    /// Create an analysis for 32-bit mode.
    pub fn new32() -> Self {
        Self {
            available_gprs: 6, // EAX, ECX, EDX, EBX, ESI, EDI (ESP/EBP reserved)
            ..Default::default()
        }
    }

    /// Whether using a complex addressing mode (with index) is acceptable
    /// given the current register pressure.
    pub fn can_use_index(&self) -> bool {
        self.current_pressure < self.pressure_threshold
    }

    /// Whether to prefer LEA (which uses a destination register) over
    /// separate ADD instructions.
    pub fn should_use_lea(&self, num_adds: usize) -> bool {
        if self.current_pressure > 0.9 {
            // Very high pressure: use ADD to avoid tying up a dest register
            return false;
        }
        if self.current_pressure > 0.6 && num_adds <= 1 {
            return false;
        }
        true
    }

    /// Estimate the pressure change from using a given address mode.
    /// Returns (new_pressure, pressure_change).
    pub fn estimate_pressure(&self, addr: &X86AddressMode, live_regs: usize) -> (f64, f64) {
        let current = live_regs as f64 / self.available_gprs as f64;

        // Using an index register adds pressure if the index register
        // needs to be kept alive
        let additional: f64 = if addr.has_index() && addr.index != addr.base {
            1.0 / self.available_gprs as f64
        } else {
            0.0
        };

        (current + additional, additional)
    }

    /// Get a score for how "register-friendly" an addressing mode is.
    /// Higher scores mean less register pressure.
    pub fn register_friendliness(&self, addr: &X86AddressMode) -> u32 {
        let mut score: u32 = 10;

        if addr.has_index() {
            score -= 3; // Index consumes a register
        }

        if addr.has_base() {
            score -= 1; // Base consumes a register (but usually needed anyway)
        }

        if addr.is_rip_relative {
            score += 5; // RIP-relative uses no GP register
        }

        if addr.is_absolute_32 || addr.is_absolute_16 {
            score += 3; // Absolute uses no register
        }

        score
    }
}

// ============================================================================
// Comprehensive Memory Operand Folding Rules
// ============================================================================

/// Rules for folding memory operands into X86 instructions.
///
/// Many X86 instructions can take a memory operand as either the source
/// or destination. Folding a load into an ALU operation saves a MOV
/// instruction and a register.
///
/// # Foldable Patterns
/// ```text
/// Before:   mov reg, [addr]     ;  load
///           add reg, imm         ;  operate
/// After:    add reg, [addr]      ;  fold load into ALU op
///
/// Before:   add reg, [addr]     ;  compute
///           mov [addr], reg      ;  store
/// After:    add [addr], reg      ;  fold store into ALU op (RMW)
/// ```
#[derive(Debug, Clone)]
pub struct MemoryFoldRules {
    /// Set of opcodes that can fold a memory source operand.
    pub can_fold_load: HashSet<X86Opcode>,
    /// Set of opcodes that can fold a memory destination (RMW).
    pub can_fold_rmw: HashSet<X86Opcode>,
    /// Set of opcodes that can fold complex addressing (index*scale).
    pub can_fold_complex: HashSet<X86Opcode>,
    /// Maximum displacement value for folding (prevents massive displacements).
    pub max_fold_disp: i64,
}

impl Default for MemoryFoldRules {
    fn default() -> Self {
        let mut fold_load = HashSet::new();
        fold_load.insert(X86Opcode::ADD);
        fold_load.insert(X86Opcode::ADC);
        fold_load.insert(X86Opcode::SUB);
        fold_load.insert(X86Opcode::SBB);
        fold_load.insert(X86Opcode::AND);
        fold_load.insert(X86Opcode::OR);
        fold_load.insert(X86Opcode::XOR);
        fold_load.insert(X86Opcode::CMP);
        fold_load.insert(X86Opcode::TEST);
        fold_load.insert(X86Opcode::MOV);
        fold_load.insert(X86Opcode::MOVSX);
        fold_load.insert(X86Opcode::MOVZX);
        fold_load.insert(X86Opcode::IMUL);
        fold_load.insert(X86Opcode::BT);
        fold_load.insert(X86Opcode::BTC);
        fold_load.insert(X86Opcode::BTR);
        fold_load.insert(X86Opcode::BTS);
        fold_load.insert(X86Opcode::BSF);
        fold_load.insert(X86Opcode::BSR);
        fold_load.insert(X86Opcode::NEG);
        fold_load.insert(X86Opcode::NOT);
        fold_load.insert(X86Opcode::MUL);
        fold_load.insert(X86Opcode::PUSH);
        fold_load.insert(X86Opcode::ADDSS);
        fold_load.insert(X86Opcode::ADDSD);
        fold_load.insert(X86Opcode::SUBSS);
        fold_load.insert(X86Opcode::SUBSD);
        fold_load.insert(X86Opcode::MULSS);
        fold_load.insert(X86Opcode::MULSD);
        fold_load.insert(X86Opcode::DIVSS);
        fold_load.insert(X86Opcode::DIVSD);

        let mut fold_rmw = HashSet::new();
        fold_rmw.insert(X86Opcode::ADD);
        fold_rmw.insert(X86Opcode::ADC);
        fold_rmw.insert(X86Opcode::SUB);
        fold_rmw.insert(X86Opcode::SBB);
        fold_rmw.insert(X86Opcode::AND);
        fold_rmw.insert(X86Opcode::OR);
        fold_rmw.insert(X86Opcode::XOR);
        fold_rmw.insert(X86Opcode::INC);
        fold_rmw.insert(X86Opcode::DEC);
        fold_rmw.insert(X86Opcode::NEG);
        fold_rmw.insert(X86Opcode::NOT);
        fold_rmw.insert(X86Opcode::SHL);
        fold_rmw.insert(X86Opcode::SHR);
        fold_rmw.insert(X86Opcode::SAR);
        fold_rmw.insert(X86Opcode::ROL);
        fold_rmw.insert(X86Opcode::ROR);
        fold_rmw.insert(X86Opcode::RCL);
        fold_rmw.insert(X86Opcode::RCR);
        fold_rmw.insert(X86Opcode::BTC);
        fold_rmw.insert(X86Opcode::BTR);
        fold_rmw.insert(X86Opcode::BTS);

        Self {
            can_fold_load: fold_load,
            can_fold_rmw: fold_rmw,
            can_fold_complex: HashSet::new(),
            max_fold_disp: 2_147_483_647,
        }
    }
}

impl MemoryFoldRules {
    /// Check if a load can be folded into the given ALU opcode.
    pub fn can_fold_load_into(&self, opcode: X86Opcode) -> bool {
        self.can_fold_load.contains(&opcode)
    }

    /// Check if a store can be folded into the given ALU opcode (RMW).
    pub fn can_fold_rmw_into(&self, opcode: X86Opcode) -> bool {
        self.can_fold_rmw.contains(&opcode)
    }

    /// Check if the addressing mode is simple enough to fold.
    pub fn is_foldable(&self, addr: &X86AddressMode) -> bool {
        // Absolute addresses without a base cannot be folded into most ALU ops
        if addr.is_absolute_16 || (addr.is_absolute_32 && addr.width == AddrWidth::Addr32) {
            return false;
        }

        // RIP-relative is foldable in 64-bit mode
        if addr.is_rip_relative {
            return true;
        }

        // Complex addressing with index is foldable
        // (but may be restricted for some instructions)
        if addr.has_index() {
            return true;
        }

        // Check displacement range
        addr.displacement.abs() <= self.max_fold_disp
    }

    /// Get the most restrictive fold form possible.
    pub fn get_fold_form(&self, addr: &X86AddressMode) -> FoldForm {
        if !self.is_foldable(addr) {
            return FoldForm::CannotFold;
        }

        if addr.has_index() {
            if addr.fits_disp8() || addr.has_disp_zero() {
                FoldForm::FullWithIndex
            } else {
                FoldForm::FullWithIndexDisp32
            }
        } else if addr.has_disp_zero() {
            FoldForm::BaseOnly
        } else if addr.fits_disp8() {
            FoldForm::BaseDisp8
        } else {
            FoldForm::BaseDisp32
        }
    }
}

/// Forms of foldable memory operands.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FoldForm {
    CannotFold,
    BaseOnly,
    BaseDisp8,
    BaseDisp32,
    FullWithIndex,
    FullWithIndexDisp32,
}

// ============================================================================
// LEA Complexity Database
// ============================================================================

/// Database of LEA instruction complexity for different microarchitectures.
///
/// On modern CPUs, the complexity of a LEA determines its latency and
/// which execution ports it can use.
///
/// # LEA Complexity Classes
/// ```text
/// Class 1: LEA with base only    → 1 cycle, any ALU port
/// Class 2: LEA with base + index → 1 cycle, any ALU port
/// Class 3: LEA with scale        → 1 cycle, restricted ports (Intel)
/// Class 4: LEA with 3 components → 3 cycles (Intel), 1 cycle (AMD)
/// ```
#[derive(Debug, Clone)]
pub struct LeaComplexityDB {
    /// Latency for each LEA complexity class.
    pub latencies: [u32; 5],
    /// Whether class 3 LEAs can use any port.
    pub class3_any_port: bool,
    /// Whether class 4 LEAs are fast (1 cycle).
    pub class4_fast: bool,
}

impl LeaComplexityDB {
    /// Complexity DB for Intel Skylake and later (Client).
    pub fn intel_skylake_client() -> Self {
        Self {
            latencies: [0, 1, 1, 1, 3],
            class3_any_port: false,
            class4_fast: false,
        }
    }

    /// Complexity DB for Intel Ice Lake / Alder Lake.
    pub fn intel_ice_lake() -> Self {
        Self {
            latencies: [0, 1, 1, 1, 3],
            class3_any_port: false,
            class4_fast: false,
        }
    }

    /// Complexity DB for AMD Zen 3 / Zen 4 / Zen 5.
    pub fn amd_zen() -> Self {
        Self {
            latencies: [0, 1, 1, 1, 1],
            class3_any_port: true,
            class4_fast: true,
        }
    }

    /// Classify a LEA address mode into a complexity class.
    pub fn classify_lea(&self, addr: &X86AddressMode) -> u8 {
        let components = if addr.has_base() { 1 } else { 0 }
            + if addr.has_index() { 1 } else { 0 }
            + if addr.displacement != 0 { 1 } else { 0 };

        let has_scale = addr.scale > 1;

        match (components, has_scale) {
            (0, _) => 1,     // No components (unlikely)
            (1, false) => 1, // Base only, or index only
            (2, false) => 2, // Base + index (no scale), or base + disp, or index + disp
            (2, true) => 3,  // Base + scaled index, or scaled index + disp
            (3, false) => 3, // Base + index + disp (no scale)
            (3, true) => 4,  // Base + scaled index + disp
            _ => 4,
        }
    }

    /// Get the latency of a LEA for a given address mode.
    pub fn lea_latency(&self, addr: &X86AddressMode) -> u32 {
        let class = self.classify_lea(addr) as usize;
        if class < self.latencies.len() {
            self.latencies[class]
        } else {
            3
        }
    }
}

// ============================================================================
// Address Mode Selection Decision Tree
// ============================================================================

/// Decision tree for selecting the optimal addressing mode given
/// a set of constraints (registers available, displacement, etc.).
///
/// # Decision Flow
/// ```text
/// 1. Is the address a frame index?
///    → YES: Use [RBP/RSP + offset]
///    → NO:  Continue to step 2.
///
/// 2. Is the address a global symbol?
///    → YES and PIC/64-bit: Use [RIP + symbol]
///    → YES and non-PIC/32-bit: Use [abs addr]
///    → NO:  Continue to step 3.
///
/// 3. Is the address a TLS variable?
///    → YES: Use [FS/GS:offset]
///    → NO:  Continue to step 4.
///
/// 4. Can the address be expressed as base+disp?
///    → YES and disp fits in 8 bits: Use [base + disp8]
///    → YES and disp fits in 32 bits: Use [base + disp32]
///    → NO:  Continue to step 5.
///
/// 5. Does the address have an index*scale component?
///    → YES and disp == 0:    Use [base + index*scale]
///    → YES and disp fits 8:  Use [base + index*scale + disp8]
///    → YES and disp fits 32: Use [base + index*scale + disp32]
///    → NO:  Use simple form.
/// ```
#[derive(Debug, Clone)]
pub struct AddressSelectionDecisionTree {
    engine: X86AddressingFull,
    cost_model: AddressCostModel,
    pressure: RegisterPressureAnalysis,
    lea_db: LeaComplexityDB,
    fold_rules: MemoryFoldRules,
}

impl AddressSelectionDecisionTree {
    /// Create a new decision tree.
    pub fn new(engine: X86AddressingFull) -> Self {
        Self {
            engine,
            cost_model: AddressCostModel::default(),
            pressure: RegisterPressureAnalysis::default(),
            lea_db: LeaComplexityDB::intel_skylake_client(),
            fold_rules: MemoryFoldRules::default(),
        }
    }

    /// Select the best addressing mode for a memory operand.
    pub fn select_best_memory(
        &self,
        base: Option<u16>,
        index: Option<u16>,
        scale: u8,
        disp: i64,
        is_frame_idx: bool,
        is_global: bool,
        is_tls: bool,
    ) -> X86AddressMode {
        if is_tls {
            return self.select_tls_mode(disp);
        }

        if is_global {
            return self.select_global_mode(disp);
        }

        if is_frame_idx {
            return self.select_frame_mode(disp);
        }

        self.select_generic_mode(base, index, scale, disp)
    }

    /// Select TLS addressing mode.
    fn select_tls_mode(&self, offset: i64) -> X86AddressMode {
        let seg = if self.engine.addr_width == AddrWidth::Addr64 {
            x86_register_info::FS
        } else {
            x86_register_info::GS
        };
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_disp(offset)
            .with_segment(seg)
            .build()
    }

    /// Select global symbol addressing mode.
    fn select_global_mode(&self, disp: i64) -> X86AddressMode {
        if self.engine.is_pic && self.engine.addr_width == AddrWidth::Addr64 {
            X86AddressMode::rip_relative(disp).with_got_relative(true)
        } else if self.engine.addr_width == AddrWidth::Addr64 {
            X86AddressMode::rip_relative(disp)
        } else {
            X86AddressMode::absolute32(disp)
        }
    }

    /// Select frame index addressing mode.
    fn select_frame_mode(&self, offset: i64) -> X86AddressMode {
        let base = match self.engine.addr_width {
            AddrWidth::Addr64 => x86_register_info::RBP,
            AddrWidth::Addr32 => x86_register_info::EBP,
            AddrWidth::Addr16 => x86_register_info::BP,
        };
        X86AddressMode::base_disp64(base, -offset).with_frame_relative(true)
    }

    /// Select the best generic addressing mode.
    fn select_generic_mode(
        &self,
        base: Option<u16>,
        index: Option<u16>,
        scale: u8,
        disp: i64,
    ) -> X86AddressMode {
        // Try base+disp forms first (simple, 1 byte smaller than SIB)
        if let Some(b) = base {
            if index.is_none() || scale <= 1 {
                let simple = X86AddressingModeBuilder::new(self.engine.addr_width)
                    .with_base(b)
                    .with_disp(disp)
                    .build();

                let complex = X86AddressingModeBuilder::new(self.engine.addr_width)
                    .with_base(b)
                    .with_index_opt(index, scale)
                    .with_disp(disp)
                    .build();

                let simple_cost = self.cost_model.compute_cost(&simple);
                let complex_cost = self.cost_model.compute_cost(&complex);

                if simple_cost <= complex_cost || !self.pressure.can_use_index() {
                    return simple;
                }
                return complex;
            }
        }

        // Use full addressing if index is present and scale > 1
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base_opt(base)
            .with_index_opt(index, scale)
            .with_disp(disp)
            .build()
    }

    /// Select the best LEA form for an address computation.
    pub fn select_best_lea(
        &self,
        base: u16,
        index: Option<u16>,
        scale: u8,
        disp: i64,
    ) -> X86AddressMode {
        // LEA doesn't actually access memory, so we always want
        // the most compact form possible
        X86AddressingModeBuilder::new(self.engine.addr_width)
            .with_base(base)
            .with_index_opt(index, scale)
            .with_disp(disp)
            .build()
    }
}

// ============================================================================
// REX/VEX/EVEX Prefix Interaction with Addressing Modes
// ============================================================================

/// Handles the interaction between REX/VEX/EVEX prefixes and addressing modes.
///
/// # REX Prefix (1 byte)
/// ```text
/// Bits:  7    6    5    4    3    2    1    0
///       0    1    0    0    W    R    X    B
///
/// W = 64-bit operand size
/// R = Extension of ModR/M reg field
/// X = Extension of SIB index field
/// B = Extension of ModR/M r/m field, SIB base, or opcode reg
/// ```
///
/// # VEX Prefix (2 or 3 bytes)
/// Encodes the same register extensions as REX plus:
/// - Non-destructive 3-operand form
/// - AVX/AVX2 opcode map selection
/// - VEX.L (256-bit vector length)
///
/// # EVEX Prefix (4 bytes)
/// Extends VEX with:
/// - 512-bit vector length
/// - Mask register (opmask)
/// - Broadcast/rounding control
/// - 32 vector registers (XMM16-XMM31, etc.)
///
/// # REX Constraints on Addressing
/// - REX prefix must immediately precede the opcode
/// - Segment overrides go before REX
/// - Address size override (0x67) goes before REX
/// - AH/BH/CH/DH cannot be used with REX (they encode different registers)
/// - SPL/BPL/SIL/DIL require REX to be encoded
#[derive(Debug, Clone)]
pub struct PrefixInteraction {
    pub addr_width: AddrWidth,
}

impl PrefixInteraction {
    /// Create a new prefix handler.
    pub fn new(addr_width: AddrWidth) -> Self {
        Self { addr_width }
    }

    /// Encode a full REX prefix byte.
    ///
    /// # Arguments
    /// * `w` - REX.W (64-bit operand size)
    /// * `r` - REX.R (ModR/M reg extension)
    /// * `x` - REX.X (SIB index extension)
    /// * `b` - REX.B (ModR/M r/m, SIB base, or opcode reg extension)
    pub fn encode_rex(&self, w: bool, r: bool, x: bool, b: bool) -> u8 {
        let mut rex: u8 = 0x40;
        if w {
            rex |= 0x08;
        }
        if r {
            rex |= 0x04;
        }
        if x {
            rex |= 0x02;
        }
        if b {
            rex |= 0x01;
        }
        rex
    }

    /// Decode a REX prefix byte.
    pub fn decode_rex(&self, rex: u8) -> (bool, bool, bool, bool) {
        let w = (rex & 0x08) != 0;
        let r = (rex & 0x04) != 0;
        let x = (rex & 0x02) != 0;
        let b = (rex & 0x01) != 0;
        (w, r, x, b)
    }

    /// Check if a REX prefix is needed for a given addressing mode.
    pub fn needs_rex(&self, addr: &X86AddressMode) -> bool {
        if self.addr_width != AddrWidth::Addr64 {
            return false;
        }

        // Check base register
        if let Some(base) = addr.base {
            if base >= 8 {
                return true; // REX.B needed
            }
        }

        // Check index register
        if let Some(index) = addr.index {
            if index >= 8 {
                return true; // REX.X needed
            }
        }

        // 64-bit operand size always needs REX.W
        true
    }

    /// Generate the REX bits needed for an address mode.
    pub fn compute_rex_bits(&self, addr: &X86AddressMode) -> (bool, bool, bool) {
        let r: bool = false; // Reg extension (set by caller based on reg operand)
        let mut x: bool = false;
        let mut b: bool = false;

        if let Some(index) = addr.index {
            if index >= 8 {
                x = true;
            }
        }

        if let Some(base) = addr.base {
            if base >= 8 {
                b = true;
            }
        }

        (r, x, b)
    }

    /// Check if a REX prefix is valid (no AH/BH/CH/DH conflict).
    pub fn is_rex_valid_with_reg(&self, _reg: u16) -> bool {
        // AH/BH/CH/DH (regs 64-67) cannot be encoded with REX
        // because REX changes their encoding to SPL/BPL/SIL/DIL
        !matches!(_reg, 64 | 65 | 66 | 67)
    }

    /// Generate the address-size override prefix (0x67) if needed.
    pub fn needs_addr_size_override(&self, addr: &X86AddressMode) -> bool {
        match self.addr_width {
            AddrWidth::Addr64 => addr.width == AddrWidth::Addr32,
            AddrWidth::Addr32 => addr.width == AddrWidth::Addr16,
            AddrWidth::Addr16 => false,
        }
    }

    /// Encode all prefixes for an addressing mode in correct order.
    ///
    /// Prefix order matters:
    /// 1. Segment override (0x26, 0x2E, 0x36, 0x3E, 0x64, 0x65)
    /// 2. Address size override (0x67)
    /// 3. Operand size override (0x66)
    /// 4. REX (0x40-0x4F)
    pub fn encode_all_prefixes(&self, addr: &X86AddressMode, reg_field: u16) -> Vec<u8> {
        let mut prefixes = Vec::new();

        // 1. Segment override
        if let Some(_seg) = addr.segment {
            let seg_handler = X86SegmentHandling::new(X86AddressingFull::new(self.addr_width));
            if let Some(pfx) = seg_handler.segment_override_prefix(addr) {
                prefixes.push(pfx);
            }
        }

        // 2. Address size override
        if self.needs_addr_size_override(addr) {
            prefixes.push(0x67);
        }

        // 3. Operand size override (0x66) — handled by instruction logic
        // Not included here; depends on instruction-specific operand sizes

        // 4. REX
        if self.needs_rex(addr) {
            let (_r, x, b) = self.compute_rex_bits(addr);
            let r_bit = reg_field >= 8;
            let rex = self.encode_rex(true, r_bit, x, b);
            prefixes.push(rex);
        }

        prefixes
    }
}

// ============================================================================
// Addressing Mode Validation and Constraints
// ============================================================================

/// Validates addressing modes against X86 architectural constraints.
///
/// Not all combinations of base, index, scale, and displacement are
/// valid in all modes. This validator checks for common violations.
#[derive(Debug, Clone)]
pub struct AddressingModeValidator {
    width: AddrWidth,
}

impl AddressingModeValidator {
    /// Create a new validator.
    pub fn new(width: AddrWidth) -> Self {
        Self { width }
    }

    /// Check if the given addressing mode is architecturally valid.
    pub fn is_valid(&self, addr: &X86AddressMode) -> Result<(), AddressingError> {
        // Check width consistency
        if addr.width != self.width {
            return Err(AddressingError::WidthMismatch);
        }

        // Check base register validity
        if let Some(base) = addr.base {
            if !is_valid_base_reg(base, self.width) {
                return Err(AddressingError::InvalidBaseRegister(base));
            }
        }

        // Check index register validity
        if let Some(index) = addr.index {
            if !is_valid_index_reg(index, self.width) {
                return Err(AddressingError::InvalidIndexRegister(index));
            }
        }

        // Check scale validity
        if addr.scale > 0 && !is_valid_scale(addr.scale) {
            return Err(AddressingError::InvalidScale(addr.scale));
        }

        // Check displacement range
        if !self.is_displacement_valid(addr.displacement) {
            return Err(AddressingError::DisplacementOutOfRange(addr.displacement));
        }

        // RIP-relative constraints
        if addr.is_rip_relative {
            if self.width != AddrWidth::Addr64 {
                return Err(AddressingError::RipRelativeNotSupported);
            }
            if addr.base.is_some() || addr.index.is_some() {
                return Err(AddressingError::RipRelativeWithBaseIndex);
            }
        }

        // 16-bit mode constraints
        if self.width == AddrWidth::Addr16 {
            if addr.scale > 1 {
                return Err(AddressingError::ScaleNotSupportedIn16Bit);
            }
            if addr.base.is_some() && addr.index.is_some() {
                // Only valid combinations: BX+SI, BX+DI, BP+SI, BP+DI
                let valid = Self::is_valid_16bit_pair(addr.base.unwrap(), addr.index.unwrap());
                if !valid {
                    return Err(AddressingError::Invalid16BitPair);
                }
            }
        }

        // ESP/RSP cannot be an index
        if let Some(idx) = addr.index {
            let idx_enc = idx & 0x7;
            if idx_enc == 4 && self.width != AddrWidth::Addr16 {
                return Err(AddressingError::RspCannotBeIndex);
            }
        }

        Ok(())
    }

    /// Check if a 16-bit base+index pair is valid.
    fn is_valid_16bit_pair(base: u16, index: u16) -> bool {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};
        match (base, index) {
            (b, i) if b == BX && i == SI => true,
            (b, i) if b == BX && i == DI => true,
            (b, i) if b == BP && i == SI => true,
            (b, i) if b == BP && i == DI => true,
            _ => false,
        }
    }

    /// Check if a displacement is valid for the current mode.
    fn is_displacement_valid(&self, disp: i64) -> bool {
        match self.width {
            AddrWidth::Addr16 => disp >= -32768 && disp <= 32767,
            AddrWidth::Addr32 | AddrWidth::Addr64 => {
                disp >= -2_147_483_648 && disp <= 2_147_483_647
            }
        }
    }

    /// Suggest a fix for an invalid addressing mode.
    pub fn suggest_fix(&self, error: &AddressingError) -> Option<String> {
        match error {
            AddressingError::RspCannotBeIndex => {
                Some("Use a different index register; RSP cannot be an index.".into())
            }
            AddressingError::InvalidScale(s) => {
                let nearest = match s {
                    s if *s <= 1 => 1,
                    s if *s <= 2 => 2,
                    s if *s <= 4 => 4,
                    _ => 8,
                };
                Some(format!(
                    "Scale {} is invalid. Use 1, 2, 4, or 8. Nearest: {}",
                    s, nearest
                ))
            }
            AddressingError::RipRelativeNotSupported => {
                Some("RIP-relative addressing is only available in 64-bit mode.".into())
            }
            AddressingError::ScaleNotSupportedIn16Bit => {
                Some("16-bit mode does not support scaled index addressing.".into())
            }
            AddressingError::Invalid16BitPair => {
                Some("Valid 16-bit pairs: [BX+SI], [BX+DI], [BP+SI], [BP+DI].".into())
            }
            _ => None,
        }
    }
}

/// Errors that can occur when constructing or validating an addressing mode.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AddressingError {
    WidthMismatch,
    InvalidBaseRegister(u16),
    InvalidIndexRegister(u16),
    InvalidScale(u8),
    DisplacementOutOfRange(i64),
    RipRelativeNotSupported,
    RipRelativeWithBaseIndex,
    ScaleNotSupportedIn16Bit,
    Invalid16BitPair,
    RspCannotBeIndex,
    RbpWithZeroDisplacement,
    SegmentOverrideNotAllowed,
}

impl std::fmt::Display for AddressingError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            AddressingError::WidthMismatch => {
                write!(f, "Addressing mode width does not match current mode")
            }
            AddressingError::InvalidBaseRegister(r) => {
                write!(f, "Register {} is not a valid base register", r)
            }
            AddressingError::InvalidIndexRegister(r) => {
                write!(f, "Register {} is not a valid index register", r)
            }
            AddressingError::InvalidScale(s) => {
                write!(f, "Scale {} is invalid (must be 1, 2, 4, or 8)", s)
            }
            AddressingError::DisplacementOutOfRange(d) => {
                write!(f, "Displacement {} is out of range", d)
            }
            AddressingError::RipRelativeNotSupported => {
                write!(
                    f,
                    "RIP-relative addressing is only supported in 64-bit mode"
                )
            }
            AddressingError::RipRelativeWithBaseIndex => {
                write!(
                    f,
                    "RIP-relative addressing cannot have a base or index register"
                )
            }
            AddressingError::ScaleNotSupportedIn16Bit => {
                write!(f, "Scaled index addressing is not supported in 16-bit mode")
            }
            AddressingError::Invalid16BitPair => {
                write!(f, "Invalid base+index pair for 16-bit mode")
            }
            AddressingError::RspCannotBeIndex => {
                write!(f, "RSP/ESP cannot be used as an index register")
            }
            AddressingError::RbpWithZeroDisplacement => {
                write!(f, "[RBP] with zero displacement is not encodable")
            }
            AddressingError::SegmentOverrideNotAllowed => {
                write!(f, "Segment override is not allowed in this context")
            }
        }
    }
}

impl std::error::Error for AddressingError {}

// ============================================================================
// Complete ModR/M + SIB Encoding Table (Full Enumeration)
// ============================================================================

/// Full enumeration of all valid ModR/M + SIB + displacement combinations
/// for 32/64-bit addressing modes.
#[derive(Debug, Clone)]
pub struct CompleteModRMTable {
    /// All ModR/M entries.
    pub entries: Vec<CompleteModRMEntry>,
    /// Lookup by ModR/M byte.
    pub by_modrm: BTreeMap<u8, Vec<CompleteModRMEntry>>,
    /// Lookup by form.
    pub by_form: HashMap<ModRMForm, Vec<CompleteModRMEntry>>,
}

/// A complete ModR/M table entry with all encoding details.
#[derive(Debug, Clone)]
pub struct CompleteModRMEntry {
    /// The ModR/M byte.
    pub modrm: u8,
    /// The Mod field (0-3).
    pub mod_field: u8,
    /// The Reg/opcode field (0-7).
    pub reg_field: u8,
    /// The R/M field (0-7).
    pub rm_field: u8,
    /// Addressing form.
    pub form: ModRMForm,
    /// Base register (3-bit encoding), if any.
    pub base: Option<u8>,
    /// Index register (3-bit encoding), if any.
    pub index: Option<u8>,
    /// Scale factor (1, 2, 4, 8).
    pub scale: u8,
    /// Whether SIB is used.
    pub has_sib: bool,
    /// SIB byte (if has_sib).
    pub sib_byte: Option<u8>,
    /// Whether displacement is present.
    pub has_disp: bool,
    /// Displacement size in bytes.
    pub disp_size: u8,
    /// Human-readable description.
    pub description: &'static str,
}

impl CompleteModRMTable {
    /// Generate the complete table for 64-bit mode.
    pub fn generate_64bit() -> Self {
        Self::generate(AddrWidth::Addr64)
    }

    /// Generate the complete table for 32-bit mode.
    pub fn generate_32bit() -> Self {
        Self::generate(AddrWidth::Addr32)
    }

    /// Generate the complete table for a given width.
    pub fn generate(width: AddrWidth) -> Self {
        let mut entries = Vec::new();
        let mut by_modrm: BTreeMap<u8, Vec<CompleteModRMEntry>> = BTreeMap::new();
        let mut by_form: HashMap<ModRMForm, Vec<CompleteModRMEntry>> = HashMap::new();

        // Enumerate all ModR/M and SIB combinations
        for mod_field in 0u8..4 {
            for reg_field in 0u8..8 {
                for rm_field in 0u8..8 {
                    let modrm = (mod_field << 6) | (reg_field << 3) | rm_field;

                    if mod_field == 3 {
                        // Register-direct mode
                        let entry = CompleteModRMEntry {
                            modrm,
                            mod_field,
                            reg_field,
                            rm_field,
                            form: ModRMForm::RegisterDirect,
                            base: Some(rm_field),
                            index: None,
                            scale: 1,
                            has_sib: false,
                            sib_byte: None,
                            has_disp: false,
                            disp_size: 0,
                            description: "register-direct",
                        };
                        entries.push(entry);
                        continue;
                    }

                    if rm_field == 4 && width.uses_sib() {
                        Self::generate_sib_entries(
                            mod_field,
                            reg_field,
                            rm_field,
                            modrm,
                            width,
                            &mut entries,
                        );
                    } else {
                        Self::generate_direct_entries(
                            mod_field,
                            reg_field,
                            rm_field,
                            modrm,
                            width,
                            &mut entries,
                        );
                    }
                }
            }
        }

        // Build lookup maps
        for entry in &entries {
            by_modrm.entry(entry.modrm).or_default().push(entry.clone());
            by_form.entry(entry.form).or_default().push(entry.clone());
        }

        Self {
            entries,
            by_modrm,
            by_form,
        }
    }

    fn generate_direct_entries(
        mod_field: u8,
        reg_field: u8,
        rm_field: u8,
        modrm: u8,
        width: AddrWidth,
        entries: &mut Vec<CompleteModRMEntry>,
    ) {
        let (form, has_disp, disp_size, description) = match (mod_field, rm_field, width) {
            (0, 5, AddrWidth::Addr64) => (ModRMForm::RIPRelative, true, 4, "[RIP + disp32]"),
            (0, 5, AddrWidth::Addr32) => (ModRMForm::Absolute, true, 4, "[disp32]"),
            (0, _, _) => (ModRMForm::BaseOnly, false, 0, "[base]"),
            (1, _, _) => (ModRMForm::BaseDisp8, true, 1, "[base + disp8]"),
            (2, _, _) => (ModRMForm::BaseDisp32, true, 4, "[base + disp32]"),
            _ => (ModRMForm::BaseOnly, false, 0, "[base]"),
        };

        entries.push(CompleteModRMEntry {
            modrm,
            mod_field,
            reg_field,
            rm_field,
            form,
            base: if form != ModRMForm::Absolute && form != ModRMForm::RIPRelative {
                Some(rm_field)
            } else {
                None
            },
            index: None,
            scale: 1,
            has_sib: false,
            sib_byte: None,
            has_disp,
            disp_size,
            description,
        });
    }

    fn generate_sib_entries(
        mod_field: u8,
        reg_field: u8,
        _rm_field: u8,
        modrm: u8,
        width: AddrWidth,
        entries: &mut Vec<CompleteModRMEntry>,
    ) {
        for scale_bits in 0u8..4 {
            for index_field in 0u8..8 {
                for base_field in 0u8..8 {
                    // Skip the special "no base, no index" case for mod=00
                    if mod_field == 0 && base_field == 5 && index_field == 4 {
                        // This is the [disp32] form via SIB
                        entries.push(CompleteModRMEntry {
                            modrm,
                            mod_field,
                            reg_field,
                            rm_field: 4,
                            form: if width == AddrWidth::Addr64 {
                                ModRMForm::RIPRelative
                            } else {
                                ModRMForm::Absolute
                            },
                            base: None,
                            index: None,
                            scale: 1,
                            has_sib: true,
                            sib_byte: Some(
                                (scale_bits << 6) | ((index_field & 0x7) << 3) | (base_field & 0x7),
                            ),
                            has_disp: true,
                            disp_size: 4,
                            description: "[disp32 via SIB]",
                        });
                        continue;
                    }

                    let sib = (scale_bits << 6) | ((index_field & 0x7) << 3) | (base_field & 0x7);

                    let scale: u8 = match scale_bits {
                        0 => 1,
                        1 => 2,
                        2 => 4,
                        3 => 8,
                        _ => 1,
                    };

                    let has_index = index_field != 4;
                    let base_is_disp32 = mod_field == 0 && base_field == 5;
                    let actual_base = if base_is_disp32 {
                        None
                    } else {
                        Some(base_field)
                    };
                    let actual_index = if has_index { Some(index_field) } else { None };

                    let (form, has_disp, disp_size, description) =
                        match (mod_field, base_is_disp32, has_index) {
                            (0, _, true) => {
                                (ModRMForm::BaseIndexScale, false, 0, "[base + index*scale]")
                            }
                            (0, false, false) => (ModRMForm::BaseOnly, false, 0, "[base] via SIB"),
                            (1, _, true) => (
                                ModRMForm::BaseIndexScaleDisp8,
                                true,
                                1,
                                "[base + index*scale + disp8]",
                            ),
                            (1, false, false) => {
                                (ModRMForm::BaseDisp8, true, 1, "[base + disp8] via SIB")
                            }
                            (2, _, true) => (
                                ModRMForm::BaseIndexScaleDisp32,
                                true,
                                4,
                                "[base + index*scale + disp32]",
                            ),
                            (2, false, false) => {
                                (ModRMForm::BaseDisp32, true, 4, "[base + disp32] via SIB")
                            }
                            _ => (ModRMForm::BaseOnly, false, 0, "[base] via SIB"),
                        };

                    entries.push(CompleteModRMEntry {
                        modrm,
                        mod_field,
                        reg_field,
                        rm_field: 4,
                        form,
                        base: actual_base,
                        index: actual_index,
                        scale,
                        has_sib: true,
                        sib_byte: Some(sib),
                        has_disp,
                        disp_size,
                        description,
                    });
                }
            }
        }
    }

    /// Lookup the addressing mode for a given ModR/M byte.
    pub fn lookup_modrm(&self, modrm: u8) -> Option<&CompleteModRMEntry> {
        self.by_modrm.get(&modrm).and_then(|v| v.first())
    }

    /// Get all entries of a given form.
    pub fn entries_by_form(&self, form: ModRMForm) -> &[CompleteModRMEntry] {
        self.by_form.get(&form).map(|v| v.as_slice()).unwrap_or(&[])
    }

    /// Get the total count of entries in the table.
    pub fn total_entries(&self) -> usize {
        self.entries.len()
    }
}

// ============================================================================
// 7. Complete Test Suite
// ============================================================================

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

    // ========================================================================
    // Helper functions
    // ========================================================================

    fn make_reg_info() -> X86RegisterInfo {
        X86RegisterInfo
    }

    // ========================================================================
    // AddrWidth tests
    // ========================================================================

    #[test]
    fn test_addr_width_default_data_size() {
        assert_eq!(AddrWidth::Addr16.default_data_size(), 2);
        assert_eq!(AddrWidth::Addr32.default_data_size(), 4);
        assert_eq!(AddrWidth::Addr64.default_data_size(), 8);
    }

    #[test]
    fn test_addr_width_max_disp_bits() {
        assert_eq!(AddrWidth::Addr16.max_disp_bits(), 16);
        assert_eq!(AddrWidth::Addr32.max_disp_bits(), 32);
        assert_eq!(AddrWidth::Addr64.max_disp_bits(), 32);
    }

    #[test]
    fn test_addr_width_rip_relative_support() {
        assert!(!AddrWidth::Addr16.supports_rip_relative());
        assert!(!AddrWidth::Addr32.supports_rip_relative());
        assert!(AddrWidth::Addr64.supports_rip_relative());
    }

    #[test]
    fn test_addr_width_uses_sib() {
        assert!(!AddrWidth::Addr16.uses_sib());
        assert!(AddrWidth::Addr32.uses_sib());
        assert!(AddrWidth::Addr64.uses_sib());
    }

    // ========================================================================
    // X86AddressingFull tests
    // ========================================================================

    #[test]
    fn test_addressing_full_new() {
        let e = X86AddressingFull::new_x86_64();
        assert_eq!(e.addr_width, AddrWidth::Addr64);

        let e32 = X86AddressingFull::new_x86_32();
        assert_eq!(e32.addr_width, AddrWidth::Addr32);

        let e16 = X86AddressingFull::new_x86_16();
        assert_eq!(e16.addr_width, AddrWidth::Addr16);
    }

    #[test]
    fn test_addressing_full_with_code_model() {
        let e = X86AddressingFull::new_x86_64().with_code_model(CodeModel::Large);
        assert_eq!(e.code_model, CodeModel::Large);
    }

    #[test]
    fn test_addressing_full_with_pic() {
        let e = X86AddressingFull::new_x86_64().with_pic(false);
        assert!(!e.is_pic);
    }

    #[test]
    fn test_addressing_full_with_tls_model() {
        let e = X86AddressingFull::new_x86_64().with_tls_model(TlsModel::LocalExec);
        assert_eq!(e.tls_model, TlsModel::LocalExec);
    }

    #[test]
    fn test_addressing_full_default() {
        let e = X86AddressingFull::default();
        assert_eq!(e.addr_width, AddrWidth::Addr64);
        assert!(e.is_pic);
        assert_eq!(e.tls_model, TlsModel::InitialExec);
    }

    // ========================================================================
    // X86AddressMode tests — Constructors
    // ========================================================================

    #[test]
    fn test_address_mode_base64() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.width, AddrWidth::Addr64);
        assert_eq!(m.base, Some(x86_register_info::RAX));
        assert_eq!(m.index, None);
        assert_eq!(m.displacement, 0);
    }

    #[test]
    fn test_address_mode_base_disp64() {
        let m = X86AddressMode::base_disp64(x86_register_info::RBX, 16);
        assert_eq!(m.base, Some(x86_register_info::RBX));
        assert_eq!(m.displacement, 16);
    }

    #[test]
    fn test_address_mode_full64() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        assert_eq!(m.base, Some(x86_register_info::RBX));
        assert_eq!(m.index, Some(x86_register_info::RSI));
        assert_eq!(m.scale, 4);
        assert_eq!(m.displacement, 8);
    }

    #[test]
    fn test_address_mode_rip_relative() {
        let m = X86AddressMode::rip_relative(42);
        assert!(m.is_rip_relative);
        assert_eq!(m.displacement, 42);
        assert_eq!(m.base, None);
    }

    #[test]
    fn test_address_mode_rip_symbol() {
        let m = X86AddressMode::rip_symbol("foo", 0);
        assert!(m.is_rip_relative);
        assert_eq!(m.symbol, Some("foo".to_string()));
    }

    #[test]
    fn test_address_mode_base32() {
        let m = X86AddressMode::base32(x86_register_info::EAX);
        assert_eq!(m.width, AddrWidth::Addr32);
        assert_eq!(m.base, Some(x86_register_info::EAX));
    }

    #[test]
    fn test_address_mode_absolute32() {
        let m = X86AddressMode::absolute32(0x1000);
        assert!(m.is_absolute_32);
        assert_eq!(m.displacement, 0x1000);
    }

    #[test]
    fn test_address_mode_base16() {
        let m = X86AddressMode::base16(x86_register_info::BX);
        assert_eq!(m.width, AddrWidth::Addr16);
        assert_eq!(m.base, Some(x86_register_info::BX));
        assert_eq!(m.form_16bit, Some(X86Addr16Form::Bx));
    }

    #[test]
    fn test_address_mode_base_index16() {
        let m = X86AddressMode::base_index16(x86_register_info::BX, x86_register_info::SI);
        assert_eq!(m.width, AddrWidth::Addr16);
        assert_eq!(m.base, Some(x86_register_info::BX));
        assert_eq!(m.index, Some(x86_register_info::SI));
        assert_eq!(m.form_16bit, Some(X86Addr16Form::BxSi));
    }

    #[test]
    fn test_address_mode_absolute16() {
        let m = X86AddressMode::absolute16(0x200);
        assert!(m.is_absolute_16);
        assert_eq!(m.displacement, 0x200);
        assert_eq!(m.form_16bit, Some(X86Addr16Form::Disp16));
    }

    #[test]
    fn test_address_mode_with_segment() {
        let m = X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::FS);
        assert_eq!(m.segment, Some(x86_register_info::FS));
    }

    #[test]
    fn test_address_mode_with_frame_relative() {
        let m = X86AddressMode::base64(x86_register_info::RBP).with_frame_relative(true);
        assert!(m.is_frame_relative);
    }

    #[test]
    fn test_address_mode_with_symbol() {
        let m = X86AddressMode::rip_relative(0).with_symbol("my_var");
        assert_eq!(m.symbol, Some("my_var".to_string()));
    }

    #[test]
    fn test_address_mode_with_got_relative() {
        let m = X86AddressMode::rip_relative(0).with_got_relative(true);
        assert!(m.is_got_relative);
    }

    // ========================================================================
    // X86AddressMode tests — Queries
    // ========================================================================

    #[test]
    fn test_has_base() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert!(m.has_base());
        let n = X86AddressMode::default();
        assert!(!n.has_base());
    }

    #[test]
    fn test_has_index() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 2, 0);
        assert!(m.has_index());
        let n = X86AddressMode::base64(x86_register_info::RAX);
        assert!(!n.has_index());
    }

    #[test]
    fn test_fits_disp8() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert!(m.fits_disp8());
        let n = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert!(!n.fits_disp8());
        let z = X86AddressMode::base_disp64(x86_register_info::RAX, -128);
        assert!(z.fits_disp8());
    }

    #[test]
    fn test_fits_disp32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 2_147_483_647);
        assert!(m.fits_disp32());
        let n = X86AddressMode::base_disp64(x86_register_info::RAX, 3_000_000_000i64);
        assert!(!n.fits_disp32());
    }

    #[test]
    fn test_fits_disp16() {
        let m = X86AddressMode::base16(x86_register_info::BX);
        let m2 = X86AddressMode {
            displacement: 32767,
            ..m.clone()
        };
        assert!(m2.fits_disp16());
        let m3 = X86AddressMode {
            displacement: 32768,
            ..m
        };
        assert!(!m3.fits_disp16());
    }

    // ========================================================================
    // X86AddressMode tests — Classification
    // ========================================================================

    #[test]
    fn test_classify_base_only() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.classify(), AddressingForm::BaseOnly);
    }

    #[test]
    fn test_classify_base_disp8() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m.classify(), AddressingForm::BaseDisp8);
    }

    #[test]
    fn test_classify_base_disp32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert_eq!(m.classify(), AddressingForm::BaseDisp32);
    }

    #[test]
    fn test_classify_rip_relative() {
        let m = X86AddressMode::rip_relative(42);
        assert_eq!(m.classify(), AddressingForm::RipRelative);
    }

    #[test]
    fn test_classify_absolute16() {
        let m = X86AddressMode::absolute16(0x200);
        assert_eq!(m.classify(), AddressingForm::Absolute16);
    }

    #[test]
    fn test_classify_absolute32() {
        let m = X86AddressMode::absolute32(0x1000);
        assert_eq!(m.classify(), AddressingForm::Absolute32);
    }

    #[test]
    fn test_classify_base_index_scale() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert_eq!(m.classify(), AddressingForm::BaseIndexScale);
    }

    #[test]
    fn test_classify_base_index_scale_disp8() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 42);
        assert_eq!(m.classify(), AddressingForm::BaseIndexScaleDisp8);
    }

    #[test]
    fn test_classify_base_index_scale_disp32() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 200);
        assert_eq!(m.classify(), AddressingForm::BaseIndexScaleDisp32);
    }

    // ========================================================================
    // X86AddressMode tests — SIB requirement
    // ========================================================================

    #[test]
    fn test_requires_sib_with_index() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_requires_sib_no_index_no_sib() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert!(!m.requires_sib());
    }

    #[test]
    fn test_requires_sib_rsp() {
        let m = X86AddressMode::base64(x86_register_info::RSP);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_requires_sib_r12() {
        let m = X86AddressMode::base64(x86_register_info::R12);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_requires_sib_rbp_64bit() {
        let m = X86AddressMode::base64(x86_register_info::RBP);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_requires_sib_r13_64bit() {
        let m = X86AddressMode::base64(x86_register_info::R13);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_requires_sib_16bit() {
        let m = X86AddressMode::base16(x86_register_info::BX);
        assert!(!m.requires_sib());
    }

    // ========================================================================
    // X86AddressMode tests — REX requirement
    // ========================================================================

    #[test]
    fn test_requires_rex_r8() {
        let m = X86AddressMode::base64(x86_register_info::R8);
        assert!(m.requires_rex());
    }

    #[test]
    fn test_requires_rex_r8_index() {
        let m = X86AddressMode::full64(x86_register_info::RAX, x86_register_info::R8, 1, 0);
        assert!(m.requires_rex());
    }

    #[test]
    fn test_requires_rex_none_for_low_regs() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert!(!m.requires_rex());
    }

    // ========================================================================
    // X86AddressMode tests — Encoding
    // ========================================================================

    #[test]
    fn test_encode_modrm_base_only() {
        // [RAX]: mod=00, reg=0, r/m=0
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.encode_modrm(0), 0x00);
    }

    #[test]
    fn test_encode_modrm_rip_relative() {
        // [RIP + disp32]: mod=00, reg=0, r/m=5
        let m = X86AddressMode::rip_relative(42);
        assert_eq!(m.encode_modrm(0), 0x05);
    }

    #[test]
    fn test_encode_modrm_base_disp8() {
        // [RAX + 42]: mod=01, reg=0, r/m=0
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m.encode_modrm(0), 0x40);
    }

    #[test]
    fn test_encode_modrm_base_disp32() {
        // [RAX + 200]: mod=10, reg=0, r/m=0
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert_eq!(m.encode_modrm(0), 0x80);
    }

    #[test]
    fn test_encode_modrm_with_reg_field() {
        // [RAX]: mod=00, reg=1 (RCX), r/m=0
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.encode_modrm(1), 0x08);
    }

    #[test]
    fn test_encode_sib() {
        // [RBX + RSI*4]: scale=2, index=6, base=3
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let sib = m.encode_sib();
        assert_eq!((sib >> 6) & 0x3, 2); // scale=4
        assert_eq!((sib >> 3) & 0x7, x86_register_info::RSI & 0x7); // index
        assert_eq!(sib & 0x7, x86_register_info::RBX & 0x7); // base
    }

    #[test]
    fn test_encode_sib_no_index() {
        // [RSP]: scale=0, index=4 (none), base=4
        let m = X86AddressMode::base64(x86_register_info::RSP);
        let sib = m.encode_sib();
        assert_eq!(sib, 0x24);
    }

    #[test]
    fn test_displacement_size_zero() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.displacement_size(), 0);
    }

    #[test]
    fn test_displacement_size_8() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m.displacement_size(), 1);
    }

    #[test]
    fn test_displacement_size_32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert_eq!(m.displacement_size(), 4);
    }

    #[test]
    fn test_encode_displacement_zero() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.encode_displacement(), Vec::<u8>::new());
    }

    #[test]
    fn test_encode_displacement_8() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m.encode_displacement(), vec![42]);
    }

    #[test]
    fn test_encode_displacement_32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 0x12345678);
        let expected = vec![0x78, 0x56, 0x34, 0x12];
        assert_eq!(m.encode_displacement(), expected);
    }

    #[test]
    fn test_encode_displacement_negative() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, -1);
        let expected = vec![0xFF, 0xFF, 0xFF, 0xFF];
        assert_eq!(m.encode_displacement(), expected);
    }

    #[test]
    fn test_encode_full() {
        // [RAX]: ModR/M only
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.encode_full(0), vec![0x00]);

        // [RAX + 42]: ModR/M + disp8
        let m2 = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m2.encode_full(0), vec![0x40, 0x2A]);

        // [RBX + RSI*4]: ModR/M + SIB
        let m3 = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let result = m3.encode_full(0);
        assert_eq!(result.len(), 2); // ModR/M + SIB
        assert_eq!(result[0] & 0xC7, 0x04); // mod=00, reg=0, r/m=4
    }

    // ========================================================================
    // X86AddressMode tests — Complexity
    // ========================================================================

    #[test]
    fn test_complexity_simple() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(m.complexity_score(), 1);
    }

    #[test]
    fn test_complexity_with_disp8() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(m.complexity_score(), 2); // 1 base + 1 disp8
    }

    #[test]
    fn test_complexity_full() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 200);
        let score = m.complexity_score();
        assert!(score >= 5); // 1 base + 2 index + 1 scale + 4 disp32 + 1 sib
    }

    // ========================================================================
    // X86AddressMode tests — MemOperand conversion
    // ========================================================================

    #[test]
    fn test_to_mem_operand() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        let mem = m.to_mem_operand();
        assert_eq!(mem.base, x86_register_info::RBX);
        assert_eq!(mem.index, x86_register_info::RSI);
        assert_eq!(mem.scale, 4);
        assert_eq!(mem.displacement, 8);
        assert_eq!(mem.segment, 0);
    }

    #[test]
    fn test_from_mem_operand() {
        let mem = X86MemOperand::full(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        let m = X86AddressMode::from_mem_operand(&mem, AddrWidth::Addr64);
        assert_eq!(m.base, Some(x86_register_info::RBX));
        assert_eq!(m.index, Some(x86_register_info::RSI));
        assert_eq!(m.scale, 4);
        assert_eq!(m.displacement, 8);
    }

    // ========================================================================
    // X86Addr16Form tests
    // ========================================================================

    #[test]
    fn test_addr16_form_rm_field() {
        assert_eq!(X86Addr16Form::BxSi.rm_field(), 0);
        assert_eq!(X86Addr16Form::BxDi.rm_field(), 1);
        assert_eq!(X86Addr16Form::BpSi.rm_field(), 2);
        assert_eq!(X86Addr16Form::BpDi.rm_field(), 3);
        assert_eq!(X86Addr16Form::Si.rm_field(), 4);
        assert_eq!(X86Addr16Form::Di.rm_field(), 5);
        assert_eq!(X86Addr16Form::Bp.rm_field(), 6);
        assert_eq!(X86Addr16Form::Bx.rm_field(), 7);
    }

    #[test]
    fn test_addr16_form_mod_field() {
        assert_eq!(X86Addr16Form::BxSi.mod_field(), Mod00);
        assert_eq!(X86Addr16Form::Bp.mod_field(), Mod01);
        assert_eq!(X86Addr16Form::BxDisp8.mod_field(), Mod01);
        assert_eq!(X86Addr16Form::BxDisp16.mod_field(), Mod10);
    }

    #[test]
    fn test_addr16_form_has_displacement() {
        assert!(!X86Addr16Form::BxSi.has_displacement());
        assert!(X86Addr16Form::Bp.has_displacement());
        assert!(X86Addr16Form::BxDisp8.has_displacement());
        assert!(X86Addr16Form::Disp16.has_displacement());
    }

    #[test]
    fn test_addr16_form_disp_size() {
        assert_eq!(X86Addr16Form::BxSi.disp_size(), 0);
        assert_eq!(X86Addr16Form::Bp.disp_size(), 1);
        assert_eq!(X86Addr16Form::BxDisp8.disp_size(), 1);
        assert_eq!(X86Addr16Form::BxDisp16.disp_size(), 2);
        assert_eq!(X86Addr16Form::Disp16.disp_size(), 2);
    }

    #[test]
    fn test_addr16_form_effective_base() {
        assert_eq!(
            X86Addr16Form::BxSi.effective_base(),
            Some(x86_register_info::BX)
        );
        assert_eq!(
            X86Addr16Form::BpSi.effective_base(),
            Some(x86_register_info::BP)
        );
        assert_eq!(
            X86Addr16Form::Si.effective_base(),
            Some(x86_register_info::SI)
        );
        assert_eq!(
            X86Addr16Form::Di.effective_base(),
            Some(x86_register_info::DI)
        );
        assert_eq!(
            X86Addr16Form::Bx.effective_base(),
            Some(x86_register_info::BX)
        );
        assert_eq!(X86Addr16Form::Disp16.effective_base(), None);
    }

    #[test]
    fn test_addr16_form_effective_index() {
        assert_eq!(
            X86Addr16Form::BxSi.effective_index(),
            Some(x86_register_info::SI)
        );
        assert_eq!(
            X86Addr16Form::BxDi.effective_index(),
            Some(x86_register_info::DI)
        );
        assert_eq!(X86Addr16Form::Si.effective_index(), None);
        assert_eq!(X86Addr16Form::Bx.effective_index(), None);
    }

    #[test]
    fn test_addr16_form_name() {
        assert_eq!(X86Addr16Form::BxSi.name(), "[BX+SI]");
        assert_eq!(X86Addr16Form::Bx.name(), "[BX]");
        assert_eq!(X86Addr16Form::Disp16.name(), "[disp16]");
    }

    #[test]
    fn test_addr16_form_decode() {
        // mod=00, r/m=0 → [BX+SI]
        assert_eq!(X86Addr16Form::decode(0x00), X86Addr16Form::BxSi);

        // mod=01, r/m=7 → [BX+disp8]
        assert_eq!(X86Addr16Form::decode(0x47), X86Addr16Form::BxDisp8);

        // mod=10, r/m=6 → [BP+disp16]
        assert_eq!(X86Addr16Form::decode(0x8E), X86Addr16Form::BpDisp16);

        // mod=00, r/m=6 → [disp16]
        assert_eq!(X86Addr16Form::decode(0x06), X86Addr16Form::Disp16);
    }

    #[test]
    fn test_addr16_form_decode_all() {
        // Verify all 24 valid forms decode uniquely
        let mut seen = HashSet::new();

        // mod=00 forms
        for rm in 0..8u8 {
            let modrm = (Mod00 << 6) | rm;
            seen.insert(X86Addr16Form::decode(modrm));
        }

        // mod=01 forms
        for rm in 0..8u8 {
            let modrm = (Mod01 << 6) | rm;
            seen.insert(X86Addr16Form::decode(modrm));
        }

        // mod=10 forms
        for rm in 0..8u8 {
            let modrm = (Mod10 << 6) | rm;
            seen.insert(X86Addr16Form::decode(modrm));
        }

        // Should have all 24 unique forms
        assert_eq!(seen.len(), 24);
    }

    // ========================================================================
    // AddressingForm tests
    // ========================================================================

    #[test]
    fn test_addressing_form_encoding_overhead() {
        assert_eq!(AddressingForm::BaseOnly.encoding_overhead(), 1);
        assert_eq!(AddressingForm::BaseDisp8.encoding_overhead(), 2);
        assert_eq!(AddressingForm::BaseDisp32.encoding_overhead(), 5);
        assert_eq!(AddressingForm::BaseIndexScale.encoding_overhead(), 2);
        assert_eq!(AddressingForm::BaseIndexScaleDisp8.encoding_overhead(), 3);
        assert_eq!(AddressingForm::BaseIndexScaleDisp32.encoding_overhead(), 6);
        assert_eq!(AddressingForm::RipRelative.encoding_overhead(), 5);
        assert_eq!(AddressingForm::Absolute32.encoding_overhead(), 5);
    }

    #[test]
    fn test_addressing_form_uses_sib() {
        assert!(!AddressingForm::BaseOnly.uses_sib());
        assert!(AddressingForm::BaseIndexScale.uses_sib());
        assert!(AddressingForm::BaseIndexScaleDisp8.uses_sib());
        assert!(!AddressingForm::RipRelative.uses_sib());
    }

    // ========================================================================
    // X86AddressingModeBuilder tests
    // ========================================================================

    #[test]
    fn test_builder_new() {
        let b = X86AddressingModeBuilder::new64();
        assert_eq!(b.build().width, AddrWidth::Addr64);
    }

    #[test]
    fn test_builder_simple() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .build();
        assert_eq!(m.base, Some(x86_register_info::RAX));
        assert_eq!(m.displacement, 0);
    }

    #[test]
    fn test_builder_full() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 4)
            .with_disp(16)
            .build();
        assert_eq!(m.base, Some(x86_register_info::RBX));
        assert_eq!(m.index, Some(x86_register_info::RSI));
        assert_eq!(m.scale, 4);
        assert_eq!(m.displacement, 16);
    }

    #[test]
    fn test_builder_canonicalize_scale() {
        // Invalid scales are canonicalized to valid ones
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 3)
            .build();
        assert_eq!(m.scale, 4);

        let m2 = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 0)
            .build();
        assert_eq!(m2.scale, 1);
    }

    #[test]
    fn test_builder_canonicalize_zero_index_scale() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .with_index_opt(Some(x86_register_info::RSI), 0)
            .build();
        // Scale=0 should remove the index
        assert_eq!(m.index, None);
        assert_eq!(m.scale, 0);
    }

    #[test]
    fn test_builder_rip_relative() {
        let m = X86AddressingModeBuilder::new64()
            .with_rip_relative(true)
            .with_disp(42)
            .build();
        assert!(m.is_rip_relative);
        assert_eq!(m.base, None);
        assert_eq!(m.displacement, 42);
    }

    #[test]
    fn test_builder_segment() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .with_segment(x86_register_info::FS)
            .build();
        assert_eq!(m.segment, Some(x86_register_info::FS));
    }

    #[test]
    fn test_builder_symbol() {
        let m = X86AddressingModeBuilder::new64()
            .with_symbol("test_var")
            .with_rip_relative(true)
            .build();
        assert_eq!(m.symbol, Some("test_var".to_string()));
    }

    #[test]
    fn test_builder_got_relative() {
        let m = X86AddressingModeBuilder::new64()
            .with_got_relative(true)
            .with_rip_relative(true)
            .build();
        assert!(m.is_got_relative);
    }

    #[test]
    fn test_builder_frame_relative() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBP)
            .with_frame_relative(true)
            .build();
        assert!(m.is_frame_relative);
    }

    #[test]
    fn test_builder_complexity_score() {
        let score_simple = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .complexity_score();
        assert_eq!(score_simple, 1);

        let score_complex = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 4)
            .with_disp(200)
            .complexity_score();
        assert!(score_complex > 4);
    }

    #[test]
    fn test_builder_select_best_form() {
        let form_simple = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .select_best_form();
        assert_eq!(form_simple, AddressingForm::BaseOnly);

        let form_rip = X86AddressingModeBuilder::new64()
            .with_rip_relative(true)
            .with_disp(42)
            .select_best_form();
        assert_eq!(form_rip, AddressingForm::RipRelative);

        let form_complex = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 4)
            .with_disp(42)
            .select_best_form();
        assert_eq!(form_complex, AddressingForm::BaseIndexScaleDisp8);
    }

    #[test]
    fn test_builder_determine_16bit_form() {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};

        let b = X86AddressingModeBuilder::new16()
            .with_base(BX)
            .with_index(SI, 1);
        let m = b.build();
        assert_eq!(m.form_16bit, Some(X86Addr16Form::BxSi));

        let b2 = X86AddressingModeBuilder::new16()
            .with_base(BX)
            .with_disp(42);
        let m2 = b2.build();
        assert_eq!(m2.form_16bit, Some(X86Addr16Form::BxDisp8));

        let b3 = X86AddressingModeBuilder::new16().with_disp(0x200);
        let m3 = b3.build();
        assert_eq!(m3.form_16bit, Some(X86Addr16Form::Disp16));
        assert!(m3.is_absolute_16);
    }

    #[test]
    fn test_builder_add_disp() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .with_disp(10)
            .add_disp(5)
            .build();
        assert_eq!(m.displacement, 15);
    }

    #[test]
    fn test_builder_add_disp_overflow() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .with_disp(i64::MAX)
            .add_disp(1)
            .build();
        // Wrapping overflow is expected
        assert_eq!(m.displacement, i64::MIN);
    }

    #[test]
    fn test_builder_fold_displacement_into_base() {
        let m = X86AddressingModeBuilder::new64()
            .with_disp(16)
            .fold_displacement_into_base(x86_register_info::RBX)
            .build();
        assert_eq!(m.base, Some(x86_register_info::RBX));
        assert_eq!(m.displacement, 16);
    }

    // ========================================================================
    // X86MemoryLowering tests — Load lowering
    // ========================================================================

    #[test]
    fn test_lower_simple_load_8() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_simple_load(&addr, 8);
        assert_eq!(result.size, 8);
        assert_eq!(result.address_mode.base, Some(x86_register_info::RAX));
    }

    #[test]
    fn test_lower_simple_load_4() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RBX);
        let result = lower.lower_simple_load(&addr, 4);
        assert_eq!(result.size, 4);
    }

    #[test]
    fn test_lower_load_signed_ext() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_load(&addr, 4, true, Some(8));
        // MOVSXD for 32-bit → 64-bit sign extension
        assert_eq!(result.opcode, X86Opcode::MOVSXD);
    }

    #[test]
    fn test_lower_load_zero_ext() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_load(&addr, 2, false, Some(4));
        // MOVZX for 16-bit → 32-bit zero extension
        assert_eq!(result.opcode, X86Opcode::MOVZX);
    }

    // ========================================================================
    // X86MemoryLowering tests — Store lowering
    // ========================================================================

    #[test]
    fn test_lower_store_int() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_store(&addr, 8, false);
        assert_eq!(result.size, 8);
        assert_eq!(result.address_mode.base, Some(x86_register_info::RAX));
    }

    #[test]
    fn test_lower_store_float() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_store(&addr, 4, true);
        assert_eq!(result.opcode, X86Opcode::MOVSS);
    }

    #[test]
    fn test_lower_store_double() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = lower.lower_store(&addr, 8, true);
        assert_eq!(result.opcode, X86Opcode::MOVSD);
    }

    // ========================================================================
    // X86MemoryLowering tests — Frame index lowering
    // ========================================================================

    #[test]
    fn test_lower_frame_index_with_fp() {
        let mut lower = X86MemoryLowering::new_x86_64_pic();
        lower.use_frame_pointer = true;
        let addr = lower.lower_frame_index(0, 8);
        assert_eq!(addr.base, Some(x86_register_info::RBP));
        assert!(addr.is_frame_relative);
    }

    #[test]
    fn test_lower_frame_index_without_fp() {
        let mut lower = X86MemoryLowering::new_x86_64_pic();
        lower.use_frame_pointer = false;
        let addr = lower.lower_frame_index(0, 8);
        assert_eq!(addr.base, Some(x86_register_info::RSP));
    }

    #[test]
    fn test_lower_frame_index_32bit() {
        let lower_32 = X86MemoryLowering::new_x86_32();
        let addr = lower_32.lower_frame_index(0, 4);
        // 32-bit mode uses EBP/ESP
        assert!(
            addr.base == Some(x86_register_info::EBP) || addr.base == Some(x86_register_info::ESP)
        );
    }

    // ========================================================================
    // X86MemoryLowering tests — Global address lowering
    // ========================================================================

    #[test]
    fn test_lower_global_address_64bit_pic() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = lower.lower_global_address("my_var", 0, false);
        assert!(addr.is_rip_relative || addr.is_got_relative);
        assert!(addr.symbol.is_some());
    }

    #[test]
    fn test_lower_global_address_64bit_non_pic() {
        let lower = X86MemoryLowering::new_x86_64_non_pic();
        let addr = lower.lower_global_address("my_var", 0, false);
        // Non-PIC small model: RIP-relative
        assert!(addr.is_rip_relative);
    }

    #[test]
    fn test_lower_global_address_32bit() {
        let lower = X86MemoryLowering::new_x86_32();
        let addr = lower.lower_global_address("my_var", 0, false);
        assert!(addr.is_absolute_32 || addr.is_got_relative);
    }

    #[test]
    fn test_lower_global_got() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = lower.lower_global_got("my_var");
        assert!(addr.is_rip_relative);
        assert!(addr.is_got_relative);
        assert!(addr.symbol.unwrap().contains("GOTPCREL"));
    }

    // ========================================================================
    // X86MemoryLowering tests — TLS address lowering
    // ========================================================================

    #[test]
    fn test_lower_tls_local_exec_64() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = lower.lower_tls_address("tls_var", 8, true);
        assert!(addr.segment == Some(x86_register_info::FS));
        assert_eq!(addr.displacement, 8);
    }

    #[test]
    fn test_lower_tls_local_exec_32() {
        let lower = X86MemoryLowering::new_x86_32();
        let addr = lower.lower_tls_address("tls_var", 4, true);
        // 32-bit Linux: GS segment
        assert!(addr.segment == Some(x86_register_info::GS));
    }

    #[test]
    fn test_lower_tls_initial_exec() {
        let mut engine = X86AddressingFull::new_x86_64();
        engine.tls_model = TlsModel::InitialExec;
        let lower = X86MemoryLowering::new(engine);
        let addr = lower.lower_tls_address("tls_var", 0, false);
        assert!(addr.is_got_relative);
        assert!(addr.symbol.is_some());
    }

    #[test]
    fn test_lower_tls_general_dynamic() {
        let mut engine = X86AddressingFull::new_x86_64();
        engine.tls_model = TlsModel::GeneralDynamic;
        let lower = X86MemoryLowering::new(engine);
        let addr = lower.lower_tls_address("tls_var", 0, false);
        assert!(addr.symbol.as_ref().map_or(false, |s| s.contains("TLSGD")));
        assert!(addr.is_rip_relative);
    }

    // ========================================================================
    // X86MemoryLowering tests — Constant pool lowering
    // ========================================================================

    #[test]
    fn test_lower_constant_pool_64() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = lower.lower_constant_pool(0, 0);
        assert!(addr.is_rip_relative);
        assert!(addr.symbol.unwrap().contains("LCPI"));
    }

    #[test]
    fn test_lower_constant_pool_32() {
        let lower = X86MemoryLowering::new_x86_32();
        let addr = lower.lower_constant_pool(0, 0);
        assert!(addr.is_absolute_32);
        assert!(addr.symbol.unwrap().contains("LCPI"));
    }

    #[test]
    fn test_lower_jump_table() {
        let lower = X86MemoryLowering::new_x86_64_pic();
        let addr = lower.lower_jump_table(0, 0);
        assert!(addr.symbol.unwrap().contains("LJTI"));
    }

    // ========================================================================
    // ConstantPool tests
    // ========================================================================

    #[test]
    fn test_constant_pool_empty() {
        let pool = ConstantPool::new();
        assert!(pool.is_empty());
        assert_eq!(pool.len(), 0);
    }

    #[test]
    fn test_constant_pool_add_entry() {
        let mut pool = ConstantPool::new();
        let idx = pool.add_entry(8, 4, false);
        assert_eq!(idx, 0);
        assert_eq!(pool.len(), 1);
        assert!(!pool.is_empty());
    }

    #[test]
    fn test_constant_pool_get_address() {
        let mut pool = ConstantPool::new();
        let idx = pool.add_entry(8, 8, true);
        let addr = pool.get_address(idx).unwrap();
        assert!(addr.is_rip_relative);
        assert!(addr.symbol.unwrap().contains("LCPI0"));
    }

    // ========================================================================
    // X86AddressOptimization tests — LEA formation
    // ========================================================================

    #[test]
    fn test_try_form_lea_add_reg() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let result = opt.try_form_lea(
            X86Opcode::ADD,
            x86_register_info::RAX,
            x86_register_info::RBX,
            None,
        );
        assert!(result.is_some());
        let addr = result.unwrap();
        assert_eq!(addr.base, Some(x86_register_info::RAX));
        assert_eq!(addr.index, Some(x86_register_info::RBX));
    }

    #[test]
    fn test_try_form_lea_add_imm() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let result = opt.try_form_lea(X86Opcode::ADD, x86_register_info::RAX, 0, Some(16));
        assert!(result.is_some());
        let addr = result.unwrap();
        assert_eq!(addr.base, Some(x86_register_info::RAX));
        assert_eq!(addr.displacement, 16);
    }

    #[test]
    fn test_try_form_lea_sub_imm() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let result = opt.try_form_lea(X86Opcode::SUB, x86_register_info::RAX, 0, Some(8));
        assert!(result.is_some());
        let addr = result.unwrap();
        assert_eq!(addr.displacement, -8);
    }

    #[test]
    fn test_try_form_lea_no_lea_for_mul() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let result = opt.try_form_lea(
            X86Opcode::MUL,
            x86_register_info::RAX,
            x86_register_info::RBX,
            None,
        );
        assert!(result.is_none());
    }

    #[test]
    fn test_should_use_lea() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, 16);
        // One add — don't use LEA for size optimization
        assert!(!opt.should_use_lea(&addr, 1));
        // Two adds — use LEA
        assert!(opt.should_use_lea(&addr, 2));
    }

    // ========================================================================
    // X86AddressOptimization tests — Address sinking
    // ========================================================================

    #[test]
    fn test_compute_sink_distance_simple() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let dist = opt.compute_sink_distance(&addr, 2);
        assert_eq!(dist, 4); // max for simple address
    }

    #[test]
    fn test_compute_sink_distance_complex() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 200);
        let dist = opt.compute_sink_distance(&addr, 2);
        assert_eq!(dist, 0); // Complex addresses shouldn't be sunk
    }

    #[test]
    fn test_can_sink_to() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(opt.can_sink_to(&addr, true));
        assert!(!opt.can_sink_to(&addr, false)); // Not in loop
    }

    // ========================================================================
    // X86AddressOptimization tests — Base/Index factoring
    // ========================================================================

    #[test]
    fn test_factor_common_base() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);

        let addrs = vec![
            X86AddressMode::base_disp64(x86_register_info::RBX, 0),
            X86AddressMode::base_disp64(x86_register_info::RBX, 4),
            X86AddressMode::base_disp64(x86_register_info::RBX, 8),
        ];
        let (common, _) = opt.factor_common_base(&addrs);
        assert_eq!(common, Some(x86_register_info::RBX));
    }

    #[test]
    fn test_factor_common_base_different() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);

        let addrs = vec![
            X86AddressMode::base_disp64(x86_register_info::RAX, 0),
            X86AddressMode::base_disp64(x86_register_info::RBX, 4),
            X86AddressMode::base_disp64(x86_register_info::RCX, 8),
        ];
        let (common, _) = opt.factor_common_base(&addrs);
        assert_eq!(common, None); // No common base
    }

    #[test]
    fn test_factor_common_index() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);

        let addrs = vec![
            X86AddressMode::full64(x86_register_info::RAX, x86_register_info::RSI, 4, 0),
            X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 4),
            X86AddressMode::full64(x86_register_info::RCX, x86_register_info::RSI, 4, 8),
        ];
        let (common, _) = opt.factor_common_index(&addrs);
        assert_eq!(common, Some((x86_register_info::RSI, 4)));
    }

    // ========================================================================
    // X86AddressOptimization tests — Loop invariant hoisting
    // ========================================================================

    #[test]
    fn test_is_loop_invariant_frame() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode {
            width: AddrWidth::Addr64,
            base: Some(x86_register_info::RBP),
            is_frame_relative: true,
            ..Default::default()
        };
        assert!(opt.is_loop_invariant(&addr));
    }

    #[test]
    fn test_is_loop_invariant_global() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::rip_relative(0).with_symbol("foo");
        assert!(opt.is_loop_invariant(&addr));
    }

    #[test]
    fn test_is_loop_invariant_rsp() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RSP);
        assert!(opt.is_loop_invariant(&addr));
    }

    #[test]
    fn test_is_not_loop_invariant_gpr() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(!opt.is_loop_invariant(&addr));
    }

    // ========================================================================
    // X86AddressOptimization tests — General optimization
    // ========================================================================

    #[test]
    fn test_optimize_zero_disp() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let optimized = opt.optimize(&addr);
        assert_eq!(optimized.displacement, 0);
    }

    #[test]
    fn test_select_best_smaller_encoding() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let a = X86AddressMode::base64(x86_register_info::RAX); // 1 byte
        let b = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0); // 2 bytes
        let best = opt.select_best(&a, &b);
        assert_eq!(best.classify(), AddressingForm::BaseOnly);
    }

    // ========================================================================
    // X86SegmentHandling tests
    // ========================================================================

    #[test]
    fn test_segment_default_for_base() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        assert_eq!(
            handler.default_segment_for_base(x86_register_info::RSP),
            x86_register_info::SS
        );
        assert_eq!(
            handler.default_segment_for_base(x86_register_info::RBP),
            x86_register_info::SS
        );
        assert_eq!(
            handler.default_segment_for_base(x86_register_info::RAX),
            x86_register_info::DS
        );
    }

    #[test]
    fn test_segment_override_prefix() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        let addr =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::FS);
        assert_eq!(handler.segment_override_prefix(&addr), Some(0x64));

        let addr_gs =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::GS);
        assert_eq!(handler.segment_override_prefix(&addr_gs), Some(0x65));
    }

    #[test]
    fn test_needs_segment_override() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        // DS is default for RAX, so no override needed
        let addr =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::DS);
        assert!(!handler.needs_segment_override(&addr));

        // FS override is needed
        let addr_fs =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::FS);
        assert!(handler.needs_segment_override(&addr_fs));
    }

    #[test]
    fn test_encode_decode_segment_prefix() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        let prefixes = [0x2E, 0x36, 0x3E, 0x26, 0x64, 0x65];
        for p in &prefixes {
            let seg = handler.decode_segment_prefix(*p);
            assert!(seg.is_some());
            let encoded = handler.encode_segment_prefix(seg.unwrap());
            assert_eq!(encoded, *p);
        }
    }

    #[test]
    fn test_tls_segment_reg() {
        let engine64 = X86AddressingFull::new_x86_64();
        let handler64 = X86SegmentHandling::new(engine64);
        assert_eq!(handler64.tls_segment_reg(), x86_register_info::FS);

        let engine32 = X86AddressingFull::new_x86_32();
        let handler32 = X86SegmentHandling::new(engine32);
        assert_eq!(handler32.tls_segment_reg(), x86_register_info::GS);
    }

    #[test]
    fn test_create_tls_address() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        let addr = handler.create_tls_address(16);
        assert_eq!(addr.segment, Some(x86_register_info::FS));
        assert_eq!(addr.displacement, 16);
    }

    #[test]
    fn test_is_stack_access() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        let stack_addr = X86AddressMode::base64(x86_register_info::RSP);
        assert!(handler.is_stack_access(&stack_addr));

        let data_addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(!handler.is_stack_access(&data_addr));
    }

    #[test]
    fn test_generate_prefixes() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);

        // Simple address: no prefixes needed
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let prefixes = handler.generate_prefixes(&addr);
        assert_eq!(prefixes, vec![0x48]); // REX.W for 64-bit

        // R8 requires REX.B + REX.W
        let addr_r8 = X86AddressMode::base64(x86_register_info::R8);
        let prefixes_r8 = handler.generate_prefixes(&addr_r8);
        assert!(prefixes_r8.contains(&0x49)); // 0x40 | REX.W | REX.B = 0x49
    }

    #[test]
    fn test_available_segments() {
        let engine64 = X86AddressingFull::new_x86_64();
        let handler64 = X86SegmentHandling::new(engine64);
        let segs64 = handler64.get_available_segments();
        assert_eq!(segs64.len(), 2); // FS, GS in 64-bit

        let engine32 = X86AddressingFull::new_x86_32();
        let handler32 = X86SegmentHandling::new(engine32);
        let segs32 = handler32.get_available_segments();
        assert_eq!(segs32.len(), 6); // CS, DS, SS, ES, FS, GS in 32-bit
    }

    // ========================================================================
    // AddressingModeMatcher tests
    // ========================================================================

    #[test]
    fn test_matcher_decode_64bit_rip_relative() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        // mod=00, r/m=5 → [RIP + disp32]
        let disp = vec![0x78, 0x56, 0x34, 0x12]; // 0x12345678
        let addr = matcher.decode(0x05, None, &disp, false, false, false);
        assert!(addr.is_rip_relative);
        assert_eq!(addr.displacement, 0x12345678);
    }

    #[test]
    fn test_matcher_decode_32bit_absolute() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr32);
        // mod=00, r/m=5 → [disp32]
        let disp = vec![0x00, 0x10, 0x00, 0x00]; // 0x1000
        let addr = matcher.decode(0x05, None, &disp, false, false, false);
        assert!(addr.is_absolute_32);
        assert_eq!(addr.displacement, 0x1000);
    }

    #[test]
    fn test_matcher_decode_sib() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        // mod=00, r/m=4 (SIB), SIB: scale=2, index=6 (RSI), base=3 (RBX)
        // [RBX + RSI*4]
        let sib: u8 = (2 << 6) | (6 << 3) | 3; // 0xB3
        let addr = matcher.decode(0x04, Some(sib), &[], false, false, false);
        assert_eq!(addr.base, Some(3)); // RBX
        assert_eq!(addr.index, Some(6)); // RSI
        assert_eq!(addr.scale, 4);
    }

    #[test]
    fn test_matcher_decode_sib_no_index() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        // [RSP]: SIB with index=4 (none), base=4 (RSP)
        let sib: u8 = (0 << 6) | (4 << 3) | 4; // 0x24
        let addr = matcher.decode(0x04, Some(sib), &[], false, false, false);
        assert_eq!(addr.base, Some(4)); // RSP
        assert_eq!(addr.index, None);
    }

    #[test]
    fn test_matcher_decode_16bit() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr16);
        // mod=01, r/m=7 → [BX+disp8]
        let addr = matcher.decode(0x47, None, &[0x10], false, false, false);
        assert_eq!(addr.form_16bit, Some(X86Addr16Form::BxDisp8));
        assert_eq!(addr.displacement, 16);
    }

    #[test]
    fn test_matcher_decode_16bit_disp16() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr16);
        // mod=00, r/m=6 → [disp16]
        let disp: Vec<u8> = vec![0x00, 0x20]; // 0x2000
        let addr = matcher.decode(0x06, None, &disp, false, false, false);
        assert!(addr.is_absolute_16);
        assert_eq!(addr.displacement, 0x2000);
    }

    // ========================================================================
    // ModR/M Combination Table tests
    // ========================================================================

    #[test]
    fn test_generate_all_modrm_combinations_64() {
        let entries = generate_all_modrm_combinations_32_64(AddrWidth::Addr64);
        // Should have many entries
        assert!(entries.len() > 50);

        // Check that RIP-relative is represented
        let rip_entries: Vec<_> = entries
            .iter()
            .filter(|e| e.form == ModRMForm::RIPRelative)
            .collect();
        assert!(!rip_entries.is_empty());
    }

    #[test]
    fn test_generate_all_modrm_combinations_32() {
        let entries = generate_all_modrm_combinations_32_64(AddrWidth::Addr32);
        assert!(entries.len() > 50);

        // In 32-bit mode, mod=00 r/m=5 is absolute, not RIP-relative
        let abs_entries: Vec<_> = entries
            .iter()
            .filter(|e| e.form == ModRMForm::Absolute && e.modrm == 0x05)
            .collect();
        assert!(!abs_entries.is_empty());
    }

    // ========================================================================
    // SIB Combination Table tests
    // ========================================================================

    #[test]
    fn test_generate_all_sib_combinations() {
        let entries = generate_all_sib_combinations();
        // 4 scales × 8 indices × 8 bases = 256 total
        assert_eq!(entries.len(), 256);

        // Check that all SIB bytes are unique
        let sibs: HashSet<u8> = entries.iter().map(|e| e.sib).collect();
        assert_eq!(sibs.len(), 256);
    }

    #[test]
    fn test_sib_entry_invalid() {
        let entries = generate_all_sib_combinations();
        // index=4, base=5 should be invalid for mod=00
        let invalid: Vec<_> = entries.iter().filter(|e| !e.is_valid).collect();
        assert!(!invalid.is_empty());
    }

    // ========================================================================
    // AddressModeSelector tests
    // ========================================================================

    #[test]
    fn test_selector_select_base_disp() {
        let engine = X86AddressingFull::new_x86_64();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_base_disp(x86_register_info::RAX, 42);
        assert_eq!(addr.base, Some(x86_register_info::RAX));
        assert_eq!(addr.displacement, 42);
    }

    #[test]
    fn test_selector_select_full() {
        let engine = X86AddressingFull::new_x86_64();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_full(x86_register_info::RBX, x86_register_info::RSI, 4, 16);
        assert_eq!(addr.base, Some(x86_register_info::RBX));
        assert_eq!(addr.index, Some(x86_register_info::RSI));
        assert_eq!(addr.scale, 4);
    }

    #[test]
    fn test_selector_select_rip_relative() {
        let engine = X86AddressingFull::new_x86_64();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_rip_relative(42);
        assert!(addr.is_rip_relative);
    }

    #[test]
    fn test_selector_select_absolute_64() {
        let engine = X86AddressingFull::new_x86_64();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_absolute(0x1000);
        // In 64-bit mode with RIP-relative allowed, should be RIP-relative
        assert!(addr.is_rip_relative);
    }

    #[test]
    fn test_selector_select_absolute_32() {
        let engine = X86AddressingFull::new_x86_32();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_absolute(0x1000);
        assert!(addr.is_absolute_32);
    }

    #[test]
    fn test_selector_select_16bit_base() {
        let engine = X86AddressingFull::new_x86_16();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_16bit(Some(x86_register_info::BX), None, 0);
        assert_eq!(addr.form_16bit, Some(X86Addr16Form::Bx));
    }

    #[test]
    fn test_selector_select_16bit_dual() {
        let engine = X86AddressingFull::new_x86_16();
        let selector = AddressModeSelector::new(engine);
        let addr =
            selector.select_16bit(Some(x86_register_info::BX), Some(x86_register_info::SI), 0);
        assert_eq!(addr.form_16bit, Some(X86Addr16Form::BxSi));
    }

    #[test]
    fn test_selector_select_16bit_with_disp() {
        let engine = X86AddressingFull::new_x86_16();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_16bit(Some(x86_register_info::BX), None, 42);
        assert_eq!(addr.form_16bit, Some(X86Addr16Form::BxDisp8));
    }

    #[test]
    fn test_selector_select_16bit_disp16_absolute() {
        let engine = X86AddressingFull::new_x86_16();
        let selector = AddressModeSelector::new(engine);
        let addr = selector.select_16bit(None, None, 0x500);
        assert_eq!(addr.form_16bit, Some(X86Addr16Form::Disp16));
        assert!(addr.is_absolute_16);
    }

    // ========================================================================
    // Utility function tests
    // ========================================================================

    #[test]
    fn test_is_valid_base_reg_64() {
        assert!(is_valid_base_reg(x86_register_info::RAX, AddrWidth::Addr64));
        assert!(is_valid_base_reg(x86_register_info::R8, AddrWidth::Addr64));
        assert!(is_valid_base_reg(x86_register_info::R15, AddrWidth::Addr64));
        assert!(!is_valid_base_reg(
            x86_register_info::XMM0,
            AddrWidth::Addr64
        ));
    }

    #[test]
    fn test_is_valid_base_reg_32() {
        assert!(is_valid_base_reg(x86_register_info::EAX, AddrWidth::Addr32));
        assert!(is_valid_base_reg(x86_register_info::R8D, AddrWidth::Addr32));
    }

    #[test]
    fn test_is_valid_base_reg_16() {
        assert!(is_valid_base_reg(x86_register_info::BX, AddrWidth::Addr16));
        assert!(is_valid_base_reg(x86_register_info::BP, AddrWidth::Addr16));
        assert!(is_valid_base_reg(x86_register_info::SI, AddrWidth::Addr16));
        assert!(is_valid_base_reg(x86_register_info::DI, AddrWidth::Addr16));
        assert!(!is_valid_base_reg(x86_register_info::AX, AddrWidth::Addr16));
    }

    #[test]
    fn test_is_valid_index_reg_64() {
        assert!(is_valid_index_reg(
            x86_register_info::RAX,
            AddrWidth::Addr64
        ));
        assert!(!is_valid_index_reg(
            x86_register_info::RSP,
            AddrWidth::Addr64
        ));
        assert!(is_valid_index_reg(x86_register_info::R8, AddrWidth::Addr64));
    }

    #[test]
    fn test_is_valid_index_reg_16() {
        assert!(is_valid_index_reg(x86_register_info::SI, AddrWidth::Addr16));
        assert!(is_valid_index_reg(x86_register_info::DI, AddrWidth::Addr16));
        assert!(!is_valid_index_reg(
            x86_register_info::BX,
            AddrWidth::Addr16
        ));
    }

    #[test]
    fn test_is_valid_scale() {
        assert!(is_valid_scale(1));
        assert!(is_valid_scale(2));
        assert!(is_valid_scale(4));
        assert!(is_valid_scale(8));
        assert!(!is_valid_scale(3));
        assert!(!is_valid_scale(0));
        assert!(!is_valid_scale(16));
    }

    #[test]
    fn test_compute_effective_address() {
        let result = compute_effective_address(Some(0x1000), Some(0x8), 4, 16);
        assert_eq!(result, 0x1000 + (0x8 * 4) + 16);

        let result_no_base = compute_effective_address(None, Some(0x10), 8, 0x100);
        assert_eq!(result_no_base, 0 + (0x10 * 8) + 0x100);

        let result_simple = compute_effective_address(Some(0x1000), None, 0, 0);
        assert_eq!(result_simple, 0x1000);
    }

    #[test]
    fn test_are_addresses_equal() {
        let a = X86AddressMode::base_disp64(x86_register_info::RAX, 16);
        let b = X86AddressMode::base_disp64(x86_register_info::RAX, 16);
        assert!(are_addresses_equal(&a, &b));

        let c = X86AddressMode::base_disp64(x86_register_info::RAX, 32);
        assert!(!are_addresses_equal(&a, &c));
    }

    #[test]
    fn test_address_difference() {
        let a = X86AddressMode::base_disp64(x86_register_info::RAX, 0);
        let b = X86AddressMode::base_disp64(x86_register_info::RAX, 16);
        assert_eq!(address_difference(&a, &b), Some(16));

        let c = X86AddressMode::base_disp64(x86_register_info::RBX, 16);
        assert_eq!(address_difference(&a, &c), None); // Different base
    }

    #[test]
    fn test_merge_addresses() {
        let a = X86AddressMode::base_disp64(x86_register_info::RBX, 8);
        let b = X86AddressMode::base_disp64(x86_register_info::RBX, 16);
        let result = merge_addresses(&a, &b);
        assert!(result.is_some());
        let (common, off_a, off_b) = result.unwrap();
        assert_eq!(common.displacement, 8);
        assert_eq!(off_a, 0);
        assert_eq!(off_b, 8);
    }

    #[test]
    fn test_merge_addresses_different_base() {
        let a = X86AddressMode::base_disp64(x86_register_info::RAX, 8);
        let b = X86AddressMode::base_disp64(x86_register_info::RBX, 16);
        let result = merge_addresses(&a, &b);
        assert!(result.is_none());
    }

    // ========================================================================
    // Encoding utilities tests
    // ========================================================================

    #[test]
    fn test_encode_addressing_mode_simple() {
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let bytes = encode_addressing_mode(&addr, 0);
        // [REX.W=0x48] [ModR/M=0x00]
        assert!(bytes.contains(&0x00)); // ModR/M
    }

    #[test]
    fn test_encode_addressing_mode_with_sib() {
        let addr = X86AddressMode::base64(x86_register_info::RSP);
        let bytes = encode_addressing_mode(&addr, 0);
        // [REX.W=0x48] [ModR/M with r/m=4] [SIB=0x24]
        assert!(bytes.len() >= 3);
    }

    #[test]
    fn test_decode_addressing_mode_roundtrip() {
        let original = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        let encoded = encode_addressing_mode(&original, 0);
        let (decoded, consumed) =
            decode_addressing_mode(&encoded, 1, AddrWidth::Addr64, true, false, false).unwrap();
        assert!(consumed > 0);
        assert_eq!(decoded.base, original.base);
        assert_eq!(decoded.displacement, original.displacement);
    }

    #[test]
    fn test_encode_16bit_modrm() {
        let modrm = encode_16bit_modrm(X86Addr16Form::BxSi, 0);
        assert_eq!(modrm, (Mod00 << 6) | 0);

        let modrm2 = encode_16bit_modrm(X86Addr16Form::BxDisp8, 1);
        assert_eq!(modrm2, (Mod01 << 6) | (1 << 3) | 7);
    }

    // ========================================================================
    // Format tests
    // ========================================================================

    #[test]
    fn test_format_intel_simple() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        let reg_info = make_reg_info();
        let s = format_intel(&m, &reg_info);
        assert!(s.contains("["));
        assert!(s.contains("]"));
        assert!(s.contains("rax") || s.contains("RAX"));
    }

    #[test]
    fn test_format_intel_full() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        let reg_info = make_reg_info();
        let s = format_intel(&m, &reg_info);
        assert!(s.contains("rbx") || s.contains("RBX"));
        assert!(s.contains("rsi") || s.contains("RSI"));
        assert!(s.contains("4"));
        assert!(s.contains("8"));
    }

    #[test]
    fn test_format_intel_rip_relative() {
        let m = X86AddressMode::rip_relative(42);
        let reg_info = make_reg_info();
        let s = format_intel(&m, &reg_info);
        assert!(s.contains("rip") || s.contains("RIP"));
    }

    #[test]
    fn test_format_att_simple() {
        let m = X86AddressMode::base64(x86_register_info::RAX);
        let reg_info = make_reg_info();
        let s = format_att(&m, &reg_info);
        assert!(s.contains("("));
        assert!(s.contains(")"));
        assert!(s.contains("rax") || s.contains("RAX"));
    }

    #[test]
    fn test_format_att_with_index() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        let reg_info = make_reg_info();
        let s = format_att(&m, &reg_info);
        assert!(s.contains("8"));
        assert!(s.contains("rbx") || s.contains("RBX"));
        assert!(s.contains("rsi") || s.contains("RSI"));
        assert!(s.contains("4"));
    }

    // ========================================================================
    // Edge case tests
    // ========================================================================

    #[test]
    fn test_rsp_sib_encoding() {
        // [RSP] must use SIB with index=4 (none), base=4 (RSP)
        let m = X86AddressMode::base64(x86_register_info::RSP);
        assert!(m.requires_sib());
        let sib = m.encode_sib();
        assert_eq!(sib, 0x24);
    }

    #[test]
    fn test_rbp_64bit_sib_encoding() {
        // [RBP] in 64-bit mode must use SIB because mod=00, r/m=5 is RIP-relative
        let m = X86AddressMode::base64(x86_register_info::RBP);
        assert!(m.requires_sib());
        let sib = m.encode_sib();
        assert_eq!(sib & 0x7, 5); // base = RBP
        assert_eq!((sib >> 3) & 0x7, 4); // index = none
    }

    #[test]
    fn test_r12_sib_encoding() {
        // [R12] must use SIB with index=4 (none), base=4 (5-bit encoding for R12)
        let m = X86AddressMode::base64(x86_register_info::R12);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_r13_64bit_sib_encoding() {
        // [R13] in 64-bit mode must use SIB
        let m = X86AddressMode::base64(x86_register_info::R13);
        assert!(m.requires_sib());
    }

    #[test]
    fn test_rip_relative_no_sib() {
        let m = X86AddressMode::rip_relative(42);
        assert!(!m.requires_sib());
        assert_eq!(m.encode_modrm(0), 0x05);
    }

    #[test]
    fn test_absolute_32_no_sib() {
        let m = X86AddressMode::absolute32(0x1000);
        assert!(!m.requires_sib());
    }

    #[test]
    fn test_zero_disp_folded() {
        let builder = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RAX)
            .with_disp(0);
        let m = builder.build();
        assert_eq!(m.displacement, 0);
        assert_eq!(m.classify(), AddressingForm::BaseOnly);
    }

    #[test]
    fn test_disp8_promoted_to_disp32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert_eq!(m.classify(), AddressingForm::BaseDisp32);
    }

    #[test]
    fn test_displacement_negative() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, -16);
        assert!(m.fits_disp8());
        assert_eq!(m.displacement_size(), 1);
    }

    #[test]
    fn test_displacement_negative_32() {
        let m = X86AddressMode::base_disp64(x86_register_info::RAX, -200);
        assert!(!m.fits_disp8());
        assert_eq!(m.displacement_size(), 4);
    }

    #[test]
    fn test_address_mode_clone() {
        let m = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 8);
        let cloned = m.clone();
        assert_eq!(m.base, cloned.base);
        assert_eq!(m.index, cloned.index);
        assert_eq!(m.scale, cloned.scale);
        assert_eq!(m.displacement, cloned.displacement);
    }

    #[test]
    fn test_address_mode_default() {
        let m = X86AddressMode::default();
        assert_eq!(m.width, AddrWidth::Addr64);
        assert_eq!(m.base, None);
        assert_eq!(m.index, None);
        assert_eq!(m.scale, 0);
        assert_eq!(m.displacement, 0);
        assert!(!m.is_rip_relative);
    }

    #[test]
    fn test_hash_key_unique() {
        let a = X86AddressMode::base64(x86_register_info::RAX);
        let b = X86AddressMode::base64(x86_register_info::RBX);
        assert_ne!(a.hash_key(), b.hash_key());

        let c = X86AddressMode::base_disp64(x86_register_info::RAX, 0);
        let d = X86AddressMode::base_disp64(x86_register_info::RAX, 16);
        assert_ne!(c.hash_key(), d.hash_key());
    }

    #[test]
    fn test_code_model_default() {
        assert_eq!(CodeModel::default(), CodeModel::Small);
    }

    #[test]
    fn test_tls_model_default() {
        assert_eq!(TlsModel::default(), TlsModel::InitialExec);
    }

    // ========================================================================
    // Stress / combinatorial tests
    // ========================================================================

    #[test]
    fn test_all_sib_combinations_are_unique() {
        let entries = generate_all_sib_combinations();
        let mut seen = HashSet::new();
        for e in &entries {
            assert!(seen.insert(e.sib), "Duplicate SIB: {:02X}", e.sib);
        }
    }

    #[test]
    fn test_all_16bit_forms_decode_roundtrip() {
        let forms = [
            X86Addr16Form::BxSi,
            X86Addr16Form::BxDi,
            X86Addr16Form::BpSi,
            X86Addr16Form::BpDi,
            X86Addr16Form::Si,
            X86Addr16Form::Di,
            X86Addr16Form::Bp,
            X86Addr16Form::Bx,
        ];
        for &form in &forms {
            let modrm = (form.mod_field() << 6) | (form.rm_field());
            let decoded = X86Addr16Form::decode(modrm);
            assert_eq!(
                decoded, form,
                "Form {:?} mismatch: encoded {:02X} → decoded {:?}",
                form, modrm, decoded
            );
        }
    }

    #[test]
    fn test_all_64bit_base_registers_work() {
        let regs: Vec<u16> = vec![
            x86_register_info::RAX,
            x86_register_info::RCX,
            x86_register_info::RDX,
            x86_register_info::RBX,
            x86_register_info::RSP,
            x86_register_info::RBP,
            x86_register_info::RSI,
            x86_register_info::RDI,
            x86_register_info::R8,
            x86_register_info::R9,
            x86_register_info::R10,
            x86_register_info::R11,
            x86_register_info::R12,
            x86_register_info::R13,
            x86_register_info::R14,
            x86_register_info::R15,
        ];

        for reg in &regs {
            let m = X86AddressMode::base64(*reg);
            // Each should encode without panicking
            let modrm = m.encode_modrm(0);
            // Verify the modrm byte is valid
            assert!(
                modrm < 0xC0,
                "Invalid ModR/M for register {}: {:02X}",
                reg,
                modrm
            );
        }
    }

    #[test]
    fn test_all_scale_factors_work() {
        let scales = [1, 2, 4, 8];
        for &scale in &scales {
            let m =
                X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, scale, 0);
            let sib = m.encode_sib();
            let decoded_scale = match (sib >> 6) & 0x3 {
                0 => 1,
                1 => 2,
                2 => 4,
                3 => 8,
                _ => 0,
            };
            assert_eq!(
                decoded_scale, scale,
                "Scale {} encoded incorrectly in SIB {:02X}",
                scale, sib
            );
        }
    }

    #[test]
    fn test_displacement_range_8bit() {
        for disp in -128i64..=127i64 {
            let m = X86AddressMode::base_disp64(x86_register_info::RAX, disp);
            assert!(m.fits_disp8());
            assert_eq!(
                m.displacement_size(),
                if disp == 0 && m.requires_sib() {
                    0
                } else if disp != 0 {
                    1
                } else {
                    0
                }
            );
        }
    }

    #[test]
    fn test_tls_all_models() {
        let models = [
            TlsModel::GeneralDynamic,
            TlsModel::LocalDynamic,
            TlsModel::InitialExec,
            TlsModel::LocalExec,
        ];

        for &model in &models {
            let mut engine = X86AddressingFull::new_x86_64();
            engine.tls_model = model;
            let lower = X86MemoryLowering::new(engine);
            let addr = lower.lower_tls_address("tls_var", 0, true);
            // Each model should produce a valid address mode
            assert!(addr.width == AddrWidth::Addr64);
        }
    }

    #[test]
    fn test_code_model_all() {
        let models = [
            CodeModel::Small,
            CodeModel::Kernel,
            CodeModel::Medium,
            CodeModel::Large,
        ];

        for &model in &models {
            let engine = X86AddressingFull::new_x86_64().with_code_model(model);
            assert_eq!(engine.code_model, model);
        }
    }

    #[test]
    fn test_opt_level_all() {
        let levels = [OptLevel::None, OptLevel::Default, OptLevel::Aggressive];
        for &level in &levels {
            let engine = X86AddressingFull::new_x86_64().with_opt_level(level);
            assert_eq!(engine.opt_level, level);
        }
    }

    // ========================================================================
    // Round-trip tests: encode → decode
    // ========================================================================

    #[test]
    fn test_roundtrip_base_only() {
        for reg in &[
            x86_register_info::RAX,
            x86_register_info::RCX,
            x86_register_info::RDX,
            x86_register_info::RBX,
            x86_register_info::RSI,
            x86_register_info::RDI,
        ] {
            let original = X86AddressMode::base64(*reg);
            let modrm = original.encode_modrm(0);
            let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
            let decoded = matcher.decode(modrm, None, &[], false, false, false);
            assert_eq!(
                decoded.base, original.base,
                "Round-trip failed for register {}",
                reg
            );
            assert_eq!(decoded.displacement, original.displacement);
        }
    }

    #[test]
    fn test_roundtrip_rip_relative() {
        let disp: i64 = 0x12345678;
        let original = X86AddressMode::rip_relative(disp);
        let modrm = original.encode_modrm(0);
        let disp_bytes = original.encode_displacement();
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        let decoded = matcher.decode(modrm, None, &disp_bytes, false, false, false);
        assert!(decoded.is_rip_relative);
        assert_eq!(decoded.displacement, disp);
    }

    #[test]
    fn test_roundtrip_sib_index() {
        let original = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let modrm = original.encode_modrm(0);
        let sib = Some(original.encode_sib());
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        let decoded = matcher.decode(modrm, sib, &[], false, false, false);
        assert_eq!(decoded.base, original.base);
        assert_eq!(decoded.index, original.index);
        assert_eq!(decoded.scale, original.scale);
    }

    // ========================================================================
    // Bulk combinatorial tests
    // ========================================================================

    #[test]
    fn test_bulk_sib_all_scale_index_base_combos() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        for scale in [0u8, 1, 2, 3] {
            for index in 0..8u8 {
                for base in 0..8u8 {
                    if index == 4 && base == 5 {
                        // Special: mod=00, base=5, index=4 → disp32 form
                        continue;
                    }
                    let sib = (scale << 6) | ((index & 0x7) << 3) | (base & 0x7);
                    if index == 4 && base == 5 {
                        continue; // Same special case
                    }

                    // Decode the SIB
                    let addr = matcher.decode(
                        (Mod00 << 6) | 4, // mod=00, r/m=4
                        Some(sib),
                        &[],
                        false,
                        false,
                        false,
                    );

                    // Verify base
                    if base == 5 {
                        // mod=00, base=5 → no base (disp32 form)
                        assert_eq!(addr.base, None);
                    } else {
                        assert_eq!(addr.base, Some(base as u16));
                    }

                    // Verify index
                    if index == 4 {
                        assert_eq!(addr.index, None);
                    } else {
                        assert_eq!(addr.index, Some(index as u16));
                    }

                    // Verify scale
                    let expected_scale: u8 = match scale {
                        0 => 1,
                        1 => 2,
                        2 => 4,
                        3 => 8,
                        _ => 1,
                    };
                    assert_eq!(addr.scale, expected_scale);
                }
            }
        }
    }

    #[test]
    fn test_bulk_16bit_all_modrm_forms() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr16);
        for mod_field in 0u8..3 {
            for rm in 0u8..8 {
                let modrm = (mod_field << 6) | rm;
                let form = X86Addr16Form::decode(modrm);

                // Encode a synthetic displacement
                let disp: Vec<u8> = match form.disp_size() {
                    0 => vec![],
                    1 => vec![0x10],
                    2 => vec![0x00, 0x20],
                    _ => vec![],
                };

                let addr = matcher.decode(modrm, None, &disp, false, false, false);

                // Verify the decoded form
                if form.disp_size() == 0 {
                    assert!(addr.form_16bit.is_some());
                    assert_eq!(addr.form_16bit, Some(form));
                }
            }
        }
    }

    // ========================================================================
    // AddressCostModel tests
    // ========================================================================

    #[test]
    fn test_cost_model_default() {
        let model = AddressCostModel::default();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let cost = model.compute_cost(&addr);
        assert!(cost > 0);
    }

    #[test]
    fn test_cost_model_simple_vs_complex() {
        let model = AddressCostModel::default();
        let simple = X86AddressMode::base64(x86_register_info::RAX);
        let complex =
            X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 200);
        let cost_simple = model.compute_cost(&simple);
        let cost_complex = model.compute_cost(&complex);
        assert!(cost_simple < cost_complex);
    }

    #[test]
    fn test_cost_model_size_optimized() {
        let model = AddressCostModel::size_optimized();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let cost = model.compute_cost(&addr);
        assert!(cost > 0);
    }

    #[test]
    fn test_cost_model_select_cheaper() {
        let model = AddressCostModel::default();
        let simple = X86AddressMode::base64(x86_register_info::RAX);
        let complex =
            X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 200);
        let selected = model.select_cheaper(&simple, &complex);
        assert_eq!(selected.base, simple.base);
    }

    #[test]
    fn test_cost_model_skylake() {
        let model = AddressCostModel::skylake();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let cost = model.compute_cost(&addr);
        assert!(cost > 0);
    }

    #[test]
    fn test_cost_model_zen() {
        let model = AddressCostModel::zen();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let cost = model.compute_cost(&addr);
        assert!(cost > 0);
    }

    // ========================================================================
    // RegisterPressureAnalysis tests
    // ========================================================================

    #[test]
    fn test_pressure_analysis_default() {
        let pa = RegisterPressureAnalysis::default();
        assert!(pa.can_use_index());
    }

    #[test]
    fn test_pressure_analysis_high_pressure() {
        let mut pa = RegisterPressureAnalysis::default();
        pa.current_pressure = 0.9;
        assert!(!pa.can_use_index());
    }

    #[test]
    fn test_pressure_should_use_lea() {
        let pa = RegisterPressureAnalysis::default();
        assert!(pa.should_use_lea(2));
        assert!(!pa.should_use_lea(1));

        let mut pa2 = RegisterPressureAnalysis::default();
        pa2.current_pressure = 0.95;
        assert!(!pa2.should_use_lea(2));
    }

    #[test]
    fn test_pressure_estimate() {
        let pa = RegisterPressureAnalysis::new64();
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let (pressure, change) = pa.estimate_pressure(&addr, 5);
        assert!(change > 0.0);
        assert!(pressure > 0.0);
    }

    #[test]
    fn test_pressure_register_friendliness() {
        let pa = RegisterPressureAnalysis::default();
        let simple = X86AddressMode::base64(x86_register_info::RAX);
        let complex = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let rip = X86AddressMode::rip_relative(0);

        assert!(pa.register_friendliness(&simple) > pa.register_friendliness(&complex));
        assert!(pa.register_friendliness(&rip) > pa.register_friendliness(&simple));
    }

    // ========================================================================
    // MemoryFoldRules tests
    // ========================================================================

    #[test]
    fn test_fold_rules_default_load() {
        let rules = MemoryFoldRules::default();
        assert!(rules.can_fold_load_into(X86Opcode::ADD));
        assert!(rules.can_fold_load_into(X86Opcode::CMP));
        assert!(!rules.can_fold_load_into(X86Opcode::JMP));
    }

    #[test]
    fn test_fold_rules_default_rmw() {
        let rules = MemoryFoldRules::default();
        assert!(rules.can_fold_rmw_into(X86Opcode::ADD));
        assert!(rules.can_fold_rmw_into(X86Opcode::INC));
        assert!(!rules.can_fold_rmw_into(X86Opcode::JMP));
    }

    #[test]
    fn test_fold_rules_is_foldable() {
        let rules = MemoryFoldRules::default();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(rules.is_foldable(&addr));

        let rip = X86AddressMode::rip_relative(0);
        assert!(rules.is_foldable(&rip));

        let complex = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert!(rules.is_foldable(&complex));
    }

    #[test]
    fn test_fold_rules_get_fold_form() {
        let rules = MemoryFoldRules::default();
        let base = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(rules.get_fold_form(&base), FoldForm::BaseOnly);

        let disp8 = X86AddressMode::base_disp64(x86_register_info::RAX, 42);
        assert_eq!(rules.get_fold_form(&disp8), FoldForm::BaseDisp8);

        let disp32 = X86AddressMode::base_disp64(x86_register_info::RAX, 200);
        assert_eq!(rules.get_fold_form(&disp32), FoldForm::BaseDisp32);

        let index = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert_eq!(rules.get_fold_form(&index), FoldForm::FullWithIndex);
    }

    // ========================================================================
    // LeaComplexityDB tests
    // ========================================================================

    #[test]
    fn test_lea_complexity_class_1() {
        let db = LeaComplexityDB::intel_skylake_client();
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(db.classify_lea(&addr), 1);
        assert_eq!(db.lea_latency(&addr), 1);
    }

    #[test]
    fn test_lea_complexity_class_2() {
        let db = LeaComplexityDB::intel_skylake_client();
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 1, 0);
        assert_eq!(db.classify_lea(&addr), 2);
        assert_eq!(db.lea_latency(&addr), 1);
    }

    #[test]
    fn test_lea_complexity_class_3() {
        let db = LeaComplexityDB::intel_skylake_client();
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert_eq!(db.classify_lea(&addr), 3);
        assert_eq!(db.lea_latency(&addr), 1);
    }

    #[test]
    fn test_lea_complexity_class_4() {
        let db = LeaComplexityDB::intel_skylake_client();
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 16);
        assert_eq!(db.classify_lea(&addr), 4);
        assert_eq!(db.lea_latency(&addr), 3);
    }

    #[test]
    fn test_lea_complexity_zen_class_4_fast() {
        let db = LeaComplexityDB::amd_zen();
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 16);
        assert_eq!(db.classify_lea(&addr), 4);
        assert_eq!(db.lea_latency(&addr), 1);
    }

    // ========================================================================
    // AddressSelectionDecisionTree tests
    // ========================================================================

    #[test]
    fn test_decision_tree_select_frame() {
        let engine = X86AddressingFull::new_x86_64();
        let tree = AddressSelectionDecisionTree::new(engine);
        let addr = tree.select_best_memory(
            None, None, 0, 8, true,  // frame index
            false, // not global
            false, // not TLS
        );
        assert!(addr.is_frame_relative);
        assert_eq!(addr.base, Some(x86_register_info::RBP));
    }

    #[test]
    fn test_decision_tree_select_global() {
        let engine = X86AddressingFull::new_x86_64().with_pic(true);
        let tree = AddressSelectionDecisionTree::new(engine);
        let addr = tree.select_best_memory(
            None, None, 0, 0, false, true, // global
            false,
        );
        assert!(addr.is_rip_relative);
        assert!(addr.is_got_relative);
    }

    #[test]
    fn test_decision_tree_select_tls() {
        let engine = X86AddressingFull::new_x86_64();
        let tree = AddressSelectionDecisionTree::new(engine);
        let addr = tree.select_best_memory(
            None, None, 0, 8, false, false, true, // TLS
        );
        assert_eq!(addr.segment, Some(x86_register_info::FS));
    }

    #[test]
    fn test_decision_tree_select_generic() {
        let engine = X86AddressingFull::new_x86_64();
        let tree = AddressSelectionDecisionTree::new(engine);
        let addr = tree.select_best_memory(
            Some(x86_register_info::RAX),
            Some(x86_register_info::RSI),
            4,
            16,
            false,
            false,
            false,
        );
        assert_eq!(addr.base, Some(x86_register_info::RAX));
        assert_eq!(addr.index, Some(x86_register_info::RSI));
        assert_eq!(addr.scale, 4);
    }

    // ========================================================================
    // PrefixInteraction tests
    // ========================================================================

    #[test]
    fn test_prefix_encode_rex_all_bits() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        assert_eq!(pi.encode_rex(false, false, false, false), 0x40);
        assert_eq!(pi.encode_rex(true, false, false, false), 0x48);
        assert_eq!(pi.encode_rex(true, true, true, true), 0x4F);
    }

    #[test]
    fn test_prefix_decode_rex() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let (w, r, x, b) = pi.decode_rex(0x4F);
        assert!(w);
        assert!(r);
        assert!(x);
        assert!(b);
    }

    #[test]
    fn test_prefix_needs_rex_r8() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr = X86AddressMode::base64(x86_register_info::R8);
        assert!(pi.needs_rex(&addr));
    }

    #[test]
    fn test_prefix_needs_rex_low_reg() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(pi.needs_rex(&addr));
    }

    #[test]
    fn test_prefix_compute_rex_bits() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr = X86AddressMode::full64(x86_register_info::R8, x86_register_info::R9, 1, 0);
        let (r, x, b) = pi.compute_rex_bits(&addr);
        assert!(!r);
        assert!(x);
        assert!(b);
    }

    #[test]
    fn test_prefix_needs_addr_size_override() {
        let pi64 = PrefixInteraction::new(AddrWidth::Addr64);
        let addr32 = X86AddressMode::base32(x86_register_info::EAX);
        assert!(pi64.needs_addr_size_override(&addr32));

        let pi32 = PrefixInteraction::new(AddrWidth::Addr32);
        let addr16 = X86AddressMode::base16(x86_register_info::BX);
        assert!(pi32.needs_addr_size_override(&addr16));
    }

    #[test]
    fn test_prefix_encode_all() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let prefixes = pi.encode_all_prefixes(&addr, 0);
        assert!(!prefixes.is_empty());
        assert!(prefixes.contains(&0x48));
    }

    // ========================================================================
    // AddressingModeValidator tests
    // ========================================================================

    #[test]
    fn test_validator_valid_simple() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(v.is_valid(&addr).is_ok());
    }

    #[test]
    fn test_validator_valid_complex() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 16);
        assert!(v.is_valid(&addr).is_ok());
    }

    #[test]
    fn test_validator_valid_rip() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let addr = X86AddressMode::rip_relative(42);
        assert!(v.is_valid(&addr).is_ok());
    }

    #[test]
    fn test_validator_invalid_scale() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 3, 0);
        let result = v.is_valid(&addr);
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), AddressingError::InvalidScale(3));
    }

    #[test]
    fn test_validator_rip_with_base() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let mut addr = X86AddressMode::rip_relative(42);
        addr.base = Some(x86_register_info::RAX);
        let result = v.is_valid(&addr);
        assert!(result.is_err());
    }

    #[test]
    fn test_validator_rsp_as_index() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSP, 1, 0);
        let result = v.is_valid(&addr);
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), AddressingError::RspCannotBeIndex);
    }

    #[test]
    fn test_validator_16bit_valid() {
        let v = AddressingModeValidator::new(AddrWidth::Addr16);
        let addr = X86AddressMode::base_index16(x86_register_info::BX, x86_register_info::SI);
        assert!(v.is_valid(&addr).is_ok());
    }

    #[test]
    fn test_validator_16bit_invalid_pair() {
        let v = AddressingModeValidator::new(AddrWidth::Addr16);
        let addr = X86AddressMode::base_index16(x86_register_info::AX, x86_register_info::CX);
        let result = v.is_valid(&addr);
        assert!(result.is_err());
    }

    #[test]
    fn test_validator_16bit_no_scale() {
        let v = AddressingModeValidator::new(AddrWidth::Addr16);
        let addr = X86AddressMode {
            width: AddrWidth::Addr16,
            base: Some(x86_register_info::BX),
            scale: 4,
            ..Default::default()
        };
        let result = v.is_valid(&addr);
        assert!(result.is_err());
    }

    #[test]
    fn test_validator_width_mismatch() {
        let v = AddressingModeValidator::new(AddrWidth::Addr32);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        let result = v.is_valid(&addr);
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), AddressingError::WidthMismatch);
    }

    #[test]
    fn test_validator_suggest_fix() {
        let v = AddressingModeValidator::new(AddrWidth::Addr64);
        let suggestion = v.suggest_fix(&AddressingError::InvalidScale(3));
        assert!(suggestion.is_some());
        assert!(suggestion.unwrap().contains("4"));

        let suggestion2 = v.suggest_fix(&AddressingError::RspCannotBeIndex);
        assert!(suggestion2.is_some());
        assert!(suggestion2.unwrap().contains("RSP"));
    }

    #[test]
    fn test_addressing_error_display() {
        let err = AddressingError::InvalidScale(0);
        let s = format!("{}", err);
        assert!(s.contains("0"));

        let err2 = AddressingError::RipRelativeNotSupported;
        let s2 = format!("{}", err2);
        assert!(s2.contains("64-bit"));
    }

    // ========================================================================
    // CompleteModRMTable tests
    // ========================================================================

    #[test]
    fn test_complete_table_64bit() {
        let table = CompleteModRMTable::generate_64bit();
        assert!(table.total_entries() > 1000);
    }

    #[test]
    fn test_complete_table_32bit() {
        let table = CompleteModRMTable::generate_32bit();
        assert!(table.total_entries() > 1000);
    }

    #[test]
    fn test_complete_table_lookup() {
        let table = CompleteModRMTable::generate_64bit();
        let entry = table.lookup_modrm(0x00);
        assert!(entry.is_some());
        let e = entry.unwrap();
        assert_eq!(e.form, ModRMForm::BaseOnly);
        assert_eq!(e.base, Some(0));
    }

    #[test]
    fn test_complete_table_lookup_rip_relative() {
        let table = CompleteModRMTable::generate_64bit();
        let entry = table.lookup_modrm(0x05);
        assert!(entry.is_some());
        let e = entry.unwrap();
        assert_eq!(e.form, ModRMForm::RIPRelative);
    }

    #[test]
    fn test_complete_table_entries_by_form() {
        let table = CompleteModRMTable::generate_64bit();
        let entries = table.entries_by_form(ModRMForm::BaseOnly);
        assert!(!entries.is_empty());
    }

    // ========================================================================
    // Bulk 64-bit addressing tests
    // ========================================================================

    #[test]
    fn test_bulk_all_64bit_base_registers_with_disp8() {
        let regs = [
            x86_register_info::RAX,
            x86_register_info::RCX,
            x86_register_info::RDX,
            x86_register_info::RBX,
            x86_register_info::RSI,
            x86_register_info::RDI,
            x86_register_info::R8,
            x86_register_info::R9,
            x86_register_info::R10,
            x86_register_info::R11,
            x86_register_info::R14,
            x86_register_info::R15,
        ];

        for &reg in &regs {
            let addr = X86AddressMode::base_disp64(reg, 42);
            let modrm = addr.encode_modrm(0);
            let mod_field = (modrm >> 6) & 0x3;
            assert_eq!(mod_field, 1, "Expected mod=01 for disp8, reg={}", reg);

            let rm = modrm & 0x7;
            assert_eq!(rm, reg & 0x7, "rm field mismatch for reg={}", reg);
        }
    }

    #[test]
    fn test_bulk_all_64bit_base_registers_with_disp32() {
        let regs = [
            x86_register_info::RAX,
            x86_register_info::RCX,
            x86_register_info::RDX,
            x86_register_info::RBX,
            x86_register_info::RSI,
            x86_register_info::RDI,
            x86_register_info::R8,
            x86_register_info::R9,
            x86_register_info::R10,
            x86_register_info::R11,
            x86_register_info::R14,
            x86_register_info::R15,
        ];

        for &reg in &regs {
            let addr = X86AddressMode::base_disp64(reg, 200);
            let modrm = addr.encode_modrm(0);
            let mod_field = (modrm >> 6) & 0x3;
            assert_eq!(mod_field, 2, "Expected mod=10 for disp32, reg={}", reg);
        }
    }

    #[test]
    fn test_bulk_all_index_registers_with_scales() {
        let indices = [
            x86_register_info::RAX,
            x86_register_info::RCX,
            x86_register_info::RDX,
            x86_register_info::RBX,
            x86_register_info::RBP,
            x86_register_info::RSI,
            x86_register_info::RDI,
            x86_register_info::R8,
            x86_register_info::R9,
            x86_register_info::R10,
            x86_register_info::R11,
            x86_register_info::R12,
            x86_register_info::R13,
            x86_register_info::R14,
            x86_register_info::R15,
        ];

        let scales = [1u8, 2, 4, 8];

        for &idx in &indices {
            for &sc in &scales {
                let addr = X86AddressMode::full64(x86_register_info::RBX, idx, sc, 0);
                assert!(addr.requires_sib());
                let sib = addr.encode_sib();
                let sib_index = (sib >> 3) & 0x7;
                assert_eq!(
                    sib_index,
                    idx & 0x7,
                    "Index mismatch for idx={}, scale={}",
                    idx,
                    sc
                );
                let sib_scale = (sib >> 6) & 0x3;
                let decoded_scale: u8 = match sib_scale {
                    0 => 1,
                    1 => 2,
                    2 => 4,
                    3 => 8,
                    _ => 0,
                };
                assert_eq!(
                    decoded_scale, sc,
                    "Scale mismatch for idx={}, scale={}",
                    idx, sc
                );
            }
        }
    }

    // ========================================================================
    // Cross-mode conversion tests
    // ========================================================================

    #[test]
    fn test_convert_64_to_32() {
        let m64 = X86AddressMode::base64(x86_register_info::RAX);
        let mut m32 = m64.clone();
        m32.width = AddrWidth::Addr32;
        m32.base = Some(x86_register_info::EAX);
        assert_eq!(m32.width, AddrWidth::Addr32);
        assert_eq!(m32.base, Some(x86_register_info::EAX));
    }

    #[test]
    fn test_convert_64_to_16() {
        let m16 = X86AddressingModeBuilder::new16()
            .with_base(x86_register_info::BX)
            .build();
        assert_eq!(m16.width, AddrWidth::Addr16);
        assert_eq!(m16.base, Some(x86_register_info::BX));
    }

    // ========================================================================
    // Frame pointer mode tests
    // ========================================================================

    #[test]
    fn test_frame_pointer_rbp_with_negative_offset() {
        let addr = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBP)
            .with_disp(-8)
            .with_frame_relative(true)
            .build();
        assert!(addr.is_frame_relative);
        assert_eq!(addr.displacement, -8);
        assert!(addr.fits_disp8());
    }

    #[test]
    fn test_frame_pointer_ebp_with_offset() {
        let addr = X86AddressingModeBuilder::new32()
            .with_base(x86_register_info::EBP)
            .with_disp(-4)
            .with_frame_relative(true)
            .build();
        assert!(addr.is_frame_relative);
        assert_eq!(addr.base, Some(x86_register_info::EBP));
    }

    // ========================================================================
    // Stack pointer addressing tests
    // ========================================================================

    #[test]
    fn test_stack_pointer_rsp_no_disp() {
        let addr = X86AddressMode::base64(x86_register_info::RSP);
        assert!(addr.requires_sib());
        let sib = addr.encode_sib();
        assert_eq!(sib, 0x24);
    }

    #[test]
    fn test_stack_pointer_rsp_with_disp8() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RSP, 16);
        assert!(addr.requires_sib());
        let modrm = addr.encode_modrm(0);
        let mod_field = (modrm >> 6) & 0x3;
        assert_eq!(mod_field, 1);
        assert_eq!(modrm & 0x7, 4);
    }

    // ========================================================================
    // Negative displacement edge cases
    // ========================================================================

    #[test]
    fn test_disp_negative_1() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, -1);
        assert!(addr.fits_disp8());
        assert_eq!(addr.displacement_size(), 1);
        assert_eq!(addr.encode_displacement(), vec![0xFF]);
    }

    #[test]
    fn test_disp_negative_128() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, -128);
        assert!(addr.fits_disp8());
        assert_eq!(addr.displacement_size(), 1);
        assert_eq!(addr.encode_displacement(), vec![0x80]);
    }

    #[test]
    fn test_disp_negative_129() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, -129);
        assert!(!addr.fits_disp8());
        assert_eq!(addr.displacement_size(), 4);
    }

    #[test]
    fn test_disp_positive_127() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, 127);
        assert!(addr.fits_disp8());
        assert_eq!(addr.displacement_size(), 1);
    }

    #[test]
    fn test_disp_positive_128() {
        let addr = X86AddressMode::base_disp64(x86_register_info::RAX, 128);
        assert!(!addr.fits_disp8());
        assert_eq!(addr.displacement_size(), 4);
    }

    // ========================================================================
    // Special SIB encoding tests
    // ========================================================================

    #[test]
    fn test_sib_r12_no_index() {
        let addr = X86AddressMode::base64(x86_register_info::R12);
        assert!(addr.requires_sib());
        assert!(addr.is_special_sib_case());
        let sib = addr.encode_sib();
        assert_eq!((sib >> 3) & 0x7, 4);
        assert_eq!(sib & 0x7, 4);
    }

    #[test]
    fn test_sib_r13_no_index() {
        let addr = X86AddressMode::base64(x86_register_info::R13);
        assert!(addr.requires_sib());
        assert!(addr.is_special_sib_case());
        let sib = addr.encode_sib();
        assert_eq!((sib >> 3) & 0x7, 4);
        assert_eq!(sib & 0x7, 5);
    }

    #[test]
    fn test_sib_rbp_64bit() {
        let addr = X86AddressMode::base64(x86_register_info::RBP);
        assert!(addr.requires_sib());
        assert!(addr.is_special_sib_case());
    }

    #[test]
    fn test_sib_ebp_32bit() {
        let addr = X86AddressMode::base32(x86_register_info::EBP);
        assert!(!addr.requires_sib());
    }

    // ========================================================================
    // Segment interaction tests
    // ========================================================================

    #[test]
    fn test_segment_fs_override() {
        let addr =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::FS);
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);
        assert_eq!(handler.segment_override_prefix(&addr), Some(0x64));
    }

    #[test]
    fn test_segment_gs_override() {
        let addr =
            X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::GS);
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);
        assert_eq!(handler.segment_override_prefix(&addr), Some(0x65));
    }

    #[test]
    fn test_segment_ss_default_for_rsp() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RSP);
        assert_eq!(handler.default_segment(&addr), x86_register_info::SS);
        assert!(!handler.needs_segment_override(&addr));
    }

    #[test]
    fn test_segment_ds_default_for_rax() {
        let engine = X86AddressingFull::new_x86_64();
        let handler = X86SegmentHandling::new(engine);
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert_eq!(handler.default_segment(&addr), x86_register_info::DS);
    }

    // ========================================================================
    // Address hash key uniqueness tests
    // ========================================================================

    #[test]
    fn test_hash_key_different_base() {
        let a = X86AddressMode::base64(x86_register_info::RAX);
        let b = X86AddressMode::base64(x86_register_info::RBX);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    #[test]
    fn test_hash_key_different_disp() {
        let a = X86AddressMode::base_disp64(x86_register_info::RAX, 0);
        let b = X86AddressMode::base_disp64(x86_register_info::RAX, 8);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    #[test]
    fn test_hash_key_different_index() {
        let a = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        let b = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RDI, 4, 0);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    #[test]
    fn test_hash_key_different_scale() {
        let a = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 1, 0);
        let b = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    #[test]
    fn test_hash_key_different_segment() {
        let a = X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::FS);
        let b = X86AddressMode::base64(x86_register_info::RAX).with_segment(x86_register_info::GS);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    #[test]
    fn test_hash_key_rip_vs_absolute() {
        let a = X86AddressMode::rip_relative(0);
        let b = X86AddressMode::absolute32(0);
        assert_ne!(a.hash_key(), b.hash_key());
    }

    // ========================================================================
    // Complex address math tests
    // ========================================================================

    #[test]
    fn test_effective_address_overflow() {
        let result = compute_effective_address(Some(0xFFFF_FFFF_FFFF_FFFF), Some(1), 8, 0);
        assert_eq!(result, 0xFFFF_FFFF_FFFF_FFFFu64.wrapping_add(8));
    }

    #[test]
    fn test_effective_address_all_zero() {
        let result = compute_effective_address(None, None, 1, 0);
        assert_eq!(result, 0);
    }

    #[test]
    fn test_effective_address_max() {
        let result = compute_effective_address(Some(u64::MAX), Some(u64::MAX), 8, i64::MAX as u64);
        let _ = result;
    }

    // ========================================================================
    // Canonicalization edge cases
    // ========================================================================

    #[test]
    fn test_canonicalize_scale_0_to_1() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 0)
            .build();
        assert_eq!(m.scale, 0);
        assert_eq!(m.index, None);
    }

    #[test]
    fn test_canonicalize_scale_3_to_4() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 3)
            .build();
        assert_eq!(m.scale, 4);
    }

    #[test]
    fn test_canonicalize_scale_5_to_4() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 5)
            .build();
        assert_eq!(m.scale, 4);
    }

    #[test]
    fn test_canonicalize_scale_7_to_8() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 7)
            .build();
        assert_eq!(m.scale, 8);
    }

    #[test]
    fn test_canonicalize_scale_9_to_8() {
        let m = X86AddressingModeBuilder::new64()
            .with_base(x86_register_info::RBX)
            .with_index(x86_register_info::RSI, 9)
            .build();
        assert_eq!(m.scale, 8);
    }

    // ========================================================================
    // Prefix order tests
    // ========================================================================

    #[test]
    fn test_prefix_order_segment_before_rex() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr =
            X86AddressMode::base64(x86_register_info::R8).with_segment(x86_register_info::FS);
        let prefixes = pi.encode_all_prefixes(&addr, 0);
        if let Some(seg_pos) = prefixes.iter().position(|&b| b == 0x64) {
            if let Some(rex_pos) = prefixes.iter().position(|&b| b & 0xF0 == 0x40) {
                assert!(seg_pos < rex_pos, "Segment override must come before REX");
            }
        }
    }

    #[test]
    fn test_prefix_order_addr_size_before_rex() {
        let pi = PrefixInteraction::new(AddrWidth::Addr64);
        let addr = X86AddressMode::base32(x86_register_info::EAX);
        let prefixes = pi.encode_all_prefixes(&addr, 0);
        if let Some(addr_pos) = prefixes.iter().position(|&b| b == 0x67) {
            if let Some(rex_pos) = prefixes.iter().position(|&b| b & 0xF0 == 0x40) {
                assert!(
                    addr_pos < rex_pos,
                    "Address size override must come before REX"
                );
            }
        }
    }

    // ========================================================================
    // 16-bit address mode builder integration tests
    // ========================================================================

    #[test]
    fn test_builder_16bit_all_single_registers() {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};
        let regs = [
            (BX, X86Addr16Form::Bx),
            (BP, X86Addr16Form::Bp),
            (SI, X86Addr16Form::Si),
            (DI, X86Addr16Form::Di),
        ];

        for &(reg, expected_form) in &regs {
            let m = X86AddressingModeBuilder::new16().with_base(reg).build();
            assert_eq!(m.form_16bit, Some(expected_form));
            assert!(!m.is_absolute_16);
        }
    }

    #[test]
    fn test_builder_16bit_all_dual_registers() {
        use crate::x86::x86_register_info::{BP, BX, DI, SI};
        let pairs = [
            (BX, SI, X86Addr16Form::BxSi),
            (BX, DI, X86Addr16Form::BxDi),
            (BP, SI, X86Addr16Form::BpSi),
            (BP, DI, X86Addr16Form::BpDi),
        ];

        for &(base, index, expected_form) in &pairs {
            let m = X86AddressingModeBuilder::new16()
                .with_base(base)
                .with_index(index, 1)
                .build();
            assert_eq!(m.form_16bit, Some(expected_form));
        }
    }

    #[test]
    fn test_builder_16bit_disp16_absolute() {
        let m = X86AddressingModeBuilder::new16().with_disp(0x1000).build();
        assert!(m.is_absolute_16);
        assert_eq!(m.form_16bit, Some(X86Addr16Form::Disp16));
    }

    // ========================================================================
    // RIP-relative addressing constraint tests
    // ========================================================================

    #[test]
    fn test_rip_relative_displacement_range() {
        let m = X86AddressMode::rip_relative(2_147_483_647i64);
        assert!(m.fits_disp32());
        assert_eq!(m.displacement_size(), 4);
    }

    #[test]
    fn test_rip_relative_negative_disp() {
        let m = X86AddressMode::rip_relative(-2_147_483_648i64);
        assert!(m.fits_disp32());
        assert_eq!(m.displacement_size(), 4);
    }

    #[test]
    fn test_rip_relative_default_width() {
        let m = X86AddressMode::rip_relative(0);
        assert_eq!(m.width, AddrWidth::Addr64);
    }

    // ========================================================================
    // Memory lowering with various code models
    // ========================================================================

    #[test]
    fn test_lower_global_kernel_model() {
        let engine = X86AddressingFull::new_x86_64().with_code_model(CodeModel::Kernel);
        let lower = X86MemoryLowering::new(engine);
        let addr = lower.lower_global_address("kernel_var", 0, false);
        assert!(addr.symbol.is_some());
    }

    #[test]
    fn test_lower_global_medium_model() {
        let engine = X86AddressingFull::new_x86_64().with_code_model(CodeModel::Medium);
        let lower = X86MemoryLowering::new(engine);
        let addr = lower.lower_global_address("data_var", 0, false);
        assert!(!addr.is_rip_relative || addr.is_absolute_32);
    }

    #[test]
    fn test_lower_global_large_model() {
        let engine = X86AddressingFull::new_x86_64().with_code_model(CodeModel::Large);
        let lower = X86MemoryLowering::new(engine);
        let addr = lower.lower_global_address("far_var", 0, false);
        assert!(addr.is_absolute_32);
    }

    // ========================================================================
    // Final exhaustive ModR/M decoding round-trip
    // ========================================================================

    #[test]
    fn test_exhaustive_direct_modrm_roundtrip() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        let base_regs: [u16; 8] = [0, 1, 2, 3, 5, 6, 7, 8];

        for &rm in &base_regs {
            if rm != 5 {
                let modrm = (Mod00 << 6) | rm;
                let addr = matcher.decode(modrm, None, &[], false, rm >= 8, false);
                if !addr.is_rip_relative {
                    assert_eq!(addr.base, Some(rm));
                    assert_eq!(addr.displacement, 0);
                }
            }

            let modrm_disp8 = (Mod01 << 6) | rm;
            let disp8_bytes = [0x2A];
            let addr_d8 = matcher.decode(modrm_disp8, None, &disp8_bytes, false, rm >= 8, false);
            if rm != 5 {
                assert_eq!(addr_d8.base, Some(rm));
            }
            assert!(addr_d8.displacement == 42 || addr_d8.displacement == 0x2A);

            let modrm_disp32 = (Mod10 << 6) | rm;
            let disp32_bytes = [0x78, 0x56, 0x34, 0x12];
            let addr_d32 = matcher.decode(modrm_disp32, None, &disp32_bytes, false, rm >= 8, false);
            if rm != 5 {
                assert_eq!(addr_d32.base, Some(rm));
            }
        }
    }

    // ========================================================================
    // Stress test: create many address modes, encode, decode, verify
    // ========================================================================

    #[test]
    fn test_stress_many_address_modes_roundtrip() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        let bases = [0u16, 1, 2, 3, 6, 7];
        let indices = [0u16, 1, 2, 3, 5, 6, 7];
        let scales = [1u8, 2, 4, 8];
        let disps = [0i64, 42, -128, 127, 200, -200, 0x1000, -0x1000];

        for &base in &bases {
            for &index in &indices {
                for &scale in &scales {
                    for &disp in &disps {
                        let original = X86AddressMode::full64(base, index, scale, disp);
                        let modrm = original.encode_modrm(0);
                        let sib = if original.requires_sib() {
                            Some(original.encode_sib())
                        } else {
                            None
                        };
                        let disp_bytes = original.encode_displacement();
                        let decoded = matcher.decode(modrm, sib, &disp_bytes, false, false, false);

                        assert_eq!(
                            decoded.base, original.base,
                            "base mismatch: {:?} != {:?} for base={}, index={}, scale={}, disp={}",
                            decoded.base, original.base, base, index, scale, disp
                        );

                        if original.has_index() {
                            assert_eq!(
                                decoded.index, original.index,
                                "index mismatch for base={}, index={}, scale={}, disp={}",
                                base, index, scale, disp
                            );
                        }
                    }
                }
            }
        }
    }

    // ========================================================================
    // Additional edge case and integration tests
    // ========================================================================

    #[test]
    fn test_builder_opt_level_interaction() {
        for level in [OptLevel::None, OptLevel::Default, OptLevel::Aggressive] {
            let engine = X86AddressingFull::new_x86_64().with_opt_level(level);
            let opt = X86AddressOptimization::new(engine);
            let addr = X86AddressMode::base64(x86_register_info::RAX);
            let optimized = opt.optimize(&addr);
            assert_eq!(optimized.base, Some(x86_register_info::RAX));
        }
    }

    #[test]
    fn test_16bit_form_disp_sizes_all_forms() {
        let all_forms = [
            X86Addr16Form::BxSi,
            X86Addr16Form::BxDi,
            X86Addr16Form::BpSi,
            X86Addr16Form::BpDi,
            X86Addr16Form::Si,
            X86Addr16Form::Di,
            X86Addr16Form::Bp,
            X86Addr16Form::Bx,
            X86Addr16Form::BxSiDisp8,
            X86Addr16Form::BxDiDisp8,
            X86Addr16Form::BpSiDisp8,
            X86Addr16Form::BpDiDisp8,
            X86Addr16Form::SiDisp8,
            X86Addr16Form::DiDisp8,
            X86Addr16Form::BpDisp8,
            X86Addr16Form::BxDisp8,
            X86Addr16Form::BxSiDisp16,
            X86Addr16Form::BxDiDisp16,
            X86Addr16Form::BpSiDisp16,
            X86Addr16Form::BpDiDisp16,
            X86Addr16Form::SiDisp16,
            X86Addr16Form::DiDisp16,
            X86Addr16Form::BpDisp16,
            X86Addr16Form::BxDisp16,
            X86Addr16Form::Disp16,
        ];

        for form in &all_forms {
            let disp_size = form.disp_size();
            assert!(
                disp_size <= 2,
                "Form {:?} has invalid disp size {}",
                form,
                disp_size
            );
            let mod_field = form.mod_field();
            assert!(
                mod_field <= 2,
                "Form {:?} has invalid mod field {}",
                form,
                mod_field
            );
            let rm_field = form.rm_field();
            assert!(
                rm_field <= 7,
                "Form {:?} has invalid rm field {}",
                form,
                rm_field
            );
            let name = form.name();
            assert!(!name.is_empty(), "Form {:?} has empty name", form);
        }
    }

    #[test]
    fn test_modrm_form_register_direct() {
        let matcher = AddressingModeMatcher::new(AddrWidth::Addr64);
        let modrm: u8 = 0xC0;
        let addr = matcher.decode(modrm, None, &[], false, false, false);
        assert!(!addr.is_rip_relative);
    }

    #[test]
    fn test_memory_lowering_all_tls_models_64() {
        for &model in &[
            TlsModel::GeneralDynamic,
            TlsModel::LocalDynamic,
            TlsModel::InitialExec,
            TlsModel::LocalExec,
        ] {
            let mut engine = X86AddressingFull::new_x86_64();
            engine.tls_model = model;
            let lower = X86MemoryLowering::new(engine);
            let addr = lower.lower_tls_address("x", 16, true);
            assert_eq!(addr.width, AddrWidth::Addr64);
            assert!(
                addr.segment == Some(x86_register_info::FS)
                    || addr.is_rip_relative
                    || addr.symbol.is_some(),
                "Model {:?} produced addr with no segment, not RIP-relative, no symbol",
                model
            );
        }
    }

    #[test]
    fn test_memory_lowering_all_tls_models_32() {
        for &model in &[
            TlsModel::GeneralDynamic,
            TlsModel::LocalDynamic,
            TlsModel::InitialExec,
            TlsModel::LocalExec,
        ] {
            let mut engine = X86AddressingFull::new_x86_32();
            engine.tls_model = model;
            let lower = X86MemoryLowering::new(engine);
            let addr = lower.lower_tls_address("x", 8, true);
            assert_eq!(addr.width, AddrWidth::Addr32);
            assert!(
                addr.segment == Some(x86_register_info::GS)
                    || addr.is_rip_relative
                    || addr.symbol.is_some(),
                "32-bit model {:?} produced addr with no segment, not RIP-relative, no symbol",
                model
            );
        }
    }

    #[test]
    fn test_full_modrm_table_consistency() {
        let table = CompleteModRMTable::generate_64bit();
        for entry in &table.entries {
            let mod_field = (entry.modrm >> 6) & 0x3;
            assert_eq!(
                mod_field, entry.mod_field,
                "Mod field mismatch in entry {:?}",
                entry.modrm
            );
            let reg_field = (entry.modrm >> 3) & 0x7;
            assert_eq!(reg_field, entry.reg_field, "Reg field mismatch");
            let rm_field = entry.modrm & 0x7;
            assert_eq!(rm_field, entry.rm_field, "RM field mismatch");
            assert!(
                entry.disp_size <= 4,
                "Invalid disp size {}",
                entry.disp_size
            );
            if entry.has_sib {
                assert!(
                    entry.sib_byte.is_some(),
                    "SIB byte missing for entry with has_sib"
                );
            }
        }
    }

    #[test]
    fn test_builder_determines_absolute32() {
        let m = X86AddressingModeBuilder::new32().with_disp(0x1000).build();
        assert!(m.is_absolute_32);
        assert_eq!(m.base, None);
        assert_eq!(m.index, None);
    }

    #[test]
    fn test_builder_determines_not_absolute_with_base() {
        let m = X86AddressingModeBuilder::new32()
            .with_base(x86_register_info::EAX)
            .with_disp(0x1000)
            .build();
        assert!(!m.is_absolute_32);
    }

    #[test]
    fn test_different_widths_produce_different_hash() {
        let addr64 = X86AddressMode::base64(x86_register_info::RAX);
        let addr32 = X86AddressMode::base32(x86_register_info::EAX);
        assert_ne!(addr64.hash_key(), addr32.hash_key());
    }

    #[test]
    fn test_optimization_form_canonicalization_removes_zero_scale() {
        let engine = X86AddressingFull::new_x86_64();
        let opt = X86AddressOptimization::new(engine);
        let addr = X86AddressMode {
            width: AddrWidth::Addr64,
            base: Some(x86_register_info::RBX),
            index: Some(x86_register_info::RSI),
            scale: 0,
            ..Default::default()
        };
        let optimized = opt.optimize(&addr);
        assert_eq!(optimized.index, None);
    }

    #[test]
    fn test_constant_pool_multiple_entries() {
        let mut pool = ConstantPool::new();
        let idx0 = pool.add_entry(4, 4, false);
        let idx1 = pool.add_entry(8, 8, true);
        let idx2 = pool.add_entry(16, 16, false);
        assert_eq!(idx0, 0);
        assert_eq!(idx1, 1);
        assert_eq!(idx2, 2);
        assert_eq!(pool.len(), 3);

        let addr0 = pool.get_address(0).unwrap();
        assert!(addr0.symbol.unwrap().contains("LCPI0"));
        let addr1 = pool.get_address(1).unwrap();
        assert!(addr1.symbol.unwrap().contains("LCPI1"));
        let addr2 = pool.get_address(2).unwrap();
        assert!(addr2.symbol.unwrap().contains("LCPI2"));
    }

    #[test]
    fn test_constant_pool_get_nonexistent() {
        let pool = ConstantPool::new();
        assert!(pool.get_address(0).is_none());
        assert!(pool.get_address(999).is_none());
    }

    #[test]
    fn test_16bit_absolute_address_is_disp16() {
        let m = X86AddressMode::absolute16(0xB800);
        assert!(m.is_absolute_16);
        assert!(!m.is_absolute_32);
        assert!(!m.is_rip_relative);
        assert_eq!(m.form_16bit, Some(X86Addr16Form::Disp16));
        assert_eq!(m.displacement, 0xB800);
    }

    #[test]
    fn test_fold_form_enum_variants() {
        let forms = [
            FoldForm::CannotFold,
            FoldForm::BaseOnly,
            FoldForm::BaseDisp8,
            FoldForm::BaseDisp32,
            FoldForm::FullWithIndex,
            FoldForm::FullWithIndexDisp32,
        ];
        for i in 0..forms.len() {
            for j in (i + 1)..forms.len() {
                assert_ne!(forms[i], forms[j]);
            }
        }
    }

    #[test]
    fn test_is_simple_no_sib() {
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(addr.is_simple());
    }

    #[test]
    fn test_is_not_simple_with_sib() {
        let addr = X86AddressMode::full64(x86_register_info::RBX, x86_register_info::RSI, 4, 0);
        assert!(!addr.is_simple());
    }

    #[test]
    fn test_can_be_lea() {
        let addr = X86AddressMode::base64(x86_register_info::RAX);
        assert!(addr.can_be_lea());
        let rip = X86AddressMode::rip_relative(0);
        assert!(!rip.can_be_lea());
    }

    #[test]
    fn test_addressing_form_names() {
        assert_eq!(AddressingForm::BaseOnly.name(), "[base]");
        assert_eq!(AddressingForm::BaseDisp8.name(), "[base+disp8]");
        assert_eq!(AddressingForm::RipRelative.name(), "[rip+disp32]");
        assert_eq!(AddressingForm::Absolute32.name(), "[disp32]");
        assert_eq!(AddressingForm::Absolute16.name(), "[disp16]");
        assert_eq!(AddressingForm::None.name(), "none");
    }

    #[test]
    fn test_sib_scale_constants() {
        assert_eq!(sib_scale::TIMES_1, 0);
        assert_eq!(sib_scale::TIMES_2, 1);
        assert_eq!(sib_scale::TIMES_4, 2);
        assert_eq!(sib_scale::TIMES_8, 3);
    }

    #[test]
    fn test_sib_field_constants() {
        assert_eq!(sib_field::NO_INDEX, 4);
        assert_eq!(sib_field::DISP32_BASE, 5);
        assert_eq!(sib_field::RSP_BASE, 4);
        assert_eq!(sib_field::RBP_BASE, 5);
    }

    #[test]
    fn test_mod_field_constants() {
        assert_eq!(mod_field::MOD00, 0);
        assert_eq!(mod_field::MOD01, 1);
        assert_eq!(mod_field::MOD10, 2);
        assert_eq!(mod_field::MOD11, 3);
    }

    #[test]
    fn test_modrm_form_enum_variants_distinct() {
        let variants = [
            ModRMForm::BaseOnly,
            ModRMForm::BaseDisp8,
            ModRMForm::BaseDisp32,
            ModRMForm::IndexScale,
            ModRMForm::BaseIndexScale,
            ModRMForm::BaseIndexScaleDisp8,
            ModRMForm::BaseIndexScaleDisp32,
            ModRMForm::RIPRelative,
            ModRMForm::Absolute,
            ModRMForm::RegisterDirect,
        ];
        for i in 0..variants.len() {
            for j in (i + 1)..variants.len() {
                assert_ne!(variants[i], variants[j]);
            }
        }
    }

    #[test]
    fn test_load_lowering_result_fields() {
        let result = LoadLoweringResult {
            address_mode: X86AddressMode::base64(x86_register_info::RAX),
            opcode: X86Opcode::MOV,
            size: 8,
            needs_rex: false,
            needs_sib: false,
        };
        assert_eq!(result.size, 8);
        assert_eq!(result.opcode, X86Opcode::MOV);
    }

    #[test]
    fn test_store_lowering_result_fields() {
        let result = StoreLoweringResult {
            address_mode: X86AddressMode::base64(x86_register_info::RAX),
            opcode: X86Opcode::MOV,
            size: 4,
            needs_rex: false,
            needs_sib: false,
        };
        assert_eq!(result.size, 4);
        assert_eq!(result.opcode, X86Opcode::MOV);
    }

    #[test]
    fn test_opt_level_enum_distinct() {
        assert_ne!(OptLevel::None, OptLevel::Default);
        assert_ne!(OptLevel::Default, OptLevel::Aggressive);
        assert_ne!(OptLevel::None, OptLevel::Aggressive);
    }

    #[test]
    fn test_code_model_enum_distinct() {
        assert_ne!(CodeModel::Small, CodeModel::Kernel);
        assert_ne!(CodeModel::Kernel, CodeModel::Medium);
        assert_ne!(CodeModel::Medium, CodeModel::Large);
    }

    #[test]
    fn test_tls_model_enum_distinct() {
        assert_ne!(TlsModel::GeneralDynamic, TlsModel::LocalDynamic);
        assert_ne!(TlsModel::LocalDynamic, TlsModel::InitialExec);
        assert_ne!(TlsModel::InitialExec, TlsModel::LocalExec);
    }
}