llvm-native-core 0.1.16

//! X86 Garbage Collection Full Support — comprehensive GC framework for X86
//! targets including stack maps, safepoints, GC strategies, runtime integration,
//! barrier mechanisms, allocation, collection algorithms, and finalization.
//!
//! Clean-room behavioral reconstruction from:
//! - LLVM Garbage Collection documentation (Statepoint, PatchPoint intrinsics)
//! - LLVM Stack Map format specification (`.llvm_stackmaps` section)
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//! - System V AMD64 ABI (stack unwinding, register conventions)
//! - OCaml runtime GC interface (frame descriptor tables)
//! - .NET CoreCLR GCInfo specification (fully/partially interruptible regions)
//! - Erlang BEAM runtime GC (per-process heap, reduction-based scheduling)
//! - Published GC algorithm descriptions: Cheney semi-space, mark-sweep,
//!   mark-compact, generational, incremental/concurrent with tri-color marking
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications and black-box oracle interrogation.
//!
//! ## Subsystems
//!
//! - **X86GCStrategy** — GC strategies: ShadowStack, Statepoint, CoreCLR,
//!   Erlang, OCaml, and Custom.
//! - **X86GCRoot** — Root enumeration: stack scanning with frame maps,
//!   register roots, static/global roots, thread-local roots, conservative
//!   and precise root scanning.
//! - **X86GCBarrier** — Read/write barriers: card-marking write barrier,
//!   Brooks-style read barrier, SATB barrier, generational barrier,
//!   concurrent barrier with acquire semantics.
//! - **X86GCAllocator** — Allocation strategies: bump-pointer (inline fast
//!   path), free-list, TLAB (Thread-Local Allocation Buffer), large object
//!   allocation, and slow-path runtime calls.
//! - **X86GCCollector** — Collection algorithms: mark-sweep, mark-compact,
//!   copying (semi-space with Cheney scan), generational (nursery collection
//!   with tenuring), incremental/concurrent with tri-color marking.
//! - **X86GCStackMap** — Stack map generation: frame layout computation,
//!   live pointer tracking, `.llvm_stackmaps` section emission, patchpoint
//!   and statepoint integration.
//! - **X86GCFinalization** — Finalization subsystem: finalizer queue,
//!   weak references, phantom references, ephemeron support.

#![allow(non_upper_case_globals, dead_code)]

use std::collections::{BTreeMap, HashMap, HashSet, VecDeque};
use std::fmt;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, RwLock};

use crate::codegen::MachineInstr;

// ============================================================================
// Constants
// ============================================================================

/// Maximum number of GC roots tracked per function.
pub const X86_GC_MAX_ROOTS: usize = 512;

/// Maximum number of safepoints per function.
pub const X86_GC_MAX_SAFEPOINTS: usize = 1024;

/// Default GC object alignment in bytes.
pub const X86_GC_OBJECT_ALIGNMENT: u32 = 8;

/// Default card size for generational write barrier (in bytes).
pub const X86_GC_CARD_SIZE: u32 = 512;

/// Default remembered set log size (in entries).
pub const X86_GC_REMEMBERED_LOG_SIZE: usize = 12;

/// Stack map version (LLVM current: 3).
pub const X86_GC_STACK_MAP_VERSION: u8 = 3;

/// Stack map ELF section name.
pub const X86_GC_STACK_MAP_SECTION: &str = ".llvm_stackmaps";

/// Default nursery size for generational collector (in bytes).
pub const X86_GC_DEFAULT_NURSERY_SIZE: usize = 4 * 1024 * 1024;

/// Default heap size for copying collector (in bytes, per semi-space).
pub const X86_GC_DEFAULT_SEMISPACE_SIZE: usize = 8 * 1024 * 1024;

/// Default TLAB size (in bytes).
pub const X86_GC_DEFAULT_TLAB_SIZE: usize = 64 * 1024;

/// TLAB refill threshold — when remaining is below this, request new TLAB.
pub const X86_GC_TLAB_REFILL_THRESHOLD: usize = 4096;

/// Large object threshold — objects above this size go to large object space.
pub const X86_GC_LARGE_OBJECT_THRESHOLD: usize = 85 * 1024;

/// Number of reducations between GC checks (Erlang-style).
pub const X86_GC_ERLANG_REDUCTIONS: u64 = 4000;

/// Polling page address — virtual address used for safepoint polling via load.
pub const X86_GC_POLLING_PAGE_ADDR: u64 = 0x7FFF_FFFF_FFFF_F000;

/// Number of bytes in a polling page.
pub const X86_GC_POLLING_PAGE_SIZE: u64 = 4096;

/// Maximum number of finalizers to process per GC cycle.
pub const X86_GC_MAX_FINALIZERS_PER_CYCLE: usize = 1024;

/// Maximum number of weak references to process per GC cycle.
pub const X86_GC_MAX_WEAK_REFS_PER_CYCLE: usize = 4096;

/// Default heap growth factor after collection.
pub const X86_GC_HEAP_GROWTH_FACTOR: f64 = 1.5;

/// Minimum heap occupancy ratio to trigger GC.
pub const X86_GC_MIN_HEAP_OCCUPANCY: f64 = 0.75;

// DWARF register numbers for X86-64.
const DWARF_REG_RAX: u16 = 0;
const DWARF_REG_RDX: u16 = 1;
const DWARF_REG_RCX: u16 = 2;
const DWARF_REG_RBX: u16 = 3;
const DWARF_REG_RSI: u16 = 4;
const DWARF_REG_RDI: u16 = 5;
const DWARF_REG_RBP: u16 = 6;
const DWARF_REG_RSP: u16 = 7;
const DWARF_REG_R8: u16 = 8;
const DWARF_REG_R9: u16 = 9;
const DWARF_REG_R10: u16 = 10;
const DWARF_REG_R11: u16 = 11;
const DWARF_REG_R12: u16 = 12;
const DWARF_REG_R13: u16 = 13;
const DWARF_REG_R14: u16 = 14;
const DWARF_REG_R15: u16 = 15;
const DWARF_REG_RIP: u16 = 16;

/// X86-64 callee-saved GPR DWARF register numbers.
const CALLEE_SAVED_GPRS: &[u16] = &[
    DWARF_REG_RBX,
    DWARF_REG_RBP,
    DWARF_REG_R12,
    DWARF_REG_R13,
    DWARF_REG_R14,
    DWARF_REG_R15,
];

/// X86-64 caller-saved GPR DWARF register numbers (that may hold GC pointers).
const CALLER_SAVED_GPRS: &[u16] = &[
    DWARF_REG_RAX,
    DWARF_REG_RCX,
    DWARF_REG_RDX,
    DWARF_REG_RSI,
    DWARF_REG_RDI,
    DWARF_REG_R8,
    DWARF_REG_R9,
    DWARF_REG_R10,
    DWARF_REG_R11,
];

// ============================================================================
// X86GCStrategy — GC strategies
// ============================================================================

/// GC strategies available for the X86 GC framework.
///
/// Maps to LLVM's gc-strategy function attribute and controls:
/// - How safepoints are inserted (statepoints vs. cooperative suspension)
/// - How roots are tracked (shadow stack vs. stack maps)
/// - What barrier model is used
/// - Whether generational collection is supported
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum X86GCStrategy {
    /// Dual-stack strategy: normal stack + shadow stack for root tracking.
    ///
    /// Every pointer store to the stack is mirrored on a shadow stack.
    /// The GC walks only the shadow stack for roots. This is precise,
    /// portable, and does not require stack map parsing.
    ShadowStack,
    /// Statepoint-based GC. Uses `gc.statepoint` and `gc.relocate`
    /// intrinsics with explicit stack maps. Provides precise root
    /// tracking and supports deoptimization.
    Statepoint,
    /// .NET CoreCLR-compatible GC. Produces GCInfo tables with
    /// fully-interruptible and partially-interruptible regions.
    /// Uses cooperative suspension via GC poll at method entry
    /// and loop backedges.
    CoreCLR,
    /// Erlang-style per-process GC. Each Erlang process has its own
    /// heap and stack. GC only scans the local process heap.
    /// Uses reduction-based scheduling to amortize GC cost.
    Erlang,
    /// OCaml-compatible GC. Produces frame descriptor tables.
    /// Each function has a bitmap of root slots on its frame.
    /// The OCaml runtime uses `caml_call_gc` for allocation slow path.
    OCaml,
    /// User-defined GC strategy with custom parameters.
    /// Allows configuring safepoint placement, barrier kinds,
    /// and root tracking methods independently.
    Custom(X86GCCustomStrategy),
}

/// Configuration for a custom GC strategy.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct X86GCCustomStrategy {
    /// Human-readable name for the custom strategy.
    pub name: String,
    /// Whether to use statepoints for safepoints.
    pub uses_statepoints: bool,
    /// Whether to maintain a shadow stack.
    pub uses_shadow_stack: bool,
    /// Whether generational collection is supported.
    pub supports_generational: bool,
    /// Whether write barriers are required.
    pub requires_write_barriers: bool,
    /// Whether read barriers are required.
    pub requires_read_barriers: bool,
    /// Whether concurrent marking is supported.
    pub supports_concurrent_marking: bool,
    /// Cooperative suspension strategy.
    pub suspension: X86GCSuspension,
    /// Frequency of safepoint polling.
    pub safepoint_frequency: X86GCSafepointFrequency,
    /// Write barrier kind.
    pub write_barrier_kind: X86GCWriteBarrierKind,
    /// Read barrier kind.
    pub read_barrier_kind: X86GCReadBarrierKind,
    /// Custom key-value parameters.
    pub params: Vec<(String, String)>,
}

impl Default for X86GCCustomStrategy {
    fn default() -> Self {
        X86GCCustomStrategy {
            name: "custom".to_string(),
            uses_statepoints: false,
            uses_shadow_stack: false,
            supports_generational: false,
            requires_write_barriers: false,
            requires_read_barriers: false,
            supports_concurrent_marking: false,
            suspension: X86GCSuspension::default(),
            safepoint_frequency: X86GCSafepointFrequency::default(),
            write_barrier_kind: X86GCWriteBarrierKind::None,
            read_barrier_kind: X86GCReadBarrierKind::None,
            params: Vec::new(),
        }
    }
}

/// Cooperative suspension mechanism for GC.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCSuspension {
    /// No cooperative suspension — GC runs at known safe points only.
    None,
    /// Poll-based: threads check a flag at loop backedges and function entries.
    Polling,
    /// Signal-based: threads are stopped via POSIX signals (e.g., SIGUSR1).
    SignalBased,
    /// Page-fault-based: threads load from a guard page; when armed, page fault
    /// triggers GC.
    PageFault,
    /// Hybrid: polling + signal fallback for threads in long-running native code.
    Hybrid,
}

impl Default for X86GCSuspension {
    fn default() -> Self {
        X86GCSuspension::Polling
    }
}

impl fmt::Display for X86GCSuspension {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCSuspension::None => write!(f, "none"),
            X86GCSuspension::Polling => write!(f, "polling"),
            X86GCSuspension::SignalBased => write!(f, "signal"),
            X86GCSuspension::PageFault => write!(f, "pagefault"),
            X86GCSuspension::Hybrid => write!(f, "hybrid"),
        }
    }
}

/// Safepoint polling frequency.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCSafepointFrequency {
    /// Poll at every loop backedge and function entry.
    Always,
    /// Poll every N loop backedges (N = inner value).
    EveryNthBackedge(u32),
    /// Poll only at function entries and calls.
    EntryAndCalls,
    /// Poll only at function entries.
    EntryOnly,
    /// No polling — only statepoints.
    StatepointsOnly,
}

impl Default for X86GCSafepointFrequency {
    fn default() -> Self {
        X86GCSafepointFrequency::Always
    }
}

/// Write barrier kinds.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCWriteBarrierKind {
    /// No write barrier.
    None,
    /// Card marking: set a byte in the card table corresponding to the
    /// written address. Used by generational collectors.
    CardMarking,
    /// Remembered set: record the written address in a remembered set.
    RememberedSet,
    /// SATB (Snapshot-At-The-Beginning): log the old value before overwriting.
    /// Used by concurrent collectors (e.g., G1, Shenandoah).
    SATB,
    /// Yuasa deletion barrier: similar to SATB but triggered on deletion.
    Yuasa,
    /// Steele multiprocessing barrier.
    Steele,
}

impl fmt::Display for X86GCWriteBarrierKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCWriteBarrierKind::None => write!(f, "none"),
            X86GCWriteBarrierKind::CardMarking => write!(f, "card-marking"),
            X86GCWriteBarrierKind::RememberedSet => write!(f, "remembered-set"),
            X86GCWriteBarrierKind::SATB => write!(f, "satb"),
            X86GCWriteBarrierKind::Yuasa => write!(f, "yuasa"),
            X86GCWriteBarrierKind::Steele => write!(f, "steele"),
        }
    }
}

/// Read barrier kinds.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCReadBarrierKind {
    /// No read barrier.
    None,
    /// Brooks-style forwarding pointer: every object has a forwarding pointer
    /// at offset 0. Loads indirect through the forwarding pointer.
    Brooks,
    /// Self-healing barrier: if a stale reference is loaded, update it in place.
    SelfHealing,
    /// Null-check only: verify the loaded reference is non-null before use.
    /// Not a true GC barrier but used in some managed runtimes.
    Conditional,
    /// Load with acquire semantics for concurrent GC.
    AcquireLoad,
}

impl fmt::Display for X86GCReadBarrierKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCReadBarrierKind::None => write!(f, "none"),
            X86GCReadBarrierKind::Brooks => write!(f, "brooks"),
            X86GCReadBarrierKind::SelfHealing => write!(f, "self-healing"),
            X86GCReadBarrierKind::Conditional => write!(f, "conditional"),
            X86GCReadBarrierKind::AcquireLoad => write!(f, "acquire-load"),
        }
    }
}

impl X86GCStrategy {
    /// Returns the human-readable name for this strategy.
    pub fn name(&self) -> &str {
        match self {
            X86GCStrategy::ShadowStack => "shadow-stack",
            X86GCStrategy::Statepoint => "statepoint",
            X86GCStrategy::CoreCLR => "coreclr",
            X86GCStrategy::Erlang => "erlang",
            X86GCStrategy::OCaml => "ocaml",
            X86GCStrategy::Custom(c) => c.name.as_str(),
        }
    }

    /// Whether this strategy uses statepoints.
    pub fn uses_statepoints(&self) -> bool {
        match self {
            X86GCStrategy::Statepoint => true,
            X86GCStrategy::Custom(c) => c.uses_statepoints,
            _ => false,
        }
    }

    /// Whether this strategy uses a shadow stack.
    pub fn uses_shadow_stack(&self) -> bool {
        match self {
            X86GCStrategy::ShadowStack => true,
            X86GCStrategy::Custom(c) => c.uses_shadow_stack,
            _ => false,
        }
    }

    /// Whether this strategy supports generational collection.
    pub fn supports_generational(&self) -> bool {
        match self {
            X86GCStrategy::ShadowStack | X86GCStrategy::Statepoint | X86GCStrategy::CoreCLR => true,
            X86GCStrategy::Custom(c) => c.supports_generational,
            _ => false,
        }
    }

    /// Whether write barriers are required.
    pub fn requires_write_barriers(&self) -> bool {
        match self {
            X86GCStrategy::CoreCLR => true,
            X86GCStrategy::Custom(c) => {
                c.requires_write_barriers && c.write_barrier_kind != X86GCWriteBarrierKind::None
            }
            _ => false,
        }
    }

    /// Whether read barriers are required.
    pub fn requires_read_barriers(&self) -> bool {
        match self {
            X86GCStrategy::Custom(c) => {
                c.requires_read_barriers && c.read_barrier_kind != X86GCReadBarrierKind::None
            }
            _ => false,
        }
    }

    /// Whether concurrent marking is supported.
    pub fn supports_concurrent_marking(&self) -> bool {
        match self {
            X86GCStrategy::ShadowStack | X86GCStrategy::Statepoint | X86GCStrategy::CoreCLR => true,
            X86GCStrategy::Custom(c) => c.supports_concurrent_marking,
            _ => false,
        }
    }

    /// Whether cooperative suspension is used.
    pub fn uses_cooperative_suspension(&self) -> bool {
        match self {
            X86GCStrategy::CoreCLR | X86GCStrategy::Erlang => true,
            X86GCStrategy::Custom(c) => c.suspension != X86GCSuspension::None,
            _ => false,
        }
    }

    /// The safepoint polling frequency.
    pub fn safepoint_frequency(&self) -> X86GCSafepointFrequency {
        match self {
            X86GCStrategy::ShadowStack => X86GCSafepointFrequency::StatepointsOnly,
            X86GCStrategy::Statepoint => X86GCSafepointFrequency::StatepointsOnly,
            X86GCStrategy::CoreCLR => X86GCSafepointFrequency::Always,
            X86GCStrategy::Erlang => X86GCSafepointFrequency::EveryNthBackedge(1),
            X86GCStrategy::OCaml => X86GCSafepointFrequency::EntryAndCalls,
            X86GCStrategy::Custom(c) => c.safepoint_frequency,
        }
    }

    /// The write barrier kind used by this strategy.
    pub fn write_barrier_kind(&self) -> X86GCWriteBarrierKind {
        match self {
            X86GCStrategy::CoreCLR => X86GCWriteBarrierKind::CardMarking,
            X86GCStrategy::Custom(c) => c.write_barrier_kind,
            _ => X86GCWriteBarrierKind::None,
        }
    }

    /// The read barrier kind used by this strategy.
    pub fn read_barrier_kind(&self) -> X86GCReadBarrierKind {
        match self {
            X86GCStrategy::Custom(c) => c.read_barrier_kind,
            _ => X86GCReadBarrierKind::None,
        }
    }

    /// The suspension mechanism used by this strategy.
    pub fn suspension(&self) -> X86GCSuspension {
        match self {
            X86GCStrategy::CoreCLR => X86GCSuspension::Polling,
            X86GCStrategy::Erlang => X86GCSuspension::None,
            X86GCStrategy::Custom(c) => c.suspension,
            _ => X86GCSuspension::None,
        }
    }
}

impl Default for X86GCStrategy {
    fn default() -> Self {
        X86GCStrategy::Statepoint
    }
}

impl fmt::Display for X86GCStrategy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.name())
    }
}

// ============================================================================
// X86GCRoot — Root enumeration
// ============================================================================

/// A GC root — a location that contains or may contain a pointer to a
/// GC-managed object. Roots are the starting points for the mark phase.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct X86GCRoot {
    /// Unique identifier for this root within a function.
    pub id: u32,
    /// Frame offset from RBP/RSP (negative for locals/spills, positive for args).
    pub frame_offset: i32,
    /// The DWARF register number if this root lives in a register.
    pub register: Option<u16>,
    /// The size of the root in bytes (4 for 32-bit, 8 for 64-bit pointers).
    pub pointer_size: u8,
    /// Optional type metadata for precise scanning.
    pub type_metadata: Option<X86GCRootType>,
    /// Whether this is a derived pointer (interior pointer into an object).
    pub is_derived: bool,
    /// For derived pointers, the ID of the base pointer root.
    pub base_root_id: Option<u32>,
    /// For derived pointers, the offset from the base object start.
    pub interior_offset: i64,
    /// Whether this root is constant (e.g., a global variable).
    pub is_constant: bool,
    /// Whether this root needs relocation after compaction.
    pub needs_relocation: bool,
    /// Source language that created this root.
    pub source_language: X86GCRootLanguage,
    /// Whether this root is live at the current program point.
    pub is_live: bool,
    /// Whether this root is in a callee-saved register.
    pub is_callee_saved: bool,
    /// The offset in the function where the root becomes live.
    pub live_start_offset: u32,
    /// The offset in the function where the root becomes dead.
    pub live_end_offset: u32,
    /// For global/static roots, the symbol name.
    pub symbol_name: Option<String>,
    /// For thread-local roots, the TLS index.
    pub tls_index: Option<u32>,
}

/// Type metadata for a GC root — enables precise scanning by describing
/// which fields within an object are pointers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum X86GCRootType {
    /// A single pointer value.
    Pointer,
    /// A struct with known field layout.
    Struct {
        /// Total size of the struct in bytes.
        size: u32,
        /// Bitmap of pointer fields (bit i set = offset i*pointer_size is pointer).
        pointer_bitmap: Vec<u64>,
    },
    /// An array of pointers.
    PointerArray {
        /// Number of elements.
        length: u32,
    },
    /// An array of structs with known layout.
    StructArray {
        /// Number of elements.
        length: u32,
        /// The struct type.
        struct_type: Box<X86GCRootType>,
    },
    /// A tagged union (sum type).
    TaggedUnion {
        /// The offset of the tag field.
        tag_offset: u32,
        /// Mapping from tag value to type.
        variants: HashMap<u32, Box<X86GCRootType>>,
    },
    /// An opaque type — conservative scanning required.
    Opaque {
        /// Size in bytes.
        size: u32,
    },
    /// An object with no pointer fields (leaf).
    Leaf,
    /// A weak reference.
    WeakPointer,
    /// A finalizable object reference.
    Finalizable,
    /// Custom type with a name for the runtime.
    Custom(String),
}

impl X86GCRootType {
    /// Returns true if this type contains any pointer fields.
    pub fn has_pointers(&self) -> bool {
        match self {
            X86GCRootType::Pointer => true,
            X86GCRootType::Struct { pointer_bitmap, .. } => pointer_bitmap.iter().any(|&w| w != 0),
            X86GCRootType::PointerArray { .. } => true,
            X86GCRootType::StructArray { struct_type, .. } => struct_type.has_pointers(),
            X86GCRootType::TaggedUnion { .. } => true,
            X86GCRootType::Opaque { .. } => true, // Conservative
            X86GCRootType::Leaf => false,
            X86GCRootType::WeakPointer => true,
            X86GCRootType::Finalizable => true,
            X86GCRootType::Custom(_) => true,
        }
    }

    /// Returns true if precise scanning is possible (non-opaque).
    pub fn is_precise(&self) -> bool {
        !matches!(self, X86GCRootType::Opaque { .. })
    }

    /// Size in bytes.
    pub fn size(&self) -> u32 {
        match self {
            X86GCRootType::Pointer => 8,
            X86GCRootType::Struct { size, .. } => *size,
            X86GCRootType::PointerArray { length } => length * 8,
            X86GCRootType::StructArray {
                length,
                struct_type,
                ..
            } => length * struct_type.size(),
            X86GCRootType::TaggedUnion { .. } => 16, // Conservative estimate
            X86GCRootType::Opaque { size } => *size,
            X86GCRootType::Leaf => 0,
            X86GCRootType::WeakPointer => 8,
            X86GCRootType::Finalizable => 8,
            X86GCRootType::Custom(_) => 8,
        }
    }
}

/// Source language origin of a GC root.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCRootLanguage {
    /// C/C++ (conservative GC only).
    C,
    /// Rust.
    Rust,
    /// Java.
    Java,
    /// C# / .NET.
    CSharp,
    /// Go.
    Go,
    /// Erlang.
    Erlang,
    /// OCaml.
    OCaml,
    /// Python.
    Python,
    /// JavaScript.
    JavaScript,
    /// Unknown language.
    Unknown,
}

impl Default for X86GCRootLanguage {
    fn default() -> Self {
        X86GCRootLanguage::Unknown
    }
}

impl fmt::Display for X86GCRootLanguage {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCRootLanguage::C => write!(f, "c"),
            X86GCRootLanguage::Rust => write!(f, "rust"),
            X86GCRootLanguage::Java => write!(f, "java"),
            X86GCRootLanguage::CSharp => write!(f, "csharp"),
            X86GCRootLanguage::Go => write!(f, "go"),
            X86GCRootLanguage::Erlang => write!(f, "erlang"),
            X86GCRootLanguage::OCaml => write!(f, "ocaml"),
            X86GCRootLanguage::Python => write!(f, "python"),
            X86GCRootLanguage::JavaScript => write!(f, "javascript"),
            X86GCRootLanguage::Unknown => write!(f, "unknown"),
        }
    }
}

impl X86GCRoot {
    /// Create a new base pointer root.
    pub fn new_base(id: u32, frame_offset: i32) -> Self {
        X86GCRoot {
            id,
            frame_offset,
            register: None,
            pointer_size: 8,
            type_metadata: Some(X86GCRootType::Pointer),
            is_derived: false,
            base_root_id: None,
            interior_offset: 0,
            is_constant: false,
            needs_relocation: true,
            source_language: X86GCRootLanguage::Unknown,
            is_live: true,
            is_callee_saved: false,
            live_start_offset: 0,
            live_end_offset: u32::MAX,
            symbol_name: None,
            tls_index: None,
        }
    }

    /// Create a new derived pointer root.
    pub fn new_derived(
        id: u32,
        frame_offset: i32,
        base_root_id: u32,
        interior_offset: i64,
    ) -> Self {
        X86GCRoot {
            id,
            frame_offset,
            register: None,
            pointer_size: 8,
            type_metadata: Some(X86GCRootType::Pointer),
            is_derived: true,
            base_root_id: Some(base_root_id),
            interior_offset,
            is_constant: false,
            needs_relocation: true,
            source_language: X86GCRootLanguage::Unknown,
            is_live: true,
            is_callee_saved: false,
            live_start_offset: 0,
            live_end_offset: u32::MAX,
            symbol_name: None,
            tls_index: None,
        }
    }

    /// Create a new register root.
    pub fn new_register(id: u32, dwarf_reg: u16) -> Self {
        X86GCRoot {
            id,
            frame_offset: 0,
            register: Some(dwarf_reg),
            pointer_size: 8,
            type_metadata: Some(X86GCRootType::Pointer),
            is_derived: false,
            base_root_id: None,
            interior_offset: 0,
            is_constant: false,
            needs_relocation: true,
            source_language: X86GCRootLanguage::Unknown,
            is_live: true,
            is_callee_saved: false,
            live_start_offset: 0,
            live_end_offset: u32::MAX,
            symbol_name: None,
            tls_index: None,
        }
    }

    /// Create a new static (global) root.
    pub fn new_static(id: u32, symbol_name: String) -> Self {
        X86GCRoot {
            id,
            frame_offset: 0,
            register: None,
            pointer_size: 8,
            type_metadata: Some(X86GCRootType::Pointer),
            is_derived: false,
            base_root_id: None,
            interior_offset: 0,
            is_constant: true,
            needs_relocation: true,
            source_language: X86GCRootLanguage::Unknown,
            is_live: true,
            is_callee_saved: false,
            live_start_offset: 0,
            live_end_offset: u32::MAX,
            symbol_name: Some(symbol_name),
            tls_index: None,
        }
    }

    /// Create a new thread-local root.
    pub fn new_thread_local(id: u32, tls_index: u32) -> Self {
        X86GCRoot {
            id,
            frame_offset: 0,
            register: None,
            pointer_size: 8,
            type_metadata: Some(X86GCRootType::Pointer),
            is_derived: false,
            base_root_id: None,
            interior_offset: 0,
            is_constant: false,
            needs_relocation: true,
            source_language: X86GCRootLanguage::Unknown,
            is_live: true,
            is_callee_saved: false,
            live_start_offset: 0,
            live_end_offset: u32::MAX,
            symbol_name: None,
            tls_index: Some(tls_index),
        }
    }

    /// Attach type metadata for precise scanning.
    pub fn with_type_metadata(mut self, metadata: X86GCRootType) -> Self {
        self.type_metadata = Some(metadata);
        self
    }

    /// Set the source language.
    pub fn with_language(mut self, language: X86GCRootLanguage) -> Self {
        self.source_language = language;
        self
    }

    /// Mark the root as callee-saved (lives in a callee-saved register).
    pub fn mark_callee_saved(mut self) -> Self {
        self.is_callee_saved = true;
        self
    }

    /// Set the live range for this root.
    pub fn with_live_range(mut self, start: u32, end: u32) -> Self {
        self.live_start_offset = start;
        self.live_end_offset = end;
        self
    }

    /// Mark as dead (not live at current point).
    pub fn mark_dead(mut self) -> Self {
        self.is_live = false;
        self
    }

    /// The size of the slot this root occupies (pointer_size or derived from type).
    pub fn slot_size(&self) -> u32 {
        self.type_metadata
            .as_ref()
            .map(|t| t.size())
            .unwrap_or(self.pointer_size as u32)
    }

    /// Check if this root is live at the given instruction offset.
    pub fn is_live_at(&self, offset: u32) -> bool {
        self.is_live && offset >= self.live_start_offset && offset <= self.live_end_offset
    }

    /// For derived pointers, get the base root ID.
    pub fn base_root_id(&self) -> Option<u32> {
        self.base_root_id
    }

    /// Check if this root needs conservative scanning.
    pub fn needs_conservative_scan(&self) -> bool {
        self.type_metadata
            .as_ref()
            .map(|t| !t.is_precise())
            .unwrap_or(true)
    }
}

/// Scanned result from stack walking — a candidate pointer range.
#[derive(Debug, Clone)]
pub struct X86GCRootCandidate {
    /// The raw value read from memory.
    pub raw_value: u64,
    /// The address in the stack where this value was found.
    pub stack_address: u64,
    /// The frame offset of this location.
    pub frame_offset: i32,
    /// Whether this value looks like a valid heap pointer.
    pub is_valid_heap_ptr: bool,
    /// Whether this was found via conservative or precise scanning.
    pub scan_mode: X86GCScanMode,
}

/// Root scanning mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCScanMode {
    /// Precise scanning using type metadata — only known pointer fields are traced.
    Precise,
    /// Conservative scanning — any aligned value that looks heap-like is traced.
    Conservative,
    /// Hybrid: precise for known types, conservative fallback for opaque.
    Hybrid,
}

// ============================================================================
// X86GCBarrier — Read/write barriers
// ============================================================================

/// A write barrier — executed before or after a pointer store to maintain
/// GC invariants (generational remembered set, SATB snapshot, etc.).
#[derive(Debug, Clone)]
pub struct X86GCBarrier {
    /// The kind of barrier.
    pub barrier_type: X86GCBarrierType,
    /// The kind of write barrier (if applicable).
    pub write_barrier_kind: X86GCWriteBarrierKind,
    /// The kind of read barrier (if applicable).
    pub read_barrier_kind: X86GCReadBarrierKind,
    /// The base address of the object being mutated.
    pub object_base: u64,
    /// The field offset within the object.
    pub field_offset: u64,
    /// The new value being stored (for write barriers).
    pub new_value: Option<u64>,
    /// The old value being overwritten (for SATB barriers).
    pub old_value: Option<u64>,
    /// Whether this is an array element store.
    pub is_array_element: bool,
    /// The number of times this barrier has been emitted.
    pub emit_count: u64,
}

/// General barrier type classification.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCBarrierType {
    /// A write barrier.
    Write,
    /// A read barrier.
    Read,
    /// Both read and write barriers needed.
    ReadWrite,
    /// A CAS (compare-and-swap) barrier.
    CAS,
    /// An atomic RMW (read-modify-write) barrier.
    AtomicRMW,
}

impl X86GCBarrier {
    /// Create a card-marking write barrier.
    pub fn new_card_marking(object_base: u64, field_offset: u64, new_value: u64) -> Self {
        X86GCBarrier {
            barrier_type: X86GCBarrierType::Write,
            write_barrier_kind: X86GCWriteBarrierKind::CardMarking,
            read_barrier_kind: X86GCReadBarrierKind::None,
            object_base,
            field_offset,
            new_value: Some(new_value),
            old_value: None,
            is_array_element: false,
            emit_count: 0,
        }
    }

    /// Create a SATB write barrier.
    pub fn new_satb(object_base: u64, field_offset: u64, old_value: u64) -> Self {
        X86GCBarrier {
            barrier_type: X86GCBarrierType::Write,
            write_barrier_kind: X86GCWriteBarrierKind::SATB,
            read_barrier_kind: X86GCReadBarrierKind::None,
            object_base,
            field_offset,
            new_value: None,
            old_value: Some(old_value),
            is_array_element: false,
            emit_count: 0,
        }
    }

    /// Create a generational write barrier (card marking).
    pub fn new_generational(object_base: u64, field_offset: u64, new_value: u64) -> Self {
        X86GCBarrier {
            barrier_type: X86GCBarrierType::Write,
            write_barrier_kind: X86GCWriteBarrierKind::CardMarking,
            read_barrier_kind: X86GCReadBarrierKind::None,
            object_base,
            field_offset,
            new_value: Some(new_value),
            old_value: None,
            is_array_element: false,
            emit_count: 0,
        }
    }

    /// Create a Brooks-style read barrier.
    pub fn new_brooks_read(object_base: u64) -> Self {
        X86GCBarrier {
            barrier_type: X86GCBarrierType::Read,
            write_barrier_kind: X86GCWriteBarrierKind::None,
            read_barrier_kind: X86GCReadBarrierKind::Brooks,
            object_base,
            field_offset: 0,
            new_value: None,
            old_value: None,
            is_array_element: false,
            emit_count: 0,
        }
    }

    /// Create an acquire-load barrier for concurrent GC.
    pub fn new_acquire_load(object_base: u64) -> Self {
        X86GCBarrier {
            barrier_type: X86GCBarrierType::Read,
            write_barrier_kind: X86GCWriteBarrierKind::None,
            read_barrier_kind: X86GCReadBarrierKind::AcquireLoad,
            object_base,
            field_offset: 0,
            new_value: None,
            old_value: None,
            is_array_element: false,
            emit_count: 0,
        }
    }

    /// Mark this as an array element store.
    pub fn mark_array_element(mut self) -> Self {
        self.is_array_element = true;
        self
    }

    /// Increment the emission counter.
    pub fn record_emit(&mut self) {
        self.emit_count += 1;
    }

    /// Generate the X86-64 machine instruction sequence for a card-marking
    /// write barrier.
    ///
    /// The canonical sequence is:
    /// ```asm
    /// mov [object_base + field_offset], new_value   ; actual store
    /// mov rtmp, object_base                         ; compute card index
    /// shr rtmp, card_shift                           ; card_index = addr >> shift
    /// mov byte [card_table_base + rtmp], 0           ; mark card dirty
    /// ```
    pub fn emit_x86_card_marking_asm(&self, card_table_base: u64, card_shift: u8) -> Vec<u8> {
        let new_val = self.new_value.unwrap_or(0);
        let mut code = Vec::with_capacity(32);

        // MOV [object_base + field_offset], new_value
        // REX.W + MOV r/m64, imm32 (sign-extended)
        let full_addr = self.object_base.wrapping_add(self.field_offset);
        code.push(0x48); // REX.W
        code.push(0xC7); // MOV r/m64, imm32
        if (full_addr >> 32) == 0 && full_addr <= 0x7FFF_FFFF {
            // Can use SIB for absolute addressing in low 2GB
            code.push(0x04);
            code.push(0x25);
            code.extend_from_slice(&(full_addr as u32).to_le_bytes());
        } else {
            // Use RSP-relative or indirect — simplified: push new_val; use RAX
            code.push(0x04); // ModRM: [--][--]
            code.push(0x24); // SIB: no base, no index
            code.push(0x00);
        }
        code.extend_from_slice(&(new_val as u32).to_le_bytes());

        // MOV rax, object_base
        code.push(0x48); // REX.W
        code.push(0xB8); // MOV RAX, imm64
        code.extend_from_slice(&self.object_base.to_le_bytes());

        // SHR rax, card_shift
        code.push(0x48); // REX.W
        code.push(0xC1); // Shift r/m64, imm8
        code.push(0xE8); // ModRM: SHR RAX
        code.push(card_shift);

        // MOV byte [card_table_base + rax], 0
        code.push(0xC6); // MOV r/m8, imm8
        code.push(0x80); // ModRM: [RAX + disp32]
        code.extend_from_slice(&(card_table_base as u32).to_le_bytes());
        code.push(0x00); // imm8 = 0 (mark dirty)

        code
    }

    /// Generate the X86-64 machine instruction sequence for a SATB barrier.
    pub fn emit_x86_satb_asm(&self, satb_buffer_addr: u64, satb_index_addr: u64) -> Vec<u8> {
        let mut code = Vec::with_capacity(48);

        // MOV rax, [satb_index_addr]          ; load current index
        code.push(0x48);
        code.push(0xA1);
        code.extend_from_slice(&satb_index_addr.to_le_bytes());

        // CMP rax, [satb_buffer_limit]        ; compare against limit
        // (simplified: assume limit is infinite for this code gen)

        // MOV rdx, old_value
        let old = self.old_value.unwrap_or(0);
        code.push(0x48);
        code.push(0xBA);
        code.extend_from_slice(&old.to_le_bytes());

        // MOV [satb_buffer + rax*8], rdx      ; store old value at buffer[idx]
        code.push(0x48);
        code.push(0x89);
        code.push(0xD4);
        code.push(0xC0);
        code.extend_from_slice(&satb_buffer_addr.to_le_bytes());

        // INC rax                               ; increment index
        code.push(0x48);
        code.push(0xFF);
        code.push(0xC0);

        // MOV [satb_index_addr], rax           ; store new index
        code.push(0x48);
        code.push(0x89);
        code.push(0x04);
        code.push(0x25);
        code.extend_from_slice(&satb_index_addr.to_le_bytes());

        code
    }

    /// Generate the X86-64 machine code for a Brooks-style read barrier.
    ///
    /// The Brooks barrier loads the forwarding pointer from offset 0 of the
    /// object, then loads the actual field. On X86 this is:
    /// ```asm
    /// mov rax, [object_base]        ; load forwarding pointer
    /// mov rax, [rax + field_offset] ; load actual field
    /// ```
    pub fn emit_x86_brooks_read_asm(&self) -> Vec<u8> {
        let mut code = Vec::with_capacity(16);

        // MOV RAX, [object_base] — load forwarding pointer
        let full = self.object_base;
        code.push(0x48);
        code.push(0xA1);
        code.extend_from_slice(&full.to_le_bytes());

        // MOV RAX, [RAX + field_offset] — load from forwarded object
        code.push(0x48);
        code.push(0x8B);
        code.push(0x80);
        code.extend_from_slice(&(self.field_offset as u32).to_le_bytes());

        code
    }

    /// Generate X86-64 acquire-load (MFENCE after load, or LOCK ADD on X86
    /// where loads are already ordered).
    pub fn emit_x86_acquire_load_asm(&self) -> Vec<u8> {
        let mut code = Vec::with_capacity(24);

        // MOV RAX, [object_base]
        code.push(0x48);
        code.push(0xA1);
        code.extend_from_slice(&self.object_base.to_le_bytes());

        // On X86, all loads have acquire semantics already.
        // But we add an LFENCE for clarity if needed.
        // LFENCE: 0F AE E8
        code.push(0x0F);
        code.push(0xAE);
        code.push(0xE8);

        code
    }
}

// ============================================================================
// X86GCAllocator — Allocation strategies
// ============================================================================

/// Bump-pointer allocator — the fast path for allocation.
///
/// Maintains a cursor and limit. Allocation bumps the cursor. When the
/// cursor exceeds the limit, the slow path (a runtime call) is invoked.
#[derive(Debug, Clone)]
pub struct X86GCBumpAllocator {
    /// Base address of the allocation region.
    pub base: u64,
    /// Current allocation cursor.
    pub cursor: u64,
    /// End of the allocation region (exclusive).
    pub limit: u64,
    /// Total bytes allocated.
    pub bytes_allocated: u64,
    /// Total allocation count.
    pub allocation_count: u64,
    /// Number of slow-path invocations.
    pub slow_path_count: u64,
    /// Alignment requirement for allocations.
    pub alignment: u32,
}

impl X86GCBumpAllocator {
    /// Create a new bump-pointer allocator with the given region.
    pub fn new(base: u64, size: u64, alignment: u32) -> Self {
        X86GCBumpAllocator {
            base,
            cursor: base,
            limit: base + size,
            bytes_allocated: 0,
            allocation_count: 0,
            slow_path_count: 0,
            alignment,
        }
    }

    /// Fast-path allocation. Returns the address of the allocation or 0
    /// if the slow path is needed.
    pub fn allocate_fast(&mut self, size: u64) -> u64 {
        let aligned_size = (size + self.alignment as u64 - 1) & !(self.alignment as u64 - 1);
        let new_cursor = self.cursor.wrapping_add(aligned_size);

        if new_cursor <= self.limit {
            let result = self.cursor;
            self.cursor = new_cursor;
            self.bytes_allocated += aligned_size;
            self.allocation_count += 1;
            result
        } else {
            self.slow_path_count += 1;
            0
        }
    }

    /// Reset the allocator to empty.
    pub fn reset(&mut self) {
        self.cursor = self.base;
    }

    /// Remaining free bytes in the region.
    pub fn remaining(&self) -> u64 {
        self.limit.saturating_sub(self.cursor)
    }

    /// Whether the bump region is exhausted.
    pub fn is_exhausted(&self) -> bool {
        self.cursor >= self.limit
    }

    /// Generate the X86-64 inline fast-path allocation code.
    ///
    /// The canonical sequence is:
    /// ```asm
    /// mov rax, [cursor_addr]          ; load cursor
    /// lea rdx, [rax + size]           ; compute new cursor
    /// cmp rdx, [limit_addr]           ; compare against limit
    /// ja slow_path                    ; jump to slow path if exceeded
    /// mov [cursor_addr], rdx          ; store new cursor
    ///                                 ; rax now contains allocated address
    /// ```
    pub fn emit_x86_fast_path_asm(&self, size: u64, cursor_addr: u64, limit_addr: u64) -> Vec<u8> {
        let mut code = Vec::with_capacity(32);

        // MOV RAX, [cursor_addr]
        code.push(0x48);
        code.push(0xA1);
        code.extend_from_slice(&cursor_addr.to_le_bytes());

        // LEA RDX, [RAX + size]
        let aligned = (size + self.alignment as u64 - 1) & !(self.alignment as u64 - 1);
        code.push(0x48);
        if aligned <= 0x7FFF_FFFF {
            code.push(0x8D);
            code.push(0x90);
            code.extend_from_slice(&(aligned as u32).to_le_bytes());
        } else {
            // Large size: use ADD followed by alignment
            code.push(0x8D); // LEA is hard for large constants
            code.push(0x90);
            code.extend_from_slice(&(aligned as u32).to_le_bytes());
        }

        // CMP RDX, [limit_addr]
        code.push(0x48);
        code.push(0x3B);
        code.push(0x14);
        code.push(0x25);
        code.extend_from_slice(&limit_addr.to_le_bytes());

        // JA slow_path (encoded as offset 6 bytes forward for now)
        code.push(0x0F);
        code.push(0x87);
        code.push(0x06);
        code.push(0x00);
        code.push(0x00);
        code.push(0x00);

        // MOV [cursor_addr], RDX
        code.push(0x48);
        code.push(0x89);
        code.push(0x14);
        code.push(0x25);
        code.extend_from_slice(&cursor_addr.to_le_bytes());

        code
    }
}

/// Free-list allocator — maintains lists of free blocks by size class.
#[derive(Debug, Clone)]
pub struct X86GCFreeListAllocator {
    /// Free lists keyed by size class.
    pub free_lists: BTreeMap<u32, Vec<X86GCFreeBlock>>,
    /// Whether to coalesce adjacent free blocks.
    pub coalesce: bool,
    /// Total bytes allocated.
    pub bytes_allocated: u64,
    /// Total bytes freed.
    pub bytes_freed: u64,
    /// Maximum heap size.
    pub max_heap_size: u64,
    /// Current heap size (including allocated and free blocks).
    pub current_heap_size: u64,
    /// Allocation count.
    pub allocation_count: u64,
}

/// A free block in the free-list allocator.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCFreeBlock {
    /// Starting address of the free block.
    pub address: u64,
    /// Size of the free block in bytes.
    pub size: u32,
}

impl X86GCFreeListAllocator {
    /// Create a new free-list allocator.
    pub fn new(max_heap_size: u64) -> Self {
        X86GCFreeListAllocator {
            free_lists: BTreeMap::new(),
            coalesce: true,
            bytes_allocated: 0,
            bytes_freed: 0,
            max_heap_size,
            current_heap_size: 0,
            allocation_count: 0,
        }
    }

    /// Add a free block to the free list.
    pub fn add_free_block(&mut self, address: u64, size: u32) {
        let size_class = Self::size_class(size);
        self.free_lists
            .entry(size_class)
            .or_insert_with(Vec::new)
            .push(X86GCFreeBlock { address, size });
    }

    /// Allocate from the free list. Returns 0 if no suitable block found.
    pub fn allocate(&mut self, size: u32) -> u64 {
        let size_class = Self::size_class(size);

        // Try exact size class first
        if let Some(blocks) = self.free_lists.get_mut(&size_class) {
            if let Some((idx, _)) = blocks.iter().enumerate().find(|(_, b)| b.size >= size) {
                let block = blocks.remove(idx);
                self.bytes_allocated += block.size as u64;
                self.allocation_count += 1;

                // If the block is larger than needed, split and return remainder
                if block.size > size {
                    let remainder_addr = block.address + size as u64;
                    let remainder_size = block.size - size;
                    self.add_free_block(remainder_addr, remainder_size);
                }

                return block.address;
            }
        }

        // Try larger size classes
        for (&sc, blocks) in self.free_lists.range_mut(size_class + 1..) {
            if sc < size_class {
                continue;
            }
            if let Some(block) = blocks.pop() {
                if block.size >= size {
                    self.bytes_allocated += block.size as u64;
                    self.allocation_count += 1;
                    if block.size > size {
                        self.add_free_block(block.address + size as u64, block.size - size);
                    }
                    return block.address;
                }
                // Put it back if too small
                blocks.push(block);
            }
        }

        0
    }

    /// Free an allocated block, returning it to the free list.
    pub fn free(&mut self, address: u64, size: u32) {
        self.bytes_freed += size as u64;
        self.add_free_block(address, size);

        if self.coalesce {
            self.try_coalesce(address);
        }
    }

    /// Try to coalesce adjacent free blocks.
    fn try_coalesce(&mut self, _address: u64) {
        // Collect all free blocks, sort, and merge adjacent ones
        let mut all_blocks: Vec<X86GCFreeBlock> = self
            .free_lists
            .values()
            .flat_map(|v| v.iter().copied())
            .collect();

        all_blocks.sort_by_key(|b| b.address);

        let mut merged: Vec<X86GCFreeBlock> = Vec::new();
        for block in all_blocks {
            if let Some(last) = merged.last_mut() {
                if last.address + last.size as u64 == block.address {
                    last.size += block.size;
                    continue;
                }
            }
            merged.push(block);
        }

        // Rebuild free lists
        self.free_lists.clear();
        for block in merged {
            self.add_free_block(block.address, block.size);
        }
    }

    /// Compute the size class for a given allocation size.
    fn size_class(size: u32) -> u32 {
        if size <= 16 {
            16
        } else if size <= 32 {
            32
        } else if size <= 64 {
            64
        } else if size <= 128 {
            128
        } else if size <= 256 {
            256
        } else if size <= 512 {
            512
        } else if size <= 1024 {
            1024
        } else if size <= 2048 {
            2048
        } else if size <= 4096 {
            4096
        } else if size <= 8192 {
            8192
        } else {
            // Large object: round up to 85K
            ((size + 85 * 1024 - 1) / (85 * 1024)) * 85 * 1024
        }
    }

    /// Total free bytes available.
    pub fn free_bytes(&self) -> u64 {
        self.free_lists
            .values()
            .flat_map(|v| v.iter().map(|b| b.size as u64))
            .sum()
    }

    /// Fragmentation ratio (0.0 = perfect, 1.0 = fully fragmented).
    pub fn fragmentation_ratio(&self) -> f64 {
        let total_free = self.free_bytes();
        let free_blocks: usize = self.free_lists.values().map(|v| v.len()).sum();
        if free_blocks == 0 {
            return 0.0;
        }
        let avg_block_size = total_free as f64 / free_blocks as f64;
        1.0 - (avg_block_size / avg_block_size.max(1.0))
    }
}

/// Thread-Local Allocation Buffer (TLAB) — per-thread bump-pointer region
/// that avoids synchronization on the fast path.
#[derive(Debug, Clone)]
pub struct X86GCTLAB {
    /// Thread ID that owns this TLAB.
    pub thread_id: u32,
    /// Base address of the TLAB.
    pub base: u64,
    /// Current allocation cursor.
    pub cursor: Arc<Mutex<u64>>,
    /// End of the TLAB (exclusive).
    pub limit: u64,
    /// Number of times this TLAB has been refilled.
    pub refill_count: u64,
    /// Total bytes allocated from this TLAB.
    pub bytes_allocated: u64,
    /// Whether the TLAB is active.
    pub is_active: bool,
}

impl X86GCTLAB {
    /// Create a new TLAB.
    pub fn new(thread_id: u32, base: u64, size: u64) -> Self {
        X86GCTLAB {
            thread_id,
            base,
            cursor: Arc::new(Mutex::new(base)),
            limit: base + size,
            refill_count: 0,
            bytes_allocated: 0,
            is_active: true,
        }
    }

    /// Fast-path allocation from this TLAB.
    pub fn allocate_fast(&mut self, size: u64) -> u64 {
        let aligned = (size + 7) & !7;
        let mut cursor = self.cursor.lock().unwrap();
        let new_cursor = (*cursor).wrapping_add(aligned);

        if new_cursor <= self.limit {
            let result = *cursor;
            *cursor = new_cursor;
            self.bytes_allocated += aligned;
            result
        } else {
            0 // Need refill
        }
    }

    /// Refill the TLAB with a new buffer.
    pub fn refill(&mut self, new_base: u64, new_size: u64) {
        self.base = new_base;
        *self.cursor.lock().unwrap() = new_base;
        self.limit = new_base + new_size;
        self.refill_count += 1;
        self.is_active = true;
    }

    /// Retire the TLAB (return remaining space to the global pool).
    pub fn retire(&mut self) {
        self.is_active = false;
    }

    /// Remaining bytes in this TLAB.
    pub fn remaining(&self) -> u64 {
        let cursor = *self.cursor.lock().unwrap();
        self.limit.saturating_sub(cursor)
    }

    /// Check if the TLAB needs refilling.
    pub fn needs_refill(&self, size: u64) -> bool {
        self.remaining() < size
    }
}

/// Large object allocator — allocates objects above threshold directly
/// from the OS (via mmap/munmap) or from a dedicated large-object space.
#[derive(Debug, Clone)]
pub struct X86GCLargeObjectAllocator {
    /// Map from address to size for large objects.
    pub allocations: HashMap<u64, u64>,
    /// Total bytes in large objects.
    pub total_bytes: u64,
    /// Allocation count.
    pub count: u64,
    /// Minimum size for large-object allocation.
    pub threshold: u64,
}

impl X86GCLargeObjectAllocator {
    /// Create a new large-object allocator.
    pub fn new(threshold: u64) -> Self {
        X86GCLargeObjectAllocator {
            allocations: HashMap::new(),
            total_bytes: 0,
            count: 0,
            threshold,
        }
    }

    /// Allocate a large object (simulated — in real implementation, calls mmap).
    pub fn allocate(&mut self, size: u64) -> u64 {
        if size < self.threshold {
            return 0; // Use normal allocation
        }

        // Simulate mmap allocation — in production, this would call the OS.
        // We use a simple monotonic counter for deterministic addresses.
        let addr = 0x7F00_0000_0000u64 + self.total_bytes;
        self.allocations.insert(addr, size);
        self.total_bytes += size;
        self.count += 1;
        addr
    }

    /// Free a large object.
    pub fn free(&mut self, address: u64) -> bool {
        if let Some(size) = self.allocations.remove(&address) {
            self.total_bytes -= size;
            self.count -= 1;
            true
        } else {
            false
        }
    }

    /// Check if an address is within a known large object.
    pub fn contains(&self, address: u64) -> bool {
        self.allocations
            .iter()
            .any(|(&base, &size)| address >= base && address < base + size)
    }

    /// Get the base address and size for an interior pointer.
    pub fn find_enclosing_object(&self, address: u64) -> Option<(u64, u64)> {
        self.allocations
            .iter()
            .find(|&(&base, &size)| address >= base && address < base + size)
            .map(|(&base, &size)| (base, size))
    }
}

// ============================================================================
// X86GCCollector — Collection algorithms
// ============================================================================

/// A mark-sweep garbage collector.
///
/// Mark phase: traces all live objects from roots — sets a mark bit.
/// Sweep phase: scans the entire heap, reclaiming unmarked objects.
#[derive(Debug, Clone)]
pub struct X86GCMarkSweepCollector {
    /// Base address of the managed heap.
    pub heap_base: u64,
    /// Total size of the managed heap.
    pub heap_size: u64,
    /// Free list for reclaimed objects.
    pub free_list: Vec<X86GCCollectorFreeBlock>,
    /// Mark bits — one bit per allocation unit.
    pub mark_bits: Vec<u64>,
    /// Mapping from object address to object size.
    pub object_sizes: HashMap<u64, u64>,
    /// Total objects allocated.
    pub object_count: u64,
    /// Total bytes allocated.
    pub bytes_allocated: u64,
    /// Bytes freed in last collection.
    pub bytes_freed_last: u64,
    /// Total collections performed.
    pub collections: u64,
    /// Mark stack for DFS/BFS traversal.
    pub mark_stack: Vec<u64>,
    /// Whether collection is in progress.
    pub collecting: bool,
}

/// A free block returned to the free list after sweeping.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCCollectorFreeBlock {
    pub address: u64,
    pub size: u64,
}

impl X86GCMarkSweepCollector {
    /// Create a new mark-sweep collector.
    pub fn new(heap_base: u64, heap_size: u64) -> Self {
        let allocation_units = (heap_size / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
        let mark_words = (allocation_units + 63) / 64;

        X86GCMarkSweepCollector {
            heap_base,
            heap_size,
            free_list: Vec::new(),
            mark_bits: vec![0; mark_words],
            object_sizes: HashMap::new(),
            object_count: 0,
            bytes_allocated: 0,
            bytes_freed_last: 0,
            collections: 0,
            mark_stack: Vec::new(),
            collecting: false,
        }
    }

    /// Allocate an object (using free list or bump from heap end).
    pub fn allocate(&mut self, size: u64) -> u64 {
        let aligned_size =
            (size + X86_GC_OBJECT_ALIGNMENT as u64 - 1) & !(X86_GC_OBJECT_ALIGNMENT as u64 - 1);

        // Try free list first
        if let Some(pos) = self.free_list.iter().position(|b| b.size >= aligned_size) {
            let block = self.free_list.remove(pos);
            if block.size > aligned_size {
                self.free_list.push(X86GCCollectorFreeBlock {
                    address: block.address + aligned_size,
                    size: block.size - aligned_size,
                });
            }
            self.object_sizes.insert(block.address, aligned_size);
            self.object_count += 1;
            self.bytes_allocated += aligned_size;
            return block.address;
        }

        // Bump-allocate from end of heap (simplified — in practice there's a cursor)
        0
    }

    /// Set the mark bit for an object.
    pub fn set_mark(&mut self, address: u64) {
        let offset = address.saturating_sub(self.heap_base);
        if offset < self.heap_size {
            let unit_index = (offset / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
            let word_idx = unit_index / 64;
            let bit_idx = unit_index % 64;
            if word_idx < self.mark_bits.len() {
                self.mark_bits[word_idx] |= 1u64 << bit_idx;
            }
        }
    }

    /// Check if an object is marked.
    pub fn is_marked(&self, address: u64) -> bool {
        let offset = address.saturating_sub(self.heap_base);
        if offset < self.heap_size {
            let unit_index = (offset / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
            let word_idx = unit_index / 64;
            let bit_idx = unit_index % 64;
            if word_idx < self.mark_bits.len() {
                return (self.mark_bits[word_idx] & (1u64 << bit_idx)) != 0;
            }
        }
        false
    }

    /// Mark phase: trace all roots and mark reachable objects.
    pub fn mark_phase(&mut self, roots: &[X86GCRoot]) {
        self.collecting = true;

        // Initialize mark stack with root values (in reality, dereference roots)
        for root in roots {
            if root.is_live {
                // In a real implementation, we'd read the root's value from
                // the stack/register and push it to the mark stack.
                // Here we simulate by marking known addresses.
                self.mark_stack.push(self.heap_base); // Simplified
            }
        }

        // Transitive closure
        while let Some(obj_addr) = self.mark_stack.pop() {
            if self.is_marked(obj_addr) {
                continue;
            }
            self.set_mark(obj_addr);

            // Scan object for pointer fields (in real GC, use type metadata)
            if let Some(&obj_size) = self.object_sizes.get(&obj_addr) {
                let num_fields = obj_size / 8;
                for i in 0..num_fields {
                    let field_addr = obj_addr + i * 8;
                    // In real GC: read field value, check if it's a heap pointer
                    // self.mark_stack.push(field_value);
                    let _ = field_addr;
                }
            }
        }

        self.collecting = false;
        self.collections += 1;
    }

    /// Sweep phase: reclaim unmarked objects.
    pub fn sweep_phase(&mut self) -> u64 {
        let mut freed_bytes = 0u64;
        let mut to_free: Vec<u64> = Vec::new();

        for (&addr, &size) in &self.object_sizes {
            if !self.is_marked(addr) {
                self.free_list.push(X86GCCollectorFreeBlock {
                    address: addr,
                    size,
                });
                freed_bytes += size;
                to_free.push(addr);
            }
        }

        let to_free_len = to_free.len() as u64;
        for addr in to_free {
            self.object_sizes.remove(&addr);
        }

        // Clear mark bits for next collection
        for word in &mut self.mark_bits {
            *word = 0;
        }

        self.bytes_freed_last = freed_bytes;
        self.object_count -= to_free_len;
        freed_bytes
    }

    /// Full collection: mark + sweep.
    pub fn collect(&mut self, roots: &[X86GCRoot]) -> u64 {
        self.mark_phase(roots);
        self.sweep_phase()
    }
}

/// A copying (semi-space) garbage collector using Cheney's algorithm.
///
/// The heap is divided into two equal-sized semi-spaces: from-space and
/// to-space. Live objects are copied from from-space to to-space, and
/// all references are updated. After collection, the spaces are flipped.
#[derive(Debug, Clone)]
pub struct X86GCCopyingCollector {
    /// Size of each semi-space in bytes.
    pub semispace_size: u64,
    /// Start address of from-space.
    pub fromspace_base: u64,
    /// Start address of to-space.
    pub tospace_base: u64,
    /// Current allocation pointer in the active semi-space (now to-space after flip).
    pub free: u64,
    /// Scanning pointer for Cheney scan.
    pub scan: u64,
    /// Whether the collector is in collection mode.
    pub collecting: bool,
    /// Total bytes allocated.
    pub bytes_allocated: u64,
    /// Bytes copied in last collection.
    pub bytes_copied_last: u64,
    /// Total collections.
    pub collections: u64,
    /// Object forwarding map (old address → new address).
    pub forwarding: HashMap<u64, u64>,
}

impl X86GCCopyingCollector {
    /// Create a new copying collector with two semi-spaces.
    pub fn new(fromspace_base: u64, tospace_base: u64, semispace_size: u64) -> Self {
        X86GCCopyingCollector {
            semispace_size,
            fromspace_base,
            tospace_base,
            free: fromspace_base, // Start allocating in fromspace
            scan: fromspace_base,
            collecting: false,
            bytes_allocated: 0,
            bytes_copied_last: 0,
            collections: 0,
            forwarding: HashMap::new(),
        }
    }

    /// Fast-path allocation in the active semi-space.
    pub fn allocate_fast(&mut self, size: u64) -> u64 {
        let aligned = (size + 7) & !7;
        let new_free = self.free.wrapping_add(aligned);
        if new_free <= self.fromspace_base + self.semispace_size {
            let result = self.free;
            self.free = new_free;
            self.bytes_allocated += aligned;
            result
        } else {
            0 // GC needed
        }
    }

    /// Forward an object: if already forwarded, return new address.
    /// Otherwise, copy to to-space and record forwarding.
    pub fn forward(&mut self, addr: u64, size: u64) -> u64 {
        if let Some(&new_addr) = self.forwarding.get(&addr) {
            return new_addr;
        }

        let aligned = (size + 7) & !7;
        let new_addr = self.free;
        self.free = self.free.wrapping_add(aligned);

        // In real implementation: memcpy(new_addr, addr, size)
        self.forwarding.insert(addr, new_addr);
        self.bytes_copied_last += aligned;

        new_addr
    }

    /// Cheney scan: breadth-first traversal of the to-space.
    pub fn cheney_scan(&mut self, roots: &[u64]) {
        self.scan = self.tospace_base;

        // Initialize scan queue with roots
        for &root_addr in roots {
            // In real GC, forward root objects
            let new_addr = self.forward(root_addr, 64); // Estimated size
                                                        // Write back the forwarded address to the root
            let _ = new_addr;
        }

        // Cheney scan loop
        while self.scan < self.free {
            // Read object at scan pointer, scan its fields
            // For each pointer field:
            //   if points to fromspace: forward and update
            // Move scan forward by object size
            self.scan += 64; // Simplified — would use actual object size
        }
    }

    /// Perform a full collection: flip semi-spaces and copy live objects.
    pub fn collect(&mut self, roots: &[u64]) -> u64 {
        self.collecting = true;
        self.bytes_copied_last = 0;

        // Flip: to-space becomes the new from-space
        std::mem::swap(&mut self.fromspace_base, &mut self.tospace_base);
        self.free = self.tospace_base;
        self.forwarding.clear();

        // Copy live objects via Cheney scan
        self.cheney_scan(roots);

        self.collecting = false;
        self.collections += 1;
        self.bytes_copied_last
    }
}

/// A generational garbage collector with nursery and old generation.
///
/// Most objects die young (the "weak generational hypothesis"). The nursery
/// is collected frequently (minor GC). Objects that survive several minor
/// collections are promoted ("tenured") to the old generation.
/// The old generation is collected less frequently (major GC).
#[derive(Debug, Clone)]
pub struct X86GCGenerationalCollector {
    /// Nursery (young generation) base address.
    pub nursery_base: u64,
    /// Nursery size in bytes.
    pub nursery_size: u64,
    /// Nursery allocation cursor.
    pub nursery_free: u64,
    /// Remembered set: old-generation objects that may contain references
    /// into the nursery.
    pub remembered_set: HashSet<u64>,
    /// Old-generation mark-sweep collector.
    pub old_collector: X86GCMarkSweepCollector,
    /// Number of minor collections.
    pub minor_collections: u64,
    /// Number of major collections.
    pub major_collections: u64,
    /// Objects promoted in the last minor GC.
    pub promoted_last: u64,
    /// Promotion threshold: number of minor GCs an object must survive.
    pub promote_threshold: u32,
    /// Object ages (address → number of collections survived).
    pub object_ages: HashMap<u64, u32>,
    /// Total bytes promoted.
    pub total_bytes_promoted: u64,
}

impl X86GCGenerationalCollector {
    /// Create a new generational collector.
    pub fn new(
        nursery_base: u64,
        nursery_size: u64,
        old_heap_base: u64,
        old_heap_size: u64,
    ) -> Self {
        X86GCGenerationalCollector {
            nursery_base,
            nursery_size,
            nursery_free: nursery_base,
            remembered_set: HashSet::new(),
            old_collector: X86GCMarkSweepCollector::new(old_heap_base, old_heap_size),
            minor_collections: 0,
            major_collections: 0,
            promoted_last: 0,
            promote_threshold: 3,
            object_ages: HashMap::new(),
            total_bytes_promoted: 0,
        }
    }

    /// Fast-path nursery allocation.
    pub fn nursery_allocate(&mut self, size: u64) -> u64 {
        let aligned = (size + 7) & !7;
        let new_free = self.nursery_free.wrapping_add(aligned);
        if new_free <= self.nursery_base + self.nursery_size {
            let result = self.nursery_free;
            self.nursery_free = new_free;
            result
        } else {
            0 // Minor GC needed
        }
    }

    /// Record a write from the old generation into the nursery.
    pub fn record_write(&mut self, old_gen_address: u64) {
        if old_gen_address < self.nursery_base
            || old_gen_address >= self.nursery_base + self.nursery_size
        {
            self.remembered_set.insert(old_gen_address);
        }
    }

    /// Perform a minor (nursery) collection.
    pub fn minor_collect(&mut self, roots: &[X86GCRoot], _root_values: &[u64]) {
        self.minor_collections += 1;
        self.promoted_last = 0;

        // Roots for minor GC include:
        // 1. Stack roots (provided)
        // 2. Remembered set entries (old-gen objects pointing into nursery)

        // For each root and remembered set entry, trace through nursery objects.
        // Objects that have survived enough collections get promoted.

        for (&old_obj, age) in self.object_ages.iter_mut() {
            if old_obj < self.nursery_base || old_obj >= self.nursery_base + self.nursery_size {
                *age += 1;
                if *age >= self.promote_threshold {
                    // Promote to old generation
                    let _obj_size = 64u64; // Would get actual size from metadata
                    self.total_bytes_promoted += 64;
                    self.promoted_last += 1;
                }
            }
        }

        // Reset nursery
        self.nursery_free = self.nursery_base;
    }

    /// Perform a major (full heap) collection.
    pub fn major_collect(&mut self, roots: &[X86GCRoot]) -> u64 {
        self.major_collections += 1;
        self.old_collector.collect(roots)
    }

    /// Combined collection: minor GC, then major if needed.
    pub fn collect(&mut self, roots: &[X86GCRoot], root_values: &[u64]) {
        self.minor_collect(roots, root_values);

        // Check if old generation needs collection
        let occupancy =
            self.old_collector.bytes_allocated as f64 / self.old_collector.heap_size as f64;
        if occupancy > X86_GC_MIN_HEAP_OCCUPANCY {
            self.major_collect(roots);
        }
    }
}

/// An incremental/concurrent garbage collector using tri-color marking.
///
/// Objects are classified as:
/// - White: not yet visited (candidate for reclamation)
/// - Gray: visited but children not yet scanned (in mark stack)
/// - Black: visited and children scanned (definitely live)
///
/// The write barrier maintains the "no black → white pointer" invariant.
#[derive(Debug, Clone)]
pub struct X86GCIncrementalCollector {
    /// Mark bit table (simplified: byte per allocation unit).
    pub mark_bytes: Vec<u8>,
    /// Mark stack (gray set).
    pub gray_stack: Vec<u64>,
    /// Whether marking is in progress.
    pub marking: bool,
    /// Whether sweeping is in progress.
    pub sweeping: bool,
    /// Sweep cursor for incremental sweep.
    pub sweep_cursor: u64,
    /// Heap bounds.
    pub heap_base: u64,
    pub heap_size: u64,
    /// Collections performed.
    pub collections: u64,
    /// Number of marking steps performed.
    pub marking_steps: u64,
    /// Number of objects marked.
    pub objects_marked: u64,
    /// Write barriers applied during concurrent marking.
    pub write_barriers_applied: u64,
}

/// Tri-color states for objects.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCTriColor {
    White = 0,
    Gray = 1,
    Black = 2,
}

impl X86GCIncrementalCollector {
    /// Create a new incremental collector.
    pub fn new(heap_base: u64, heap_size: u64) -> Self {
        let units = (heap_size / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
        X86GCIncrementalCollector {
            mark_bytes: vec![X86GCTriColor::White as u8; units],
            gray_stack: Vec::new(),
            marking: false,
            sweeping: false,
            sweep_cursor: heap_base,
            heap_base,
            heap_size,
            collections: 0,
            marking_steps: 0,
            objects_marked: 0,
            write_barriers_applied: 0,
        }
    }

    /// Get the color of an object.
    pub fn color(&self, addr: u64) -> X86GCTriColor {
        let offset = addr.saturating_sub(self.heap_base);
        if offset < self.heap_size {
            let unit = (offset / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
            if unit < self.mark_bytes.len() {
                return match self.mark_bytes[unit] {
                    0 => X86GCTriColor::White,
                    1 => X86GCTriColor::Gray,
                    _ => X86GCTriColor::Black,
                };
            }
        }
        X86GCTriColor::White
    }

    /// Set the color of an object.
    pub fn set_color(&mut self, addr: u64, color: X86GCTriColor) {
        let offset = addr.saturating_sub(self.heap_base);
        if offset < self.heap_size {
            let unit = (offset / X86_GC_OBJECT_ALIGNMENT as u64) as usize;
            if unit < self.mark_bytes.len() {
                self.mark_bytes[unit] = color as u8;
            }
        }
    }

    /// Start a marking cycle.
    pub fn start_mark(&mut self, roots: &[u64]) {
        self.marking = true;
        self.sweeping = false;

        // Initialize all objects to white
        for byte in &mut self.mark_bytes {
            *byte = X86GCTriColor::White as u8;
        }

        // Gray the roots
        for &root_ptr in roots {
            self.set_color(root_ptr, X86GCTriColor::Gray);
            self.gray_stack.push(root_ptr);
        }
    }

    /// Perform one step of incremental marking (process a few gray objects).
    /// Returns true if marking is complete.
    pub fn marking_step(&mut self, _scan_n: usize) -> bool {
        if !self.marking {
            return true;
        }

        self.marking_steps += 1;

        // Process up to scan_n gray objects
        for _ in 0..std::cmp::min(10, self.gray_stack.len()) {
            if let Some(obj) = self.gray_stack.pop() {
                // Blacken the object
                self.set_color(obj, X86GCTriColor::Black);
                self.objects_marked += 1;

                // Scan children — for each child pointer:
                //   if white: gray it and push to stack
                // (Simplified — real GC would enumerate pointer fields)
            }
        }

        if self.gray_stack.is_empty() {
            self.marking = false;
            self.sweeping = true;
            self.sweep_cursor = self.heap_base;
            self.collections += 1;
            true
        } else {
            false
        }
    }

    /// Incremental write barrier: when a black object stores a pointer to
    /// a white object during concurrent marking, the white object must
    /// be grayed to preserve the invariant.
    pub fn write_barrier(&mut self, black_obj: u64, white_obj: u64) {
        if self.marking
            && self.color(black_obj) == X86GCTriColor::Black
            && self.color(white_obj) == X86GCTriColor::White
        {
            self.set_color(white_obj, X86GCTriColor::Gray);
            self.gray_stack.push(white_obj);
            self.write_barriers_applied += 1;
        }
    }

    /// Perform one step of incremental sweeping.
    /// Returns true if sweeping is complete.
    pub fn sweeping_step(&mut self) -> bool {
        if !self.sweeping {
            return true;
        }

        let step_size = 64 * 1024; // Sweep 64K per step
        let end = std::cmp::min(
            self.sweep_cursor + step_size,
            self.heap_base + self.heap_size,
        );

        self.sweep_cursor = end;

        if self.sweep_cursor >= self.heap_base + self.heap_size {
            self.sweeping = false;
            true
        } else {
            false
        }
    }
}

// ============================================================================
// X86GCStackMap — Stack map generation and emission
// ============================================================================

/// A stack map record for a single call site or safepoint.
///
/// Maps the locations (registers and stack slots) of live GC pointers
/// at that program point.
#[derive(Debug, Clone)]
pub struct X86GCStackMapRecord {
    /// Unique ID for this record.
    pub id: u64,
    /// Instruction byte offset from function start.
    pub instruction_offset: u64,
    /// Reserved/flags field.
    pub flags: u16,
    /// Locations of live pointer values.
    pub locations: Vec<X86GCStackMapLocation>,
    /// Live-out registers (values live after the call).
    pub live_outs: Vec<X86GCStackMapLiveOut>,
    /// Function index this record belongs to.
    pub function_index: u32,
}

/// A location record within a stack map — describes where a live pointer
/// value resides.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCStackMapLocation {
    /// Location kind (register, direct stack, indirect, constant, etc.)
    pub kind: X86GCStackMapLocationKind,
    /// DWARF register number (for register locations).
    pub dwarf_reg: u16,
    /// Offset (for stack locations — frame offset; for constants — index).
    pub offset: i32,
    /// Size of the location in bytes.
    pub size: u16,
    /// Reserved for future use.
    pub reserved: u16,
}

/// The kind of location in a stack map record.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCStackMapLocationKind {
    /// Value is in a register.
    Register = 1,
    /// Value is at a direct address (RBP/RSP + offset).
    Direct = 2,
    /// Value is at an indirect address ([reg + offset]).
    Indirect = 3,
    /// Value is a known constant.
    Constant = 4,
    /// Value is a constant from the constant pool.
    ConstantIndex = 5,
}

impl X86GCStackMapLocationKind {
    /// Convert from the byte value in the stack map format.
    pub fn from_u8(value: u8) -> Option<Self> {
        match value {
            1 => Some(X86GCStackMapLocationKind::Register),
            2 => Some(X86GCStackMapLocationKind::Direct),
            3 => Some(X86GCStackMapLocationKind::Indirect),
            4 => Some(X86GCStackMapLocationKind::Constant),
            5 => Some(X86GCStackMapLocationKind::ConstantIndex),
            _ => None,
        }
    }

    /// Convert to the byte value for serialization.
    pub fn to_u8(self) -> u8 {
        self as u8
    }
}

impl X86GCStackMapLocation {
    /// Create a register location.
    pub fn new_register(dwarf_reg: u16, size: u16) -> Self {
        X86GCStackMapLocation {
            kind: X86GCStackMapLocationKind::Register,
            dwarf_reg,
            offset: 0,
            size,
            reserved: 0,
        }
    }

    /// Create a direct (stack-based) location.
    pub fn new_direct(frame_offset: i32, size: u16) -> Self {
        X86GCStackMapLocation {
            kind: X86GCStackMapLocationKind::Direct,
            dwarf_reg: 0,
            offset: frame_offset,
            size,
            reserved: 0,
        }
    }

    /// Create an indirect location.
    pub fn new_indirect(dwarf_reg: u16, offset: i32, size: u16) -> Self {
        X86GCStackMapLocation {
            kind: X86GCStackMapLocationKind::Indirect,
            dwarf_reg,
            offset,
            size,
            reserved: 0,
        }
    }

    /// Create a constant location.
    pub fn new_constant(value: i32) -> Self {
        X86GCStackMapLocation {
            kind: X86GCStackMapLocationKind::Constant,
            dwarf_reg: 0,
            offset: value,
            size: 8,
            reserved: 0,
        }
    }

    /// Create a constant-index location.
    pub fn new_constant_index(index: i32, size: u16) -> Self {
        X86GCStackMapLocation {
            kind: X86GCStackMapLocationKind::ConstantIndex,
            dwarf_reg: 0,
            offset: index,
            size,
            reserved: 0,
        }
    }
}

/// A live-out register entry in a stack map.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCStackMapLiveOut {
    /// DWARF register number.
    pub dwarf_reg: u16,
    /// Reserved.
    pub reserved: u8,
    /// Size in bytes.
    pub size: u8,
}

impl X86GCStackMapLiveOut {
    pub fn new(dwarf_reg: u16, size: u8) -> Self {
        X86GCStackMapLiveOut {
            dwarf_reg,
            reserved: 0,
            size,
        }
    }
}

/// Complete X86 stack map — represents the `.llvm_stackmaps` section content.
#[derive(Debug, Clone)]
pub struct X86GCStackMap {
    /// Version (3 for LLVM 3.x+ format).
    pub version: u8,
    /// Reserved bytes.
    pub reserved1: u8,
    pub reserved2: u16,
    /// Function records.
    pub functions: Vec<X86GCStackMapFunction>,
    /// Constant pool entries.
    pub constants: Vec<u64>,
    /// Stack map records (call sites / safepoints).
    pub records: Vec<X86GCStackMapRecord>,
    /// Function index to record mapping.
    pub func_to_records: HashMap<u32, Vec<usize>>,
}

/// A function entry in the stack map.
#[derive(Debug, Clone)]
pub struct X86GCStackMapFunction {
    /// Function address (absolute or section-relative).
    pub function_address: u64,
    /// Stack size for this function.
    pub stack_size: u64,
    /// Number of stack map records for this function.
    pub record_count: u64,
    /// Stack size records (one per call site, or none).
    pub stack_sizes: Vec<X86GCStackSizeRecord>,
}

/// A stack-size record — maps a function offset to a modified stack size.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCStackSizeRecord {
    /// Function byte offset.
    pub function_offset: u64,
    /// Stack size at this offset.
    pub stack_size: u64,
}

impl X86GCStackMapFunction {
    /// Create a new function record.
    pub fn new(function_address: u64, stack_size: u64) -> Self {
        X86GCStackMapFunction {
            function_address,
            stack_size,
            record_count: 0,
            stack_sizes: Vec::new(),
        }
    }

    /// Add a stack size record.
    pub fn add_stack_size(&mut self, offset: u64, size: u64) {
        self.stack_sizes.push(X86GCStackSizeRecord {
            function_offset: offset,
            stack_size: size,
        });
    }

    /// Increment the record count.
    pub fn increment_records(&mut self) {
        self.record_count += 1;
    }
}

impl X86GCStackMap {
    /// Create a new empty stack map.
    pub fn new() -> Self {
        X86GCStackMap {
            version: X86_GC_STACK_MAP_VERSION,
            reserved1: 0,
            reserved2: 0,
            functions: Vec::new(),
            constants: Vec::new(),
            records: Vec::new(),
            func_to_records: HashMap::new(),
        }
    }

    /// Add a function entry.
    pub fn add_function(&mut self, address: u64, stack_size: u64) -> u32 {
        let idx = self.functions.len() as u32;
        self.functions
            .push(X86GCStackMapFunction::new(address, stack_size));
        idx
    }

    /// Add a constant to the pool.
    pub fn add_constant(&mut self, value: u64) -> u32 {
        let idx = self.constants.len() as u32;
        self.constants.push(value);
        idx
    }

    /// Add a stack map record.
    pub fn add_record(&mut self, record: X86GCStackMapRecord, function_index: u32) {
        let record_index = self.records.len();
        if let Some(func) = self.functions.get_mut(function_index as usize) {
            func.increment_records();
        }
        self.func_to_records
            .entry(function_index)
            .or_insert_with(Vec::new)
            .push(record_index);
        self.records.push(record);
    }

    /// Get records for a function.
    pub fn get_function_records(&self, function_index: u32) -> Option<&[usize]> {
        self.func_to_records
            .get(&function_index)
            .map(|v| v.as_slice())
    }

    /// Total number of records.
    pub fn record_count(&self) -> usize {
        self.records.len()
    }

    /// Total number of location entries.
    pub fn location_count(&self) -> usize {
        self.records.iter().map(|r| r.locations.len()).sum()
    }

    /// Emit the stack map as bytes (LLVM binary format).
    pub fn emit_bytes(&self) -> Vec<u8> {
        let mut buf = Vec::with_capacity(4096);

        // Header
        buf.push(self.version);
        buf.push(self.reserved1);
        buf.extend_from_slice(&self.reserved2.to_le_bytes());

        // Number of functions
        buf.extend_from_slice(&(self.functions.len() as u32).to_le_bytes());
        // Number of constants
        buf.extend_from_slice(&(self.constants.len() as u32).to_le_bytes());
        // Number of records
        buf.extend_from_slice(&(self.records.len() as u32).to_le_bytes());

        // Function records
        for func in &self.functions {
            buf.extend_from_slice(&func.function_address.to_le_bytes());
            buf.extend_from_slice(&func.stack_size.to_le_bytes());
            buf.extend_from_slice(&func.record_count.to_le_bytes());
        }

        // Constants
        for &c in &self.constants {
            buf.extend_from_slice(&c.to_le_bytes());
        }

        // Records
        for record in &self.records {
            buf.extend_from_slice(&record.id.to_le_bytes());
            buf.extend_from_slice(&record.instruction_offset.to_le_bytes());
            buf.extend_from_slice(&record.flags.to_le_bytes());
            buf.extend_from_slice(&(record.locations.len() as u16).to_le_bytes());

            // Padding for alignment of live-out count
            buf.extend_from_slice(&[0u8; 2]);

            buf.extend_from_slice(&(record.live_outs.len() as u16).to_le_bytes());

            // Locations
            for loc in &record.locations {
                buf.push(loc.kind.to_u8());
                buf.push(0); // reserved
                buf.extend_from_slice(&loc.size.to_le_bytes());
                buf.extend_from_slice(&loc.dwarf_reg.to_le_bytes());
                buf.extend_from_slice(&loc.reserved.to_le_bytes());
                buf.extend_from_slice(&loc.offset.to_le_bytes());
            }

            // Padding for alignment
            let padding = (8 - (record.locations.len() * 3) % 8) % 8;
            for _ in 0..padding {
                buf.push(0);
            }

            // Live-outs
            for lo in &record.live_outs {
                buf.extend_from_slice(&lo.dwarf_reg.to_le_bytes());
                buf.push(lo.reserved);
                buf.push(lo.size);
            }

            // Padding for 8-byte alignment
            let lo_padding = (8 - (record.live_outs.len() * 4) % 8) % 8;
            for _ in 0..lo_padding {
                buf.push(0);
            }
        }

        buf
    }

    /// Emit the stack map as assembly text (for `.llvm_stackmaps` section).
    pub fn emit_assembly(&self) -> String {
        let mut s = String::new();
        s.push_str(&format!("\t.section {},\n", X86_GC_STACK_MAP_SECTION));
        s.push_str(&format!("\t.byte {}\t# version\n", self.version));
        s.push_str(&format!("\t.byte {}\t# reserved\n", self.reserved1));
        s.push_str(&format!("\t.short {}\t# reserved\n", self.reserved2));
        s.push_str(&format!(
            "\t.long {}\t# num_functions\n",
            self.functions.len()
        ));
        s.push_str(&format!(
            "\t.long {}\t# num_constants\n",
            self.constants.len()
        ));
        s.push_str(&format!(
            "\t.long {}\t# num_records\n\n",
            self.records.len()
        ));

        for (i, func) in self.functions.iter().enumerate() {
            s.push_str(&format!("\t# Function {}\n", i));
            s.push_str(&format!(
                "\t.quad {}\t# function_address\n",
                func.function_address
            ));
            s.push_str(&format!("\t.quad {}\t# stack_size\n", func.stack_size));
            s.push_str(&format!("\t.quad {}\t# record_count\n", func.record_count));
        }

        s
    }
}

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

// ============================================================================
// X86GCStackMapGenerator — generates stack maps from function data
// ============================================================================

/// Generates stack maps for a function by tracking live pointer locations
/// and emitting location records at safepoint/call sites.
#[derive(Debug, Clone)]
pub struct X86GCStackMapGenerator {
    /// The stack map being built.
    pub stack_map: X86GCStackMap,
    /// Current function index.
    pub current_function_index: Option<u32>,
    /// Current function name.
    pub current_function_name: Option<String>,
    /// Live variable state at the current point.
    pub live_var_state: X86GCLiveVarState,
    /// Current instruction offset.
    pub current_offset: u64,
    /// Current frame size.
    pub current_frame_size: u64,
    /// Map from register dwarf number to name.
    pub reg_names: HashMap<u16, String>,
    /// Next unique record ID.
    pub next_id: u64,
}

/// Live variable state tracking for stack map generation.
#[derive(Debug, Clone)]
pub struct X86GCLiveVarState {
    /// Map from variable name to current location.
    pub var_locations: HashMap<String, X86GCStackMapLocation>,
    /// Map from variable name to type.
    pub var_types: HashMap<String, String>,
    /// Set of variable names that are GC pointers.
    pub gc_pointers: HashSet<String>,
    /// Allocated stack slots (offset → size).
    pub stack_slots: BTreeMap<i32, u16>,
    /// Current frame size.
    pub frame_size: u64,
}

impl X86GCLiveVarState {
    /// Create a new live variable state.
    pub fn new(frame_size: u64) -> Self {
        X86GCLiveVarState {
            var_locations: HashMap::new(),
            var_types: HashMap::new(),
            gc_pointers: HashSet::new(),
            stack_slots: BTreeMap::new(),
            frame_size,
        }
    }

    /// Record a register location for a variable.
    pub fn record_register(&mut self, var_name: &str, dwarf_reg: u16, size: u16) {
        self.var_locations.insert(
            var_name.to_string(),
            X86GCStackMapLocation::new_register(dwarf_reg, size),
        );
    }

    /// Record a stack location for a variable.
    pub fn record_stack(&mut self, var_name: &str, frame_offset: i32, size: u16) {
        self.var_locations.insert(
            var_name.to_string(),
            X86GCStackMapLocation::new_direct(frame_offset, size),
        );
        self.stack_slots.insert(frame_offset, size);
    }

    /// Mark a variable as a GC pointer.
    pub fn mark_gc_pointer(&mut self, var_name: &str) {
        self.gc_pointers.insert(var_name.to_string());
    }

    /// Check if a variable is a GC pointer.
    pub fn is_gc_pointer(&self, var_name: &str) -> bool {
        self.gc_pointers.contains(var_name)
    }

    /// Allocate a new stack slot for a variable.
    pub fn allocate_stack_slot(&mut self, var_name: &str, size: u16) -> i32 {
        // Find a free slot in the frame
        let mut offset = -(size as i32);
        loop {
            let mut conflicts = false;
            for (&slot_offset, &slot_size) in &self.stack_slots {
                let slot_end = slot_offset + slot_size as i32;
                let new_end = offset + size as i32;
                if !(new_end <= slot_offset || offset >= slot_end) {
                    conflicts = true;
                    break;
                }
            }
            if !conflicts {
                break;
            }
            offset -= 8; // Try next aligned slot
        }

        self.stack_slots.insert(offset, size);
        self.var_locations.insert(
            var_name.to_string(),
            X86GCStackMapLocation::new_direct(offset, size),
        );
        offset
    }

    /// Get the current location for a variable.
    pub fn get_location(&self, var_name: &str) -> Option<&X86GCStackMapLocation> {
        self.var_locations.get(var_name)
    }

    /// Get all live GC pointer locations.
    pub fn get_gc_pointer_locations(&self) -> Vec<X86GCStackMapLocation> {
        self.gc_pointers
            .iter()
            .filter_map(|name| self.var_locations.get(name).copied())
            .collect()
    }
}

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

impl X86GCStackMapGenerator {
    /// Create a new stack map generator.
    pub fn new() -> Self {
        X86GCStackMapGenerator {
            stack_map: X86GCStackMap::new(),
            current_function_index: None,
            current_function_name: None,
            live_var_state: X86GCLiveVarState::default(),
            current_offset: 0,
            current_frame_size: 0,
            reg_names: HashMap::new(),
            next_id: 1,
        }
    }

    /// Begin processing a new function.
    pub fn begin_function(&mut self, name: &str, address: u64) {
        self.current_function_name = Some(name.to_string());
        self.current_function_index = Some(
            self.stack_map
                .add_function(address, self.current_frame_size),
        );
        self.current_offset = 0;
        self.live_var_state = X86GCLiveVarState::new(self.current_frame_size);
    }

    /// End processing the current function.
    pub fn end_function(&mut self) {
        self.current_function_name = None;
        self.current_function_index = None;
    }

    /// Advance the current instruction offset.
    pub fn advance_offset(&mut self, offset: u64) {
        self.current_offset = offset;
    }

    /// Generate a stack map record at the current location.
    pub fn generate_record(&mut self, is_call: bool) -> u64 {
        let id = self.next_id;
        self.next_id += 1;

        let locations = self.live_var_state.get_gc_pointer_locations();

        let record = X86GCStackMapRecord {
            id,
            instruction_offset: self.current_offset,
            flags: if is_call { 1 } else { 0 },
            locations,
            live_outs: Vec::new(),
            function_index: self.current_function_index.unwrap_or(0),
        };

        if let Some(func_idx) = self.current_function_index {
            self.stack_map.add_record(record, func_idx);
        }

        id
    }

    /// Generate a record for a patchpoint.
    pub fn generate_for_patchpoint(&mut self, pp_id: u64, target: &str) -> u64 {
        let id = self.next_id;
        self.next_id += 1;

        let locations = self.live_var_state.get_gc_pointer_locations();

        let record = X86GCStackMapRecord {
            id,
            instruction_offset: self.current_offset,
            flags: 2, // Patchpoint flag
            locations,
            live_outs: Vec::new(),
            function_index: self.current_function_index.unwrap_or(0),
        };

        let _ = (pp_id, target);
        if let Some(func_idx) = self.current_function_index {
            self.stack_map.add_record(record, func_idx);
        }

        id
    }

    /// Generate a record for a statepoint.
    pub fn generate_for_statepoint(&mut self, sp_id: u64, callee: &str, gc_args: &[&str]) -> u64 {
        let id = self.next_id;
        self.next_id += 1;

        // Get all live GC pointer locations
        let mut locations = self.live_var_state.get_gc_pointer_locations();

        // Add GC args explicitly
        for &arg_name in gc_args {
            if let Some(&loc) = self.live_var_state.get_location(arg_name) {
                locations.push(loc);
            }
        }

        let record = X86GCStackMapRecord {
            id,
            instruction_offset: self.current_offset,
            flags: 4, // Statepoint flag
            locations,
            live_outs: Vec::new(),
            function_index: self.current_function_index.unwrap_or(0),
        };

        let _ = (sp_id, callee);
        if let Some(func_idx) = self.current_function_index {
            self.stack_map.add_record(record, func_idx);
        }

        id
    }

    /// Finalize and return the stack map.
    pub fn finalize(&self) -> X86GCStackMap {
        self.stack_map.clone()
    }

    /// Get the current frame size.
    pub fn frame_size(&self) -> u64 {
        self.current_frame_size
    }

    /// Set the current frame size.
    pub fn set_frame_size(&mut self, size: u64) {
        self.current_frame_size = size;
    }
}

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

// ============================================================================
// X86GCStackMapParser — parses .llvm_stackmaps section
// ============================================================================

/// Parses the binary `.llvm_stackmaps` section and provides lookup APIs.
#[derive(Debug, Clone)]
pub struct X86GCStackMapParser {
    /// The parsed stack map.
    pub stack_map: X86GCStackMap,
    /// Index from record ID to record index.
    pub id_index: HashMap<u64, usize>,
    /// Whether the parse was successful.
    pub parsed: bool,
    /// Parse warnings.
    pub warnings: Vec<String>,
}

impl X86GCStackMapParser {
    /// Create a new parser.
    pub fn new() -> Self {
        X86GCStackMapParser {
            stack_map: X86GCStackMap::new(),
            id_index: HashMap::new(),
            parsed: false,
            warnings: Vec::new(),
        }
    }

    /// Parse binary stack map data.
    pub fn parse(&mut self, data: &[u8]) -> bool {
        if data.len() < 16 {
            self.warnings
                .push("Data too short for stack map header".to_string());
            return false;
        }

        let mut offset = 0;

        // Header
        let version = data[offset];
        offset += 1;
        let reserved1 = data[offset];
        offset += 1;
        let reserved2 = u16::from_le_bytes([data[offset], data[offset + 1]]);
        offset += 2;

        let num_functions = u32::from_le_bytes([
            data[offset],
            data[offset + 1],
            data[offset + 2],
            data[offset + 3],
        ]) as usize;
        offset += 4;

        let num_constants = u32::from_le_bytes([
            data[offset],
            data[offset + 1],
            data[offset + 2],
            data[offset + 3],
        ]) as usize;
        offset += 4;

        let num_records = u32::from_le_bytes([
            data[offset],
            data[offset + 1],
            data[offset + 2],
            data[offset + 3],
        ]) as usize;
        offset += 4;

        self.stack_map.version = version;
        self.stack_map.reserved1 = reserved1;
        self.stack_map.reserved2 = reserved2;

        // Function records (24 bytes each)
        for _ in 0..num_functions {
            if offset + 24 > data.len() {
                self.warnings.push("Truncated function record".to_string());
                return false;
            }
            let addr = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;
            let stack_size = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;
            let record_count = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;

            let mut func = X86GCStackMapFunction::new(addr, stack_size);
            func.record_count = record_count;
            self.stack_map.functions.push(func);
        }

        // Constants (8 bytes each)
        for _ in 0..num_constants {
            if offset + 8 > data.len() {
                self.warnings.push("Truncated constant entry".to_string());
                return false;
            }
            let val = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;
            self.stack_map.constants.push(val);
        }

        // Records — simplified parse (full version would handle variable-length)
        for _ in 0..num_records {
            if offset + 16 > data.len() {
                break;
            }
            let id = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;
            let inst_offset = u64::from_le_bytes([
                data[offset],
                data[offset + 1],
                data[offset + 2],
                data[offset + 3],
                data[offset + 4],
                data[offset + 5],
                data[offset + 6],
                data[offset + 7],
            ]);
            offset += 8;

            let flags = u16::from_le_bytes([data[offset], data[offset + 1]]);
            offset += 2;
            let num_locs = u16::from_le_bytes([data[offset], data[offset + 1]]) as usize;
            offset += 2;
            // Skip padding (4 bytes)
            offset += 4;
            let num_live_outs = u16::from_le_bytes([data[offset], data[offset + 1]]) as usize;
            offset += 2;
            // Skip padding (2 bytes)
            offset += 2;

            let mut locations = Vec::with_capacity(num_locs);
            for _ in 0..num_locs {
                if offset + 12 > data.len() {
                    break;
                }
                let kind = X86GCStackMapLocationKind::from_u8(data[offset])
                    .unwrap_or(X86GCStackMapLocationKind::Register);
                offset += 1;
                let _reserved_loc = data[offset];
                offset += 1;
                let size = u16::from_le_bytes([data[offset], data[offset + 1]]);
                offset += 2;
                let dwarf_reg = u16::from_le_bytes([data[offset], data[offset + 1]]);
                offset += 2;
                let reserved = u16::from_le_bytes([data[offset], data[offset + 1]]);
                offset += 2;
                let loc_offset = i32::from_le_bytes([
                    data[offset],
                    data[offset + 1],
                    data[offset + 2],
                    data[offset + 3],
                ]);
                offset += 4;

                locations.push(X86GCStackMapLocation {
                    kind,
                    dwarf_reg,
                    offset: loc_offset,
                    size,
                    reserved,
                });
            }

            let mut live_outs = Vec::with_capacity(num_live_outs);
            for _ in 0..num_live_outs {
                if offset + 4 > data.len() {
                    break;
                }
                let dwarf_reg = u16::from_le_bytes([data[offset], data[offset + 1]]);
                offset += 2;
                let reserved_lo = data[offset];
                offset += 1;
                let size_lo = data[offset];
                offset += 1;
                live_outs.push(X86GCStackMapLiveOut {
                    dwarf_reg,
                    reserved: reserved_lo,
                    size: size_lo,
                });
            }

            let record_idx = self.stack_map.records.len();
            self.id_index.insert(id, record_idx);

            self.stack_map.records.push(X86GCStackMapRecord {
                id,
                instruction_offset: inst_offset,
                flags,
                locations,
                live_outs,
                function_index: 0,
            });
        }

        self.parsed = true;
        true
    }

    /// Look up a record by its ID.
    pub fn lookup_by_id(&self, id: u64) -> Option<&X86GCStackMapRecord> {
        self.id_index
            .get(&id)
            .and_then(|&idx| self.stack_map.records.get(idx))
    }

    /// Get all record IDs.
    pub fn all_ids(&self) -> Vec<u64> {
        self.id_index.keys().copied().collect()
    }

    /// Number of parsed records.
    pub fn record_count(&self) -> usize {
        self.stack_map.records.len()
    }
}

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

// ============================================================================
// X86GCSafepoints — Safepoint placement and polling
// ============================================================================

/// Manages safepoint insertion and polling for cooperative GC.
#[derive(Debug, Clone)]
pub struct X86GCSafepoints {
    /// Whether safepoint insertion is enabled.
    pub enabled: bool,
    /// The virtual address of the polling page.
    pub polling_page_address: u64,
    /// Size of the polling page.
    pub polling_page_size: u64,
    /// Total safepoints inserted.
    pub safepoint_count: u64,
    /// Whether to insert at function entries.
    pub insert_at_entry: bool,
    /// Whether to insert at loop backedges.
    pub insert_at_backedge: bool,
    /// Whether to insert after call instructions.
    pub insert_after_calls: bool,
    /// Poll only every N backedges.
    pub backedge_frequency: u32,
    /// Safepoint statistics.
    pub stats: X86GCSafepointStats,
    /// Safepoint locations by function.
    pub safepoints: HashMap<String, Vec<X86GCSafepointLocation>>,
}

/// Safepoint insertion statistics.
#[derive(Debug, Clone, Default)]
pub struct X86GCSafepointStats {
    pub entry_safepoints: u64,
    pub backedge_safepoints: u64,
    pub call_safepoints: u64,
    pub statepoint_safepoints: u64,
    pub coop_suspend_points: u64,
    pub exit_safepoints: u64,
}

impl X86GCSafepointStats {
    pub fn total(&self) -> u64 {
        self.entry_safepoints
            + self.backedge_safepoints
            + self.call_safepoints
            + self.statepoint_safepoints
            + self.coop_suspend_points
            + self.exit_safepoints
    }
}

/// A single safepoint location in generated code.
#[derive(Debug, Clone)]
pub struct X86GCSafepointLocation {
    /// Safepoint kind.
    pub kind: X86GCSafepointKind,
    /// Function name.
    pub function_name: String,
    /// Instruction offset from function start.
    pub instruction_offset: u64,
    /// Associated stack map record ID.
    pub stack_map_id: Option<u64>,
    /// Optional machine instruction that implements the poll.
    pub machine_instr: Option<MachineInstr>,
}

/// Safepoint placement kinds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCSafepointKind {
    FunctionEntry,
    LoopBackedge,
    AfterCall,
    Statepoint,
    CooperativeSuspend,
    FunctionExit,
}

impl fmt::Display for X86GCSafepointKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCSafepointKind::FunctionEntry => write!(f, "entry"),
            X86GCSafepointKind::LoopBackedge => write!(f, "backedge"),
            X86GCSafepointKind::AfterCall => write!(f, "after-call"),
            X86GCSafepointKind::Statepoint => write!(f, "statepoint"),
            X86GCSafepointKind::CooperativeSuspend => write!(f, "coop-suspend"),
            X86GCSafepointKind::FunctionExit => write!(f, "exit"),
        }
    }
}

impl X86GCSafepoints {
    /// Create a new safepoint manager.
    pub fn new(polling_page_address: u64) -> Self {
        X86GCSafepoints {
            enabled: true,
            polling_page_address,
            polling_page_size: X86_GC_POLLING_PAGE_SIZE,
            safepoint_count: 0,
            insert_at_entry: true,
            insert_at_backedge: true,
            insert_after_calls: false,
            backedge_frequency: 1,
            stats: X86GCSafepointStats::default(),
            safepoints: HashMap::new(),
        }
    }

    /// Enable or disable safepoint insertion.
    pub fn set_enabled(&mut self, enabled: bool) {
        self.enabled = enabled;
    }

    /// Set the polling page address.
    pub fn set_polling_page(&mut self, address: u64) {
        self.polling_page_address = address;
    }

    /// Configure safepoint insertion rules.
    pub fn configure(
        &mut self,
        insert_at_entry: bool,
        insert_at_backedge: bool,
        insert_after_calls: bool,
        backedge_frequency: u32,
    ) {
        self.insert_at_entry = insert_at_entry;
        self.insert_at_backedge = insert_at_backedge;
        self.insert_after_calls = insert_after_calls;
        self.backedge_frequency = backedge_frequency;
    }

    /// Generate the X86-64 polling sequence.
    ///
    /// The canonical polling sequence loads from the polling page.
    /// When the GC needs to stop the world, it arms the polling page
    /// (makes it inaccessible), causing a page fault on the load.
    ///
    /// ```asm
    /// mov rax, [polling_page_address]
    /// ```
    /// Or using RIP-relative addressing for position-independent code:
    /// ```asm
    /// mov rax, [rip + offset_to_polling_page]
    /// ```
    pub fn generate_poll_bytes(&self) -> Vec<u8> {
        let mut code = Vec::with_capacity(8);

        // MOV RAX, [polling_page_address]
        code.push(0x48); // REX.W
        code.push(0xA1); // MOV RAX, moffs64
        code.extend_from_slice(&self.polling_page_address.to_le_bytes());

        code
    }

    /// Generate arm/disarm page protection instructions.
    /// Arm: make page inaccessible (mprotect).
    /// Disarm: make page readable again.
    pub fn arm_polling_page(&self) {
        // In real implementation: mprotect(polling_page, page_size, PROT_NONE)
    }

    pub fn disarm_polling_page(&self) {
        // In real implementation: mprotect(polling_page, page_size, PROT_READ)
    }

    /// Insert an entry safepoint in a function.
    pub fn insert_entry_safepoint(
        &mut self,
        function_name: &str,
        generator: &mut X86GCStackMapGenerator,
    ) -> Option<u64> {
        if !self.enabled || !self.insert_at_entry {
            return None;
        }

        self.stats.entry_safepoints += 1;
        self.safepoint_count += 1;

        let record_id = generator.generate_record(false);

        self.safepoints
            .entry(function_name.to_string())
            .or_insert_with(Vec::new)
            .push(X86GCSafepointLocation {
                kind: X86GCSafepointKind::FunctionEntry,
                function_name: function_name.to_string(),
                instruction_offset: 0,
                stack_map_id: Some(record_id),
                machine_instr: None,
            });

        Some(record_id)
    }

    /// Insert a backedge safepoint.
    pub fn insert_backedge_safepoint(
        &mut self,
        function_name: &str,
        offset: u64,
        generator: &mut X86GCStackMapGenerator,
    ) -> Option<u64> {
        if !self.enabled || !self.insert_at_backedge {
            return None;
        }

        self.stats.backedge_safepoints += 1;
        self.safepoint_count += 1;

        generator.advance_offset(offset);
        let record_id = generator.generate_record(false);

        self.safepoints
            .entry(function_name.to_string())
            .or_insert_with(Vec::new)
            .push(X86GCSafepointLocation {
                kind: X86GCSafepointKind::LoopBackedge,
                function_name: function_name.to_string(),
                instruction_offset: offset,
                stack_map_id: Some(record_id),
                machine_instr: None,
            });

        Some(record_id)
    }

    /// Insert a call-site safepoint.
    pub fn insert_call_safepoint(
        &mut self,
        function_name: &str,
        offset: u64,
        generator: &mut X86GCStackMapGenerator,
    ) -> Option<u64> {
        if !self.enabled || !self.insert_after_calls {
            return None;
        }

        self.stats.call_safepoints += 1;
        self.safepoint_count += 1;

        generator.advance_offset(offset);
        let record_id = generator.generate_record(true);

        self.safepoints
            .entry(function_name.to_string())
            .or_insert_with(Vec::new)
            .push(X86GCSafepointLocation {
                kind: X86GCSafepointKind::AfterCall,
                function_name: function_name.to_string(),
                instruction_offset: offset,
                stack_map_id: Some(record_id),
                machine_instr: None,
            });

        Some(record_id)
    }

    /// Record a statepoint as a safepoint.
    pub fn record_statepoint(&mut self, function_name: &str, offset: u64, stack_map_id: u64) {
        self.stats.statepoint_safepoints += 1;
        self.safepoint_count += 1;

        self.safepoints
            .entry(function_name.to_string())
            .or_insert_with(Vec::new)
            .push(X86GCSafepointLocation {
                kind: X86GCSafepointKind::Statepoint,
                function_name: function_name.to_string(),
                instruction_offset: offset,
                stack_map_id: Some(stack_map_id),
                machine_instr: None,
            });
    }

    /// Get safepoint statistics.
    pub fn get_stats(&self) -> &X86GCSafepointStats {
        &self.stats
    }

    /// Get all safepoints for a function.
    pub fn get_function_safepoints(
        &self,
        function_name: &str,
    ) -> Option<&[X86GCSafepointLocation]> {
        self.safepoints.get(function_name).map(|v| v.as_slice())
    }

    /// Check if a backedge should have a safepoint (respects frequency).
    pub fn should_insert_backedge(&self, backedge_count: u32) -> bool {
        self.insert_at_backedge && (backedge_count % self.backedge_frequency == 0)
    }

    /// Reset all state.
    pub fn reset(&mut self) {
        self.safepoint_count = 0;
        self.stats = X86GCSafepointStats::default();
        self.safepoints.clear();
    }
}

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

// ============================================================================
// X86GCFinalization — Finalization subsystem
// ============================================================================

/// Types of references that can trigger finalization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCReferenceType {
    /// Strong reference — keeps the object alive.
    Strong,
    /// Weak reference — does not keep the object alive; cleared when
    /// the referent is collected.
    Weak,
    /// Soft reference — cleared only under memory pressure.
    Soft,
    /// Phantom reference — cleared after finalization; used for
    /// post-mortem cleanup.
    Phantom,
    /// Ephemeron — key-value pair where the value is only kept alive
    /// if the key is reachable.
    Ephemeron,
    /// Finalizer reference — the object has a finalizer that must run.
    Finalizer,
}

impl fmt::Display for X86GCReferenceType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCReferenceType::Strong => write!(f, "strong"),
            X86GCReferenceType::Weak => write!(f, "weak"),
            X86GCReferenceType::Soft => write!(f, "soft"),
            X86GCReferenceType::Phantom => write!(f, "phantom"),
            X86GCReferenceType::Ephemeron => write!(f, "ephemeron"),
            X86GCReferenceType::Finalizer => write!(f, "finalizer"),
        }
    }
}

/// A finalizable object entry.
#[derive(Debug, Clone)]
pub struct X86GCFinalizerEntry {
    /// Object address.
    pub object_address: u64,
    /// Object type name (for debugging).
    pub type_name: Option<String>,
    /// The finalizer function address.
    pub finalizer_address: u64,
    /// Whether the finalizer has been registered.
    pub registered: bool,
    /// Whether the finalizer has been run.
    pub finalized: bool,
    /// Queue priority (lower = higher priority).
    pub priority: u32,
    /// Generation in which this finalizer was registered.
    pub generation: u64,
}

/// A weak reference entry.
#[derive(Debug, Clone)]
pub struct X86GCWeakReference {
    /// The weak reference object address (the reference itself, not the referent).
    pub reference_address: u64,
    /// The referent address (the object this weak reference points to).
    pub referent_address: u64,
    /// Whether the referent has been cleared.
    pub cleared: bool,
    /// Whether a notification should be sent when cleared.
    pub notify_on_clear: bool,
}

/// A phantom reference entry.
#[derive(Debug, Clone)]
pub struct X86GCPhantomReference {
    /// The phantom reference object address.
    pub reference_address: u64,
    /// The referent address.
    pub referent_address: u64,
    /// Whether the referent has been cleared.
    pub cleared: bool,
    /// Whether the finalizer has been run.
    pub finalized: bool,
}

/// An ephemeron entry — a key-value pair where the value is only
/// reachable if the key is reachable.
#[derive(Debug, Clone)]
pub struct X86GCEphemeron {
    /// The key object address.
    pub key_address: u64,
    /// The value object address.
    pub value_address: u64,
    /// Whether the key is reachable.
    pub key_reachable: bool,
    /// Whether the value has been cleared.
    pub value_cleared: bool,
}

/// Complete finalization subsystem.
#[derive(Debug, Clone)]
pub struct X86GCFinalization {
    /// Queue of objects with pending finalizers.
    pub finalizer_queue: VecDeque<X86GCFinalizerEntry>,
    /// Set of objects that have been finalized (avoid double-finalization).
    pub finalized_objects: HashSet<u64>,
    /// Weak reference table.
    pub weak_references: HashMap<u64, X86GCWeakReference>,
    /// Phantom reference table.
    pub phantom_references: HashMap<u64, X86GCPhantomReference>,
    /// Ephemeron table.
    pub ephemerons: Vec<X86GCEphemeron>,
    /// Whether finalization processing is enabled.
    pub enabled: bool,
    /// Total finalizers run.
    pub total_finalizers_run: u64,
    /// Total weak references cleared.
    pub total_weak_cleared: u64,
    /// Total phantom references processed.
    pub total_phantom_processed: u64,
    /// Total ephemerons cleared.
    pub total_ephemerons_cleared: u64,
}

impl X86GCFinalization {
    /// Create a new finalization subsystem.
    pub fn new() -> Self {
        X86GCFinalization {
            finalizer_queue: VecDeque::new(),
            finalized_objects: HashSet::new(),
            weak_references: HashMap::new(),
            phantom_references: HashMap::new(),
            ephemerons: Vec::new(),
            enabled: true,
            total_finalizers_run: 0,
            total_weak_cleared: 0,
            total_phantom_processed: 0,
            total_ephemerons_cleared: 0,
        }
    }

    // --- Finalizer management ---

    /// Register a finalizer for an object.
    pub fn register_finalizer(
        &mut self,
        object_address: u64,
        finalizer_address: u64,
        priority: u32,
    ) {
        self.finalizer_queue.push_back(X86GCFinalizerEntry {
            object_address,
            type_name: None,
            finalizer_address,
            registered: true,
            finalized: false,
            priority,
            generation: 0,
        });
    }

    /// Process pending finalizers (called after a GC cycle).
    /// Processes up to `max_per_cycle` finalizers.
    pub fn process_finalizers(&mut self, max_per_cycle: usize) -> usize {
        if !self.enabled {
            return 0;
        }

        let mut processed = 0;
        let mut remaining = VecDeque::new();

        while let Some(entry) = self.finalizer_queue.pop_front() {
            if processed >= max_per_cycle {
                remaining.push_back(entry);
                continue;
            }

            if self.finalized_objects.contains(&entry.object_address) {
                continue; // Already finalized
            }

            // In real implementation: call finalizer_address(object_address)
            self.finalized_objects.insert(entry.object_address);
            self.total_finalizers_run += 1;
            processed += 1;
        }

        // Re-queue remaining
        self.finalizer_queue.append(&mut remaining);
        processed
    }

    /// Check if an object has a pending finalizer.
    pub fn has_finalizer(&self, object_address: u64) -> bool {
        self.finalizer_queue
            .iter()
            .any(|e| e.object_address == object_address && !e.finalized)
    }

    /// Get the number of pending finalizers.
    pub fn pending_finalizer_count(&self) -> usize {
        self.finalizer_queue.len()
    }

    // --- Weak reference management ---

    /// Register a weak reference.
    pub fn register_weak_reference(
        &mut self,
        reference_address: u64,
        referent_address: u64,
        notify: bool,
    ) {
        self.weak_references.insert(
            reference_address,
            X86GCWeakReference {
                reference_address,
                referent_address,
                cleared: false,
                notify_on_clear: notify,
            },
        );
    }

    /// Process weak references after a GC mark phase.
    /// For each weak reference whose referent is not marked (not live),
    /// clear the reference (set to null) and optionally notify.
    pub fn process_weak_references(&mut self, is_marked: &dyn Fn(u64) -> bool) -> usize {
        if !self.enabled {
            return 0;
        }

        let mut cleared = 0;
        for weak_ref in self.weak_references.values_mut() {
            if !weak_ref.cleared && !is_marked(weak_ref.referent_address) {
                weak_ref.cleared = true;
                // In real implementation: zero out the reference at reference_address
                cleared += 1;
            }
        }

        self.total_weak_cleared += cleared as u64;
        cleared
    }

    /// Get weak references that are still alive (referent is marked).
    pub fn live_weak_references(&self, is_marked: &dyn Fn(u64) -> bool) -> Vec<u64> {
        self.weak_references
            .values()
            .filter(|wr| !wr.cleared && is_marked(wr.referent_address))
            .map(|wr| wr.reference_address)
            .collect()
    }

    // --- Phantom reference management ---

    /// Register a phantom reference.
    pub fn register_phantom_reference(&mut self, reference_address: u64, referent_address: u64) {
        self.phantom_references.insert(
            reference_address,
            X86GCPhantomReference {
                reference_address,
                referent_address,
                cleared: false,
                finalized: false,
            },
        );
    }

    /// Process phantom references.
    /// Phantom references are enqueued for post-mortem cleanup after
    /// the referent's finalizer has run.
    pub fn process_phantom_references(&mut self, is_marked: &dyn Fn(u64) -> bool) -> usize {
        if !self.enabled {
            return 0;
        }

        let mut processed = 0;
        for phantom in self.phantom_references.values_mut() {
            if !phantom.cleared
                && !is_marked(phantom.referent_address)
                && self.finalized_objects.contains(&phantom.referent_address)
            {
                phantom.cleared = true;
                phantom.finalized = true;
                processed += 1;
            }
        }

        self.total_phantom_processed += processed as u64;
        processed
    }

    // --- Ephemeron support ---

    /// Register an ephemeron.
    pub fn register_ephemeron(&mut self, key_address: u64, value_address: u64) {
        self.ephemerons.push(X86GCEphemeron {
            key_address,
            value_address,
            key_reachable: false,
            value_cleared: false,
        });
    }

    /// Process ephemerons after GC marking.
    ///
    /// An ephemeron's value is only kept alive if the key is reachable.
    /// This is a two-pass process:
    /// 1. Determine key reachability
    /// 2. Clear values for unreachable keys
    pub fn process_ephemerons(&mut self, is_marked: &dyn Fn(u64) -> bool) -> usize {
        if !self.enabled {
            return 0;
        }

        let mut cleared = 0;

        // Pass 1: mark key reachability
        for eph in &mut self.ephemerons {
            eph.key_reachable = is_marked(eph.key_address);
        }

        // Pass 2: clear values where key is not reachable
        // (and optionally re-run mark for values of reachable keys)
        for eph in &mut self.ephemerons {
            if !eph.key_reachable && !eph.value_cleared {
                eph.value_cleared = true;
                cleared += 1;
            }
        }

        // For reachable keys, ensure value is also marked
        // (this might require another marking iteration)
        for eph in &self.ephemerons {
            if eph.key_reachable && !is_marked(eph.value_address) {
                // Value should be kept alive — trigger remark
            }
        }

        self.total_ephemerons_cleared += cleared as u64;
        cleared
    }

    /// Clean up processed references to free memory.
    pub fn cleanup(&mut self) {
        // Remove cleared weak references
        self.weak_references.retain(|_, wr| !wr.cleared);

        // Remove finalized phantom references
        self.phantom_references.retain(|_, pr| !pr.finalized);

        // Remove cleared ephemerons
        self.ephemerons.retain(|e| !e.value_cleared);
    }

    /// Reset all state.
    pub fn reset(&mut self) {
        self.finalizer_queue.clear();
        self.finalized_objects.clear();
        self.weak_references.clear();
        self.phantom_references.clear();
        self.ephemerons.clear();
        self.total_finalizers_run = 0;
        self.total_weak_cleared = 0;
        self.total_phantom_processed = 0;
        self.total_ephemerons_cleared = 0;
    }
}

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

// ============================================================================
// X86GCStackWalker — Stack walking for root discovery
// ============================================================================

/// Walks the native call stack to discover GC roots in stack frames.
/// Uses either frame-pointer-based unwinding (fast) or DWARF-based
/// unwinding (precise).
#[derive(Debug, Clone)]
pub struct X86GCStackWalker {
    /// Current stack pointer value.
    pub stack_pointer: u64,
    /// Current frame/base pointer value.
    pub frame_pointer: u64,
    /// Current instruction pointer value.
    pub instruction_pointer: u64,
    /// Stack bounds (lowest valid address).
    pub stack_bottom: u64,
    /// Stack bounds (highest valid address).
    pub stack_top: u64,
    /// Whether to use frame-pointer-based unwinding.
    pub use_frame_pointer: bool,
    /// Whether to fall back to conservative scanning.
    pub fallback_conservative: bool,
    /// Frames discovered during the walk.
    pub frames: Vec<X86GCStackFrame>,
    /// Roots discovered during the walk.
    pub discovered_roots: Vec<X86GCRoot>,
    /// Whether the walk is complete.
    pub walk_complete: bool,
    /// Number of frames walked.
    pub frame_count: u64,
}

/// A single stack frame discovered during stack walking.
#[derive(Debug, Clone)]
pub struct X86GCStackFrame {
    /// Frame index (0 = topmost frame).
    pub index: u64,
    /// Return address (caller's instruction pointer).
    pub return_address: u64,
    /// Frame/base pointer for this frame.
    pub frame_pointer: u64,
    /// Stack pointer at the call site.
    pub stack_pointer: u64,
    /// Frame size in bytes.
    pub frame_size: u64,
    /// Function name (if known).
    pub function_name: Option<String>,
    /// Whether a stack map was found for this frame.
    pub has_stack_map: bool,
    /// Roots in this frame (from stack maps or conservative scan).
    pub frame_roots: Vec<X86GCRoot>,
    /// Whether this is a leaf frame (no calls made).
    pub is_leaf: bool,
}

impl X86GCStackWalker {
    /// Create a new stack walker from current register state.
    pub fn new(rsp: u64, rbp: u64, rip: u64, stack_bottom: u64, stack_top: u64) -> Self {
        X86GCStackWalker {
            stack_pointer: rsp,
            frame_pointer: rbp,
            instruction_pointer: rip,
            stack_bottom,
            stack_top,
            use_frame_pointer: true,
            fallback_conservative: true,
            frames: Vec::new(),
            discovered_roots: Vec::new(),
            walk_complete: false,
            frame_count: 0,
        }
    }

    /// Walk the stack using frame-pointer chains.
    ///
    /// On X86-64, each frame typically looks like:
    /// ```
    /// [higher addresses]
    ///   ... caller's frame ...
    ///   return address          <- [rbp + 8]
    ///   saved rbp               <- [rbp]  (points to previous frame's saved rbp)
    ///   ... local variables ...  <- [rbp - N]
    /// [lower addresses]
    /// ```
    pub fn walk_frames(&mut self) {
        let mut current_rbp = self.frame_pointer;
        let mut frame_idx = 0u64;

        loop {
            // Check that RBP is within stack bounds
            if current_rbp < self.stack_bottom || current_rbp >= self.stack_top {
                break;
            }

            // Read saved RBP from [current_rbp]
            // Read return address from [current_rbp + 8]
            // In a real implementation, we'd read from memory. Here we simulate.

            let frame = X86GCStackFrame {
                index: frame_idx,
                return_address: current_rbp.wrapping_add(8), // Simplified
                frame_pointer: current_rbp,
                stack_pointer: current_rbp,
                frame_size: 0, // Would be computed from stack map or unwind info
                function_name: None,
                has_stack_map: false,
                frame_roots: Vec::new(),
                is_leaf: frame_idx == 0,
            };

            self.frames.push(frame);
            frame_idx += 1;

            // Termination: saved RBP = 0 means top of frame chain
            // For simulation, stop after 100 frames or when RBP doesn't grow
            if frame_idx > 100 {
                break;
            }

            // Advance to caller's frame
            // current_rbp = *(u64*)current_rbp;  // Real: read saved RBP
            current_rbp = current_rbp.wrapping_add(0x40); // Simulated advance

            if current_rbp == 0 {
                break;
            }
        }

        self.frame_count = frame_idx;
        self.walk_complete = true;
    }

    /// Scan a frame for roots using its stack map (precise mode).
    pub fn scan_frame_precise(
        &mut self,
        frame_idx: usize,
        stack_map: &X86GCStackMap,
        function_index: u32,
    ) -> Vec<X86GCRoot> {
        let mut roots = Vec::new();

        if let Some(record_indices) = stack_map.get_function_records(function_index) {
            for &rec_idx in record_indices {
                if let Some(record) = stack_map.records.get(rec_idx) {
                    for loc in &record.locations {
                        let root = match loc.kind {
                            X86GCStackMapLocationKind::Register => {
                                X86GCRoot::new_register((roots.len() + 1) as u32, loc.dwarf_reg)
                            }
                            X86GCStackMapLocationKind::Direct => {
                                X86GCRoot::new_base((roots.len() + 1) as u32, loc.offset)
                            }
                            _ => continue,
                        };
                        roots.push(root);
                    }
                }
            }
        }

        if frame_idx < self.frames.len() {
            self.frames[frame_idx].has_stack_map = true;
            self.frames[frame_idx].frame_roots = roots.clone();
        }

        roots
    }

    /// Conservative scan of a frame: treat every aligned word that looks
    /// like a heap pointer as a potential root.
    pub fn scan_frame_conservative(
        &mut self,
        frame_idx: usize,
        heap_start: u64,
        heap_end: u64,
    ) -> Vec<X86GCRootCandidate> {
        let mut candidates = Vec::new();

        if frame_idx >= self.frames.len() {
            return candidates;
        }

        let frame = &self.frames[frame_idx];
        let frame_start = frame.stack_pointer;
        let frame_end = frame.frame_pointer;

        let mut addr = frame_start & !7u64; // Align to 8 bytes
        let mut root_id = 1u32;

        while addr < frame_end && addr < self.stack_top {
            // In real GC: read the 8-byte value at addr
            // Check: is it within [heap_start, heap_end)?
            // Check: is it properly aligned?
            // Here we generate candidate records for demonstration.

            candidates.push(X86GCRootCandidate {
                raw_value: 0, // Would be *(u64*)addr
                stack_address: addr,
                frame_offset: (addr as i64 - frame.frame_pointer as i64) as i32,
                is_valid_heap_ptr: false, // Would check against heap bounds
                scan_mode: X86GCScanMode::Conservative,
            });

            root_id += 1;
            addr += 8;
        }

        candidates
    }

    /// Combine precise and conservative scanning for a full root set.
    pub fn collect_all_roots(
        &mut self,
        stack_map: Option<&X86GCStackMap>,
        heap_start: u64,
        heap_end: u64,
    ) {
        self.discovered_roots.clear();

        for frame_idx in 0..self.frames.len() {
            if let Some(sm) = stack_map {
                // Try precise scanning first
                let precise_roots = self.scan_frame_precise(frame_idx, sm, 0);
                if !precise_roots.is_empty() {
                    self.discovered_roots.extend(precise_roots);
                    continue;
                }
            }

            // Fall back to conservative scanning
            if self.fallback_conservative {
                let candidates = self.scan_frame_conservative(frame_idx, heap_start, heap_end);
                // In real GC: filter candidates to those that look like valid heap pointers
                let _ = candidates;
            }
        }
    }

    /// Get the total number of frames walked.
    pub fn total_frames(&self) -> u64 {
        self.frame_count
    }

    /// Get roots for a specific frame.
    pub fn frame_roots(&self, frame_idx: usize) -> Option<&[X86GCRoot]> {
        self.frames.get(frame_idx).map(|f| f.frame_roots.as_slice())
    }
}

impl Default for X86GCStackWalker {
    fn default() -> Self {
        X86GCStackWalker::new(0, 0, 0, 0, 0)
    }
}

// ============================================================================
// X86GCMemoryPressure — Memory pressure monitoring and adaptive GC
// ============================================================================

/// Monitors memory pressure and adjusts GC behavior accordingly.
#[derive(Debug, Clone)]
pub struct X86GCMemoryPressure {
    /// Current heap occupancy (bytes allocated).
    pub heap_occupancy: u64,
    /// Maximum heap size.
    pub max_heap_size: u64,
    /// Threshold at which to trigger GC (fraction, 0.0-1.0).
    pub gc_threshold: f64,
    /// Current memory pressure level.
    pub pressure_level: X86GCPressureLevel,
    /// Allocated bytes since last GC.
    pub allocated_since_gc: u64,
    /// Freed bytes since last GC.
    pub freed_since_gc: u64,
    /// Collection statistics.
    pub stats: X86GCMemoryStats,
}

/// Memory pressure levels.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum X86GCPressureLevel {
    /// Plenty of free memory — GC can be lazy.
    Low = 0,
    /// Moderate usage — normal GC scheduling.
    Normal = 1,
    /// High usage — aggressive GC needed.
    High = 2,
    /// Critical — must GC immediately, may OOM.
    Critical = 3,
}

/// Memory statistics for GC tuning.
#[derive(Debug, Clone, Default)]
pub struct X86GCMemoryStats {
    /// Total collections.
    pub total_collections: u64,
    /// Collections triggered by allocation failure.
    pub alloc_failure_collections: u64,
    /// Collections triggered by memory pressure threshold.
    pub threshold_collections: u64,
    /// Time spent in GC (in arbitrary units).
    pub gc_time_units: u64,
    /// Total bytes promoted (generational).
    pub total_bytes_promoted: u64,
    /// Total bytes tenured.
    pub total_bytes_tenured: u64,
    /// Average pause time.
    pub avg_pause_time: f64,
    /// Maximum pause time.
    pub max_pause_time: u64,
    /// Minimum pause time.
    pub min_pause_time: u64,
    /// Fragmentation ratio after last collection.
    pub fragmentation_ratio: f64,
}

impl X86GCMemoryPressure {
    /// Create a new memory pressure monitor.
    pub fn new(max_heap_size: u64) -> Self {
        X86GCMemoryPressure {
            heap_occupancy: 0,
            max_heap_size,
            gc_threshold: X86_GC_MIN_HEAP_OCCUPANCY,
            pressure_level: X86GCPressureLevel::Low,
            allocated_since_gc: 0,
            freed_since_gc: 0,
            stats: X86GCMemoryStats::default(),
        }
    }

    /// Record an allocation.
    pub fn record_allocation(&mut self, size: u64) {
        self.heap_occupancy += size;
        self.allocated_since_gc += size;
        self.update_pressure();
    }

    /// Record a deallocation.
    pub fn record_free(&mut self, size: u64) {
        self.heap_occupancy = self.heap_occupancy.saturating_sub(size);
        self.freed_since_gc += size;
    }

    /// Update the pressure level based on occupancy.
    fn update_pressure(&mut self) {
        let ratio = if self.max_heap_size > 0 {
            self.heap_occupancy as f64 / self.max_heap_size as f64
        } else {
            0.0
        };

        self.pressure_level = if ratio >= 0.95 {
            X86GCPressureLevel::Critical
        } else if ratio >= self.gc_threshold {
            X86GCPressureLevel::High
        } else if ratio >= self.gc_threshold * 0.5 {
            X86GCPressureLevel::Normal
        } else {
            X86GCPressureLevel::Low
        };
    }

    /// Whether a GC should be triggered.
    pub fn should_collect(&self) -> bool {
        self.pressure_level >= X86GCPressureLevel::High
    }

    /// Whether allocation should trigger immediate GC.
    pub fn needs_immediate_gc(&self) -> bool {
        self.pressure_level >= X86GCPressureLevel::Critical
    }

    /// Reset counters after a GC cycle.
    pub fn after_gc(&mut self, freed_bytes: u64) {
        self.freed_since_gc = 0;
        self.heap_occupancy = self.heap_occupancy.saturating_sub(freed_bytes);
        self.update_pressure();
        self.stats.total_collections += 1;
    }

    /// Get the current occupancy ratio.
    pub fn occupancy_ratio(&self) -> f64 {
        if self.max_heap_size > 0 {
            self.heap_occupancy as f64 / self.max_heap_size as f64
        } else {
            0.0
        }
    }

    /// Get approximately how many bytes can still be allocated.
    pub fn available_bytes(&self) -> u64 {
        self.max_heap_size.saturating_sub(self.heap_occupancy)
    }
}

impl Default for X86GCMemoryPressure {
    fn default() -> Self {
        X86GCMemoryPressure::new(1024 * 1024 * 1024)
    }
}

// ============================================================================
// X86GCThreadSuspension — Cooperative and preemptive thread suspension
// ============================================================================

/// Manages thread suspension for stop-the-world GC.
#[derive(Debug, Clone)]
pub struct X86GCThreadSuspension {
    /// Whether global suspension is in effect.
    pub suspended: Arc<AtomicBool>,
    /// Number of threads currently at safepoints.
    pub threads_at_safepoint: Arc<AtomicU64>,
    /// Total number of managed threads.
    pub total_threads: Arc<AtomicU64>,
    /// Thread suspension state.
    pub state: X86GCSuspensionState,
    /// Whether to use cooperative suspension.
    pub cooperative: bool,
    /// Whether to use signal-based preemption.
    pub signal_preemption: bool,
    /// Timeout in microseconds for cooperative suspension.
    pub suspension_timeout_us: u64,
    /// Threads that have been preempted.
    pub preempted_threads: HashSet<u32>,
    /// Per-thread state.
    pub thread_states: HashMap<u32, X86GCThreadState>,
}

/// Global suspension state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCSuspensionState {
    /// Threads are running normally.
    Running,
    /// GC has requested suspension.
    SuspensionRequested,
    /// Waiting for all threads to reach safepoints.
    WaitingForThreads,
    /// All threads suspended — GC in progress.
    Suspended,
    /// Threads are being resumed.
    Resuming,
}

/// Per-thread GC state.
#[derive(Debug, Clone)]
pub struct X86GCThreadState {
    /// Thread ID.
    pub thread_id: u32,
    /// Whether this thread is at a safepoint.
    pub at_safepoint: bool,
    /// Whether this thread has been preempted.
    pub preempted: bool,
    /// Thread's stack pointer at safepoint.
    pub saved_rsp: u64,
    /// Thread's base pointer at safepoint.
    pub saved_rbp: u64,
    /// Thread's instruction pointer at safepoint.
    pub saved_rip: u64,
    /// Whether this thread has pending GC roots to report.
    pub has_pending_roots: bool,
}

impl X86GCThreadSuspension {
    /// Create a new thread suspension manager.
    pub fn new(cooperative: bool, signal_preemption: bool) -> Self {
        X86GCThreadSuspension {
            suspended: Arc::new(AtomicBool::new(false)),
            threads_at_safepoint: Arc::new(AtomicU64::new(0)),
            total_threads: Arc::new(AtomicU64::new(0)),
            state: X86GCSuspensionState::Running,
            cooperative,
            signal_preemption,
            suspension_timeout_us: 100_000, // 100ms
            preempted_threads: HashSet::new(),
            thread_states: HashMap::new(),
        }
    }

    /// Register a thread with the suspension manager.
    pub fn register_thread(&mut self, thread_id: u32) {
        self.thread_states.insert(
            thread_id,
            X86GCThreadState {
                thread_id,
                at_safepoint: false,
                preempted: false,
                saved_rsp: 0,
                saved_rbp: 0,
                saved_rip: 0,
                has_pending_roots: false,
            },
        );
        self.total_threads.fetch_add(1, Ordering::SeqCst);
    }

    /// Mark a thread as having reached a safepoint.
    pub fn thread_reached_safepoint(&mut self, thread_id: u32) {
        if let Some(state) = self.thread_states.get_mut(&thread_id) {
            if !state.at_safepoint {
                state.at_safepoint = true;
                self.threads_at_safepoint.fetch_add(1, Ordering::SeqCst);
            }
        }
    }

    /// Mark a thread as having left a safepoint.
    pub fn thread_left_safepoint(&mut self, thread_id: u32) {
        if let Some(state) = self.thread_states.get_mut(&thread_id) {
            if state.at_safepoint {
                state.at_safepoint = false;
                self.threads_at_safepoint.fetch_sub(1, Ordering::SeqCst);
            }
        }
    }

    /// Request all threads to suspend.
    pub fn request_suspension(&mut self) {
        self.state = X86GCSuspensionState::SuspensionRequested;
        self.suspended.store(true, Ordering::SeqCst);
    }

    /// Check if all threads have reached safepoints.
    pub fn all_threads_at_safepoints(&self) -> bool {
        let at_sp = self.threads_at_safepoint.load(Ordering::SeqCst);
        let total = self.total_threads.load(Ordering::SeqCst);
        at_sp >= total
    }

    /// Enter the suspended state (all threads stopped).
    pub fn enter_suspended(&mut self) {
        self.state = X86GCSuspensionState::Suspended;
    }

    /// Resume all threads.
    pub fn resume_all(&mut self) {
        self.state = X86GCSuspensionState::Resuming;
        self.suspended.store(false, Ordering::SeqCst);

        for state in self.thread_states.values_mut() {
            state.at_safepoint = false;
        }

        self.threads_at_safepoint.store(0, Ordering::SeqCst);
        self.state = X86GCSuspensionState::Running;
    }

    /// Check if a thread should yield (poll at safepoint).
    pub fn should_yield(&self) -> bool {
        self.suspended.load(Ordering::SeqCst)
    }

    /// Preempt a thread by thread ID (signal-based).
    pub fn preempt_thread(&mut self, thread_id: u32) {
        if self.signal_preemption {
            self.preempted_threads.insert(thread_id);
            if let Some(state) = self.thread_states.get_mut(&thread_id) {
                state.preempted = true;
            }
        }
    }

    /// Get the number of threads still running (not at safepoint).
    pub fn running_threads(&self) -> u64 {
        let total = self.total_threads.load(Ordering::SeqCst);
        let at_sp = self.threads_at_safepoint.load(Ordering::SeqCst);
        total.saturating_sub(at_sp)
    }
}

impl Default for X86GCThreadSuspension {
    fn default() -> Self {
        X86GCThreadSuspension::new(true, false)
    }
}

// ============================================================================
// X86GCDeoptimization — Deoptimization support for speculative optimizations
// ============================================================================

/// Deoptimization state — used to reconstruct the interpreter state
/// when a speculative optimization fails and execution must continue
/// in the interpreter or baseline JIT.
#[derive(Debug, Clone)]
pub struct X86GCDeoptimization {
    /// Deoptimization reason.
    pub reason: X86GCDeoptReason,
    /// Bytecode offset to resume at.
    pub bytecode_offset: u32,
    /// Method being deoptimized.
    pub method_name: String,
    /// Saved register state.
    pub registers: HashMap<u16, u64>,
    /// Saved stack slots.
    pub stack_slots: Vec<X86GCDeoptStackSlot>,
    /// Live local variable values.
    pub local_values: Vec<X86GCDeoptLocal>,
    /// Inline depth (for inlined frames).
    pub inline_depth: u32,
    /// Whether the continuation should re-execute the current instruction.
    pub is_reexecute: bool,
    /// Total size in bytes of the deopt bundle.
    pub bundle_size: u32,
}

/// Reason for deoptimization.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCDeoptReason {
    /// No deoptimization required.
    None,
    /// A speculative guard failed.
    SpeculativeGuard,
    /// A type check failed.
    TypeCheck,
    /// A bounds check failed.
    BoundsCheck,
    /// A null check failed.
    NullCheck,
    /// Division by zero.
    DivZero,
    /// Class check failed.
    ClassCheck,
    /// Virtual call guard failed.
    VirtualCall,
    /// Inline cache miss.
    InlineCacheMiss,
    /// Explicit deoptimization request.
    Explicit,
    /// Debug deoptimization (for tooling).
    Debug,
}

impl X86GCDeoptReason {
    pub fn description(&self) -> &str {
        match self {
            X86GCDeoptReason::None => "none",
            X86GCDeoptReason::SpeculativeGuard => "speculative guard failed",
            X86GCDeoptReason::TypeCheck => "type check failed",
            X86GCDeoptReason::BoundsCheck => "bounds check failed",
            X86GCDeoptReason::NullCheck => "null check failed",
            X86GCDeoptReason::DivZero => "division by zero",
            X86GCDeoptReason::ClassCheck => "class check failed",
            X86GCDeoptReason::VirtualCall => "virtual call guard failed",
            X86GCDeoptReason::InlineCacheMiss => "inline cache miss",
            X86GCDeoptReason::Explicit => "explicit deoptimization",
            X86GCDeoptReason::Debug => "debug deoptimization",
        }
    }
}

/// A stack slot value preserved for deoptimization.
#[derive(Debug, Clone)]
pub struct X86GCDeoptStackSlot {
    /// Stack offset (from frame base).
    pub offset: i32,
    /// Value stored at the offset.
    pub value: u64,
    /// Whether this value is a GC reference.
    pub is_reference: bool,
    /// Size in bytes.
    pub size: u8,
}

/// A local variable value for deoptimization.
#[derive(Debug, Clone)]
pub struct X86GCDeoptLocal {
    /// Variable name.
    pub name: String,
    /// Type name.
    pub type_name: String,
    /// Current value.
    pub value: u64,
    /// Whether this is a GC reference.
    pub is_reference: bool,
}

impl X86GCDeoptimization {
    /// Create a new deoptimization state.
    pub fn new(reason: X86GCDeoptReason, method_name: &str, bytecode_offset: u32) -> Self {
        X86GCDeoptimization {
            reason,
            bytecode_offset,
            method_name: method_name.to_string(),
            registers: HashMap::new(),
            stack_slots: Vec::new(),
            local_values: Vec::new(),
            inline_depth: 0,
            is_reexecute: false,
            bundle_size: 0,
        }
    }

    /// Record a register value.
    pub fn record_register(&mut self, dwarf_reg: u16, value: u64) {
        self.registers.insert(dwarf_reg, value);
    }

    /// Record a stack slot.
    pub fn record_stack_slot(&mut self, offset: i32, value: u64, size: u8, is_ref: bool) {
        self.stack_slots.push(X86GCDeoptStackSlot {
            offset,
            value,
            is_reference: is_ref,
            size,
        });
    }

    /// Record a local variable.
    pub fn record_local(&mut self, name: &str, type_name: &str, value: u64, is_ref: bool) {
        self.local_values.push(X86GCDeoptLocal {
            name: name.to_string(),
            type_name: type_name.to_string(),
            value,
            is_reference: is_ref,
        });
    }

    /// Mark that the instruction should be re-executed after deopt.
    pub fn mark_reexecute(&mut self) {
        self.is_reexecute = true;
    }

    /// Set the inline depth.
    pub fn with_inline_depth(mut self, depth: u32) -> Self {
        self.inline_depth = depth;
        self
    }

    /// Get all GC references in the deoptimization state.
    pub fn gc_references(&self) -> Vec<u64> {
        let mut refs = Vec::new();

        // Register values
        for (_, &value) in self.registers.iter() {
            if value != 0 {
                refs.push(value);
            }
        }

        // Stack slots that are references
        for slot in &self.stack_slots {
            if slot.is_reference && slot.value != 0 {
                refs.push(slot.value);
            }
        }

        // Local variables that are references
        for local in &self.local_values {
            if local.is_reference && local.value != 0 {
                refs.push(local.value);
            }
        }

        refs
    }
}

// ============================================================================
// X86GCStatistics — GC performance and behavioral statistics
// ============================================================================

/// Comprehensive GC statistics for monitoring and tuning.
#[derive(Debug, Clone, Default)]
pub struct X86GCStatistics {
    /// Total GC cycles.
    pub total_gc_cycles: u64,
    /// Minor collections.
    pub minor_collections: u64,
    /// Major collections.
    pub major_collections: u64,
    /// Full heap collections.
    pub full_collections: u64,
    /// Concurrent marking cycles completed.
    pub concurrent_marking_cycles: u64,
    /// Total bytes allocated since startup.
    pub total_bytes_allocated: u64,
    /// Total bytes freed.
    pub total_bytes_freed: u64,
    /// Total bytes copied (for copying/compacting collectors).
    pub total_bytes_copied: u64,
    /// Total bytes promoted.
    pub total_bytes_promoted: u64,
    /// Total finalizers executed.
    pub total_finalizers_executed: u64,
    /// Total weak references cleared.
    pub total_weak_refs_cleared: u64,
    /// Total phantom references processed.
    pub total_phantom_processed: u64,
    /// Total write barriers executed.
    pub total_write_barriers: u64,
    /// Total read barriers executed.
    pub total_read_barriers: u64,
    /// Total SATB entries logged.
    pub total_satb_logged: u64,
    /// Total TLAB refills.
    pub total_tlab_refills: u64,
    /// Total slow-path allocations.
    pub total_slow_path_allocs: u64,
    /// Average GC pause time (arbitrary units).
    pub avg_gc_pause_time: f64,
    /// Maximum GC pause time.
    pub max_gc_pause_time: u64,
    /// Total time in GC.
    pub total_gc_time: u64,
    /// Total safepoints hit.
    pub total_safepoints_hit: u64,
    /// Total page faults from polling.
    pub total_poll_page_faults: u64,
    /// Fragmentation ratio after last major collection.
    pub last_fragmentation_ratio: f64,
    /// Heap occupancy ratio.
    pub heap_occupancy_ratio: f64,
    /// Number of out-of-memory events.
    pub oom_events: u64,
    /// Collection efficiency (bytes freed per ms of GC time).
    pub collection_efficiency: f64,
}

impl X86GCStatistics {
    /// Create a new statistics tracker.
    pub fn new() -> Self {
        X86GCStatistics {
            total_gc_cycles: 0,
            minor_collections: 0,
            major_collections: 0,
            full_collections: 0,
            concurrent_marking_cycles: 0,
            total_bytes_allocated: 0,
            total_bytes_freed: 0,
            total_bytes_copied: 0,
            total_bytes_promoted: 0,
            total_finalizers_executed: 0,
            total_weak_refs_cleared: 0,
            total_phantom_processed: 0,
            total_write_barriers: 0,
            total_read_barriers: 0,
            total_satb_logged: 0,
            total_tlab_refills: 0,
            total_slow_path_allocs: 0,
            avg_gc_pause_time: 0.0,
            max_gc_pause_time: 0,
            total_gc_time: 0,
            total_safepoints_hit: 0,
            total_poll_page_faults: 0,
            last_fragmentation_ratio: 0.0,
            heap_occupancy_ratio: 0.0,
            oom_events: 0,
            collection_efficiency: 0.0,
        }
    }

    /// Record a GC cycle.
    pub fn record_gc_cycle(
        &mut self,
        is_minor: bool,
        is_major: bool,
        pause_time: u64,
        bytes_freed: u64,
    ) {
        self.total_gc_cycles += 1;
        if is_minor {
            self.minor_collections += 1;
        }
        if is_major {
            self.major_collections += 1;
        }
        self.total_gc_time += pause_time;
        self.total_bytes_freed += bytes_freed;

        // Update max pause time
        if pause_time > self.max_gc_pause_time {
            self.max_gc_pause_time = pause_time;
        }

        // Update average pause time
        let n = self.total_gc_cycles as f64;
        self.avg_gc_pause_time = (self.avg_gc_pause_time * (n - 1.0) + pause_time as f64) / n;

        // Update collection efficiency
        if self.total_gc_time > 0 {
            self.collection_efficiency = self.total_bytes_freed as f64 / self.total_gc_time as f64;
        }
    }

    /// Record an OOM event.
    pub fn record_oom(&mut self) {
        self.oom_events += 1;
    }

    /// Get a summary string.
    pub fn summary(&self) -> String {
        format!(
            "GC Stats: {} cycles ({} minor, {} major), {:.1}ms avg pause, {}MB freed, efficiency: {:.1} MB/ms",
            self.total_gc_cycles,
            self.minor_collections,
            self.major_collections,
            self.avg_gc_pause_time,
            self.total_bytes_freed / (1024 * 1024),
            self.collection_efficiency,
        )
    }

    /// Reset all statistics.
    pub fn reset(&mut self) {
        *self = X86GCStatistics::new();
    }
}

// ============================================================================
// X86GCRememberedSet — Old-to-young pointer tracking for generational GC
// ============================================================================

/// A remembered set tracks old-generation objects that may contain
/// references into the young generation.
#[derive(Debug, Clone)]
pub struct X86GCRememberedSet {
    /// Set of old-generation addresses that have been written to.
    pub entries: HashSet<u64>,
    /// Maximum size before overflow (fall back to card table scanning).
    pub max_size: usize,
    /// Whether the set has overflowed.
    pub overflowed: bool,
    /// Number of entries added since last clear.
    pub entries_since_clear: u64,
}

impl X86GCRememberedSet {
    /// Create a new remembered set.
    pub fn new(max_size: usize) -> Self {
        X86GCRememberedSet {
            entries: HashSet::new(),
            max_size,
            overflowed: false,
            entries_since_clear: 0,
        }
    }

    /// Add an address to the remembered set (write barrier).
    pub fn add(&mut self, address: u64) {
        if self.overflowed {
            return;
        }

        if self.entries.len() >= self.max_size {
            self.overflowed = true;
            return;
        }

        self.entries.insert(address);
        self.entries_since_clear += 1;
    }

    /// Check if an address is in the remembered set.
    pub fn contains(&self, address: u64) -> bool {
        self.entries.contains(&address)
    }

    /// Remove an address.
    pub fn remove(&mut self, address: u64) -> bool {
        self.entries.remove(&address)
    }

    /// Clear all entries.
    pub fn clear(&mut self) {
        self.entries.clear();
        self.overflowed = false;
        self.entries_since_clear = 0;
    }

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

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

    /// Iterate over entries (consuming the set).
    pub fn drain(&mut self) -> Vec<u64> {
        let entries: Vec<u64> = self.entries.drain().collect();
        self.overflowed = false;
        self.entries_since_clear = 0;
        entries
    }
}

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

// ============================================================================
// X86GCFull — Top-level GC framework integration
// ============================================================================

/// The complete X86 GC framework — brings together all GC subsystems
/// under a unified interface for code generation and runtime support.
#[derive(Debug)]
pub struct X86GCFull {
    /// The selected GC strategy.
    pub strategy: X86GCStrategy,
    /// Stack map generator and data.
    pub stack_map_generator: X86GCStackMapGenerator,
    /// Stack map parser (for loading existing stack maps).
    pub stack_map_parser: X86GCStackMapParser,
    /// Safepoint manager.
    pub safepoints: X86GCSafepoints,
    /// Root set for the current GC cycle.
    pub roots: Vec<X86GCRoot>,
    /// Finalization subsystem.
    pub finalization: X86GCFinalization,
    /// Card table for generational write barriers.
    pub card_table: Option<X86GCCardTable>,
    /// SATB buffer for concurrent marking.
    pub satb_buffer: Option<X86GCSATBBuffer>,
    /// Whether GC is currently enabled.
    pub gc_enabled: AtomicBool,
    /// Total GC cycles performed.
    pub gc_cycles: AtomicU64,
    /// Total bytes allocated since startup.
    pub total_bytes_allocated: AtomicU64,
    /// Total bytes freed since startup.
    pub total_bytes_freed: AtomicU64,
    /// Mark-sweep collector (active if using mark-sweep).
    pub mark_sweep_collector: Option<X86GCMarkSweepCollector>,
    /// Copying collector (active if using copying).
    pub copying_collector: Option<X86GCCopyingCollector>,
    /// Generational collector (active if using generational).
    pub generational_collector: Option<X86GCGenerationalCollector>,
    /// Incremental collector (active if using incremental).
    pub incremental_collector: Option<X86GCIncrementalCollector>,
    /// Bump allocator for fast-path allocation.
    pub bump_allocator: Option<X86GCBumpAllocator>,
    /// Free-list allocator for backup allocation.
    pub free_list_allocator: Option<X86GCFreeListAllocator>,
    /// TLAB allocator (per-thread, simplified here).
    pub tlab: Option<X86GCTLAB>,
    /// Large-object allocator.
    pub large_object_allocator: Option<X86GCLargeObjectAllocator>,
    /// Configuration.
    pub config: X86GCFullConfig,
    /// Stack walker for root discovery.
    pub stack_walker: Option<X86GCStackWalker>,
    /// Memory pressure monitor.
    pub memory_pressure: X86GCMemoryPressure,
    /// Thread suspension manager.
    pub thread_suspension: X86GCThreadSuspension,
    /// Deoptimization support.
    pub deoptimization: Option<X86GCDeoptimization>,
    /// GC statistics.
    pub statistics: X86GCStatistics,
    /// Remembered set (for generational collectors).
    pub remembered_set: Option<Box<X86GCRememberedSet>>,
}

/// Configuration for the X86GCFull framework.
#[derive(Debug, Clone)]
pub struct X86GCFullConfig {
    /// Whether stack maps should be emitted.
    pub emit_stack_maps: bool,
    /// Whether loop poll safepoints should be inserted.
    pub insert_loop_polls: bool,
    /// Whether statepoints should be rewritten.
    pub rewrite_statepoints: bool,
    /// Card table size in bytes.
    pub card_table_size: u64,
    /// Whether write barriers should be emitted.
    pub emit_write_barriers: bool,
    /// Whether read barriers should be emitted.
    pub emit_read_barriers: bool,
    /// Whether precise (type-accurate) scanning is used.
    pub is_exact: bool,
    /// Safepoint poll frequency.
    pub poll_frequency: X86GCSafepointFrequency,
    /// Whether concurrent GC is enabled.
    pub concurrent_gc: bool,
    /// Initial heap size in bytes.
    pub initial_heap_size: u64,
    /// Maximum heap size in bytes.
    pub max_heap_size: u64,
    /// Nursery size (for generational).
    pub nursery_size: u64,
    /// Whether generational collection is used.
    pub use_generational: bool,
    /// Whether incremental marking is used.
    pub use_incremental: bool,
    /// The collection algorithm.
    pub collection_algorithm: X86GCCollectionAlgorithm,
    /// Whether finalization is enabled.
    pub enable_finalization: bool,
    /// Whether weak references are processed.
    pub process_weak_refs: bool,
    /// Whether ephemerons are processed.
    pub process_ephemerons: bool,
}

/// Collection algorithm selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCCollectionAlgorithm {
    /// Mark-sweep (stop-the-world).
    MarkSweep,
    /// Mark-compact (stop-the-world, defragments).
    MarkCompact,
    /// Copying (semi-space, Cheney scan).
    Copying,
    /// Generational (minor + major collections).
    Generational,
    /// Incremental/concurrent (tri-color marking).
    Incremental,
    /// No collection — GC disabled.
    None,
}

impl fmt::Display for X86GCCollectionAlgorithm {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            X86GCCollectionAlgorithm::MarkSweep => write!(f, "mark-sweep"),
            X86GCCollectionAlgorithm::MarkCompact => write!(f, "mark-compact"),
            X86GCCollectionAlgorithm::Copying => write!(f, "copying"),
            X86GCCollectionAlgorithm::Generational => write!(f, "generational"),
            X86GCCollectionAlgorithm::Incremental => write!(f, "incremental"),
            X86GCCollectionAlgorithm::None => write!(f, "none"),
        }
    }
}

impl Default for X86GCFullConfig {
    fn default() -> Self {
        X86GCFullConfig {
            emit_stack_maps: true,
            insert_loop_polls: false,
            rewrite_statepoints: true,
            card_table_size: 1024 * 1024,
            emit_write_barriers: false,
            emit_read_barriers: false,
            is_exact: true,
            poll_frequency: X86GCSafepointFrequency::StatepointsOnly,
            concurrent_gc: false,
            initial_heap_size: 64 * 1024 * 1024,
            max_heap_size: 1024 * 1024 * 1024,
            nursery_size: X86_GC_DEFAULT_NURSERY_SIZE as u64,
            use_generational: false,
            use_incremental: false,
            collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
            enable_finalization: true,
            process_weak_refs: true,
            process_ephemerons: false,
        }
    }
}

/// A card table for generational write barriers.
#[derive(Debug, Clone)]
pub struct X86GCCardTable {
    /// Card table bytes (one byte per card).
    pub cards: Vec<u8>,
    /// Start of the managed heap.
    pub heap_start: u64,
    /// End of the managed heap.
    pub heap_end: u64,
    /// Card size in bytes (log2).
    pub card_shift: u8,
    /// Total number of cards.
    pub num_cards: u64,
}

impl X86GCCardTable {
    /// Create a new card table.
    pub fn new(heap_start: u64, heap_size: u64, card_shift: u8) -> Self {
        let card_size = 1u64 << card_shift;
        let num_cards = (heap_size + card_size - 1) / card_size;
        X86GCCardTable {
            cards: vec![0u8; num_cards as usize],
            heap_start,
            heap_end: heap_start + heap_size,
            card_shift,
            num_cards,
        }
    }

    /// Get the card index for a given address.
    pub fn card_index(&self, address: u64) -> usize {
        ((address - self.heap_start) >> self.card_shift) as usize
    }

    /// Mark a card as dirty (containing a modified old→young pointer).
    pub fn mark_dirty(&mut self, address: u64) {
        let idx = self.card_index(address);
        if idx < self.cards.len() {
            self.cards[idx] = 1;
        }
    }

    /// Clear a card.
    pub fn clear_card(&mut self, address: u64) {
        let idx = self.card_index(address);
        if idx < self.cards.len() {
            self.cards[idx] = 0;
        }
    }

    /// Check if a card is dirty.
    pub fn is_dirty(&self, address: u64) -> bool {
        let idx = self.card_index(address);
        idx < self.cards.len() && self.cards[idx] != 0
    }

    /// Clear all cards.
    pub fn clear_all(&mut self) {
        for card in &mut self.cards {
            *card = 0;
        }
    }

    /// Get all dirty card addresses.
    pub fn dirty_cards(&self) -> Vec<u64> {
        self.cards
            .iter()
            .enumerate()
            .filter(|&(_, &c)| c != 0)
            .map(|(i, _)| self.heap_start + (i as u64) * (1u64 << self.card_shift))
            .collect()
    }

    /// Count of dirty cards.
    pub fn dirty_count(&self) -> usize {
        self.cards.iter().filter(|&&c| c != 0).count()
    }
}

impl Default for X86GCCardTable {
    fn default() -> Self {
        X86GCCardTable::new(0, 64 * 1024 * 1024, 9) // 512-byte cards
    }
}

/// SATB (Snapshot-At-The-Beginning) buffer for concurrent marking.
#[derive(Debug, Clone)]
pub struct X86GCSATBBuffer {
    /// The buffer entries.
    pub entries: Vec<u64>,
    /// Current write index.
    pub index: u64,
    /// Buffer capacity.
    pub capacity: u64,
    /// Whether the buffer has overflowed.
    pub overflowed: bool,
}

impl X86GCSATBBuffer {
    /// Create a new SATB buffer.
    pub fn new(capacity: u64) -> Self {
        X86GCSATBBuffer {
            entries: Vec::with_capacity(capacity as usize),
            index: 0,
            capacity,
            overflowed: false,
        }
    }

    /// Log an old value (SATB barrier).
    pub fn log(&mut self, value: u64) {
        if self.overflowed {
            return;
        }
        if self.entries.len() < self.capacity as usize {
            self.entries.push(value);
            self.index += 1;
        } else {
            self.overflowed = true;
        }
    }

    /// Drain all entries and reset.
    pub fn drain(&mut self) -> Vec<u64> {
        let entries = std::mem::take(&mut self.entries);
        self.index = 0;
        self.overflowed = false;
        entries
    }

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

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

impl X86GCFull {
    /// Create the full X86 GC framework with the given strategy and config.
    pub fn new(strategy: X86GCStrategy, config: X86GCFullConfig) -> Self {
        let mut gc = X86GCFull {
            strategy: strategy.clone(),
            stack_map_generator: X86GCStackMapGenerator::new(),
            stack_map_parser: X86GCStackMapParser::new(),
            safepoints: X86GCSafepoints::default(),
            roots: Vec::new(),
            finalization: X86GCFinalization::new(),
            card_table: None,
            satb_buffer: None,
            gc_enabled: AtomicBool::new(true),
            gc_cycles: AtomicU64::new(0),
            total_bytes_allocated: AtomicU64::new(0),
            total_bytes_freed: AtomicU64::new(0),
            mark_sweep_collector: None,
            copying_collector: None,
            generational_collector: None,
            incremental_collector: None,
            bump_allocator: None,
            free_list_allocator: None,
            tlab: None,
            large_object_allocator: None,
            config,
            stack_walker: None,
            memory_pressure: X86GCMemoryPressure::default(),
            thread_suspension: X86GCThreadSuspension::default(),
            deoptimization: None,
            statistics: X86GCStatistics::default(),
            remembered_set: None,
        };

        // Initialize collectors and allocators based on strategy
        gc.initialize_collectors();
        gc
    }

    /// Initialize collectors and allocators based on the configuration.
    fn initialize_collectors(&mut self) {
        let heap_base = 0x10000u64; // Simplified base address
        let heap_size = self.config.initial_heap_size;

        match self.config.collection_algorithm {
            X86GCCollectionAlgorithm::MarkSweep => {
                self.mark_sweep_collector =
                    Some(X86GCMarkSweepCollector::new(heap_base, heap_size));
            }
            X86GCCollectionAlgorithm::Copying => {
                let semispace = heap_size / 2;
                self.copying_collector = Some(X86GCCopyingCollector::new(
                    heap_base,
                    heap_base + semispace,
                    semispace,
                ));
            }
            X86GCCollectionAlgorithm::Generational => {
                let nursery_size = self.config.nursery_size;
                let old_size = heap_size - nursery_size;
                self.generational_collector = Some(X86GCGenerationalCollector::new(
                    heap_base,
                    nursery_size,
                    heap_base + nursery_size,
                    old_size,
                ));
            }
            X86GCCollectionAlgorithm::Incremental => {
                self.incremental_collector =
                    Some(X86GCIncrementalCollector::new(heap_base, heap_size));
            }
            X86GCCollectionAlgorithm::MarkCompact | X86GCCollectionAlgorithm::None => {}
        }

        // Initialize card table if using generational or write barriers
        if self.strategy.requires_write_barriers()
            || self.config.collection_algorithm == X86GCCollectionAlgorithm::Generational
        {
            self.card_table = Some(X86GCCardTable::new(heap_base, heap_size, 9));
        }

        // Initialize SATB buffer if using concurrent marking
        if self.config.concurrent_gc
            || self.config.collection_algorithm == X86GCCollectionAlgorithm::Incremental
        {
            self.satb_buffer = Some(X86GCSATBBuffer::new(1024));
        }

        // Initialize bump allocator
        self.bump_allocator = Some(X86GCBumpAllocator::new(
            heap_base,
            heap_size / 4,
            X86_GC_OBJECT_ALIGNMENT,
        ));

        // Initialize free-list allocator
        self.free_list_allocator = Some(X86GCFreeListAllocator::new(heap_size));

        // Initialize large-object allocator
        self.large_object_allocator = Some(X86GCLargeObjectAllocator::new(
            X86_GC_LARGE_OBJECT_THRESHOLD as u64,
        ));
    }

    /// Begin processing a function for GC code generation.
    pub fn begin_function(&mut self, name: &str, address: u64) {
        self.stack_map_generator.begin_function(name, address);
        self.safepoints
            .insert_entry_safepoint(name, &mut self.stack_map_generator);
    }

    /// End processing a function.
    pub fn end_function(&mut self) {
        self.stack_map_generator.end_function();
    }

    /// Add a root for the current function.
    pub fn add_root(&mut self, root: X86GCRoot) {
        self.roots.push(root);
    }

    /// Add a safepoint at the current instruction offset.
    pub fn add_safepoint(
        &mut self,
        function_name: &str,
        offset: u64,
        kind: X86GCSafepointKind,
    ) -> Option<u64> {
        match kind {
            X86GCSafepointKind::LoopBackedge => self.safepoints.insert_backedge_safepoint(
                function_name,
                offset,
                &mut self.stack_map_generator,
            ),
            X86GCSafepointKind::AfterCall => self.safepoints.insert_call_safepoint(
                function_name,
                offset,
                &mut self.stack_map_generator,
            ),
            X86GCSafepointKind::FunctionEntry => self
                .safepoints
                .insert_entry_safepoint(function_name, &mut self.stack_map_generator),
            _ => None,
        }
    }

    /// Record a write barrier for card marking.
    pub fn record_write_barrier(&mut self, object_base: u64, field_offset: u64, new_value: u64) {
        if let Some(ref mut card_table) = self.card_table {
            card_table.mark_dirty(object_base);
        }
        let _ = (field_offset, new_value);
    }

    /// Record an SATB barrier.
    pub fn record_satb_barrier(&mut self, old_value: u64) {
        if let Some(ref mut satb) = self.satb_buffer {
            satb.log(old_value);
        }
    }

    /// Allocate memory through the fast path.
    pub fn allocate(&mut self, size: u64) -> u64 {
        // Try TLAB first
        if let Some(ref mut tlab) = self.tlab {
            let result = tlab.allocate_fast(size);
            if result != 0 {
                self.total_bytes_allocated
                    .fetch_add(size, Ordering::Relaxed);
                return result;
            }
        }

        // Try bump allocator
        if let Some(ref mut bump) = self.bump_allocator {
            let result = bump.allocate_fast(size);
            if result != 0 {
                self.total_bytes_allocated
                    .fetch_add(size, Ordering::Relaxed);
                return result;
            }
        }

        // Try free-list
        if let Some(ref mut fl) = self.free_list_allocator {
            let result = fl.allocate(size as u32);
            if result != 0 {
                self.total_bytes_allocated
                    .fetch_add(size, Ordering::Relaxed);
                return result;
            }
        }

        // Try large-object allocator
        if let Some(ref mut lo) = self.large_object_allocator {
            let result = lo.allocate(size);
            if result != 0 {
                self.total_bytes_allocated
                    .fetch_add(size, Ordering::Relaxed);
                return result;
            }
        }

        // Slow path: trigger GC
        self.collect();

        // Retry after GC
        if let Some(ref mut bump) = self.bump_allocator {
            let result = bump.allocate_fast(size);
            if result != 0 {
                self.total_bytes_allocated
                    .fetch_add(size, Ordering::Relaxed);
                return result;
            }
        }

        0 // Out of memory
    }

    /// Trigger a garbage collection cycle.
    pub fn collect(&mut self) {
        self.gc_enabled.store(false, Ordering::SeqCst);

        match self.config.collection_algorithm {
            X86GCCollectionAlgorithm::MarkSweep => {
                if let Some(ref mut ms) = self.mark_sweep_collector {
                    ms.collect(&self.roots);
                }
            }
            X86GCCollectionAlgorithm::Copying => {
                if let Some(ref mut cp) = self.copying_collector {
                    // Convert roots to addresses for copying collector
                    let root_addrs: Vec<u64> = self
                        .roots
                        .iter()
                        .filter(|r| r.is_live)
                        .map(|_| 0u64) // In real GC, dereference root locations
                        .collect();
                    cp.collect(&root_addrs);
                }
            }
            X86GCCollectionAlgorithm::Generational => {
                if let Some(ref mut r#gen) = self.generational_collector {
                    let root_addrs: Vec<u64> = Vec::new();
                    r#gen.collect(&self.roots, &root_addrs);
                }
            }
            X86GCCollectionAlgorithm::Incremental => {
                if let Some(ref mut inc) = self.incremental_collector {
                    let root_addrs: Vec<u64> = Vec::new();
                    inc.start_mark(&root_addrs);
                }
            }
            X86GCCollectionAlgorithm::MarkCompact | X86GCCollectionAlgorithm::None => {}
        }

        // Process finalization
        if self.config.enable_finalization {
            self.finalization
                .process_finalizers(X86_GC_MAX_FINALIZERS_PER_CYCLE);
        }

        // Clear card table after collection
        if let Some(ref mut ct) = self.card_table {
            ct.clear_all();
        }

        // Drain SATB buffer
        if let Some(ref mut satb) = self.satb_buffer {
            let _entries = satb.drain();
            // In real GC, process SATB entries (re-mark objects)
        }

        self.gc_cycles.fetch_add(1, Ordering::SeqCst);
        self.gc_enabled.store(true, Ordering::SeqCst);
    }

    /// Perform an incremental marking step (for concurrent GC).
    /// Returns true if marking is complete.
    pub fn incremental_marking_step(&mut self, steps: usize) -> bool {
        if let Some(ref mut inc) = self.incremental_collector {
            inc.marking_step(steps)
        } else {
            true
        }
    }

    /// Perform an incremental sweeping step.
    /// Returns true if sweeping is complete.
    pub fn incremental_sweeping_step(&mut self) -> bool {
        if let Some(ref mut inc) = self.incremental_collector {
            inc.sweeping_step()
        } else {
            true
        }
    }

    /// Finalize code generation and produce the stack map.
    pub fn finalize_stack_maps(&mut self) -> X86GCStackMap {
        self.stack_map_generator.finalize()
    }

    /// Emit the stack map section as binary.
    pub fn emit_stack_map_bytes(&self) -> Vec<u8> {
        self.stack_map_generator.stack_map.emit_bytes()
    }

    /// Emit the stack map section as assembly.
    pub fn emit_stack_map_assembly(&self) -> String {
        self.stack_map_generator.stack_map.emit_assembly()
    }

    /// Enable GC.
    pub fn enable(&self) {
        self.gc_enabled.store(true, Ordering::SeqCst);
    }

    /// Disable GC (for critical sections).
    pub fn disable(&self) {
        self.gc_enabled.store(false, Ordering::SeqCst);
    }

    /// Whether GC is currently enabled.
    pub fn is_enabled(&self) -> bool {
        self.gc_enabled.load(Ordering::SeqCst)
    }

    /// Get total GC cycles.
    pub fn gc_cycles(&self) -> u64 {
        self.gc_cycles.load(Ordering::SeqCst)
    }

    /// Get total bytes allocated.
    pub fn total_allocated(&self) -> u64 {
        self.total_bytes_allocated.load(Ordering::SeqCst)
    }

    /// Validate the current GC state.
    pub fn validate(&self) -> Result<(), String> {
        if self.roots.is_empty()
            && self.config.collection_algorithm != X86GCCollectionAlgorithm::None
        {
            return Err("No roots registered for GC collection".to_string());
        }

        if self.config.emit_stack_maps {
            if self.stack_map_generator.stack_map.functions.is_empty() {
                return Err("Stack maps enabled but no functions registered".to_string());
            }
        }

        Ok(())
    }
}

// ============================================================================
// Frame descriptor for OCaml-style GC
// ============================================================================

/// OCaml-style frame descriptor — a compact representation of root locations
/// on the stack frame.
#[derive(Debug, Clone)]
pub struct X86GCFrameDescriptor {
    /// Return address that identifies this frame.
    pub return_address: u64,
    /// Total frame size in bytes (for sp restoration).
    pub frame_size: u32,
    /// Number of root slots in the frame.
    pub num_roots: u16,
    /// Bitmap of root slots (bit i set = slot at offset i*8 is a root).
    pub root_bitmap: u64,
    /// Whether this descriptor is valid.
    pub is_valid: bool,
}

impl X86GCFrameDescriptor {
    /// Create a new frame descriptor.
    pub fn new(return_address: u64, frame_size: u32) -> Self {
        X86GCFrameDescriptor {
            return_address,
            frame_size,
            num_roots: 0,
            root_bitmap: 0,
            is_valid: true,
        }
    }

    /// Mark a stack slot as a root.
    /// Slot index 0 = first 8-byte slot below the return address.
    pub fn add_root(&mut self, slot_index: u8) {
        if slot_index < 64 {
            self.root_bitmap |= 1u64 << slot_index;
            self.num_roots += 1;
        }
    }

    /// Check if a slot is a root.
    pub fn is_root(&self, slot_index: u8) -> bool {
        if slot_index >= 64 {
            return false;
        }
        (self.root_bitmap & (1u64 << slot_index)) != 0
    }

    /// Get root offsets from the frame base.
    pub fn root_offsets(&self) -> Vec<i32> {
        (0..64)
            .filter(|&i| self.is_root(i))
            .map(|i| -((i as i32 + 1) * 8)) // Negative offsets from RBP
            .collect()
    }
}

/// OCaml GC table — maps return addresses to frame descriptors.
#[derive(Debug, Clone)]
pub struct X86GCOCamlTable {
    /// Frame descriptors indexed by return address.
    pub descriptors: HashMap<u64, X86GCFrameDescriptor>,
    /// Sorted list of return addresses for binary search.
    pub addr_list: Vec<u64>,
}

impl X86GCOCamlTable {
    /// Create a new empty table.
    pub fn new() -> Self {
        X86GCOCamlTable {
            descriptors: HashMap::new(),
            addr_list: Vec::new(),
        }
    }

    /// Add a frame descriptor.
    pub fn add_descriptor(&mut self, desc: X86GCFrameDescriptor) {
        self.addr_list.push(desc.return_address);
        self.descriptors.insert(desc.return_address, desc);
    }

    /// Look up a frame descriptor by return address.
    /// OCaml uses the return address (the address after the call instruction)
    /// to identify the caller's frame.
    pub fn lookup(&self, return_address: u64) -> Option<&X86GCFrameDescriptor> {
        self.descriptors.get(&return_address)
    }

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

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

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

// ============================================================================
// CoreCLR GCInfo support
// ============================================================================

/// CoreCLR GCInfo — encodes which stack slots and registers contain
/// GC pointers at which instruction offsets.
#[derive(Debug, Clone)]
pub struct X86GCCoreCLRInfo {
    /// GCInfo version.
    pub version: u8,
    /// Return address of the method.
    pub return_address: u64,
    /// Method code size in bytes.
    pub method_size: u32,
    /// Whether this method is fully interruptible.
    pub is_fully_interruptible: bool,
    /// Interruptible regions (for partially interruptible methods).
    pub interruptible_regions: Vec<X86GCCoreCLRRegion>,
    /// Live GC slots at various offsets.
    pub live_slots: Vec<X86GCCoreCLRLiveSlot>,
    /// GC transitions (changes in liveness).
    pub transitions: Vec<X86GCCoreCLRTransition>,
    /// Whether the method has a security object.
    pub has_security_object: bool,
    /// Whether the method has a generational cookie.
    pub has_gen_cookie: bool,
    /// Epilog count.
    pub epilog_count: u8,
}

/// An interruptible region in CoreCLR GCInfo.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCCoreCLRRegion {
    /// Start instruction offset.
    pub start_offset: u32,
    /// End instruction offset.
    pub end_offset: u32,
}

/// A live GC slot description in CoreCLR GCInfo.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCCoreCLRLiveSlot {
    /// Stack offset (from RBP).
    pub stack_offset: i32,
    /// Whether this is a byref (interior pointer).
    pub is_byref: bool,
    /// Whether this is pinned (must not be moved).
    pub is_pinned: bool,
}

/// A GC transition point in CoreCLR GCInfo.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCCoreCLRTransition {
    /// Instruction offset where the transition occurs.
    pub instruction_offset: u32,
    /// Code offset for the transition.
    pub code_offset: u32,
    /// Whether this is a call site.
    pub is_call_site: bool,
}

impl X86GCCoreCLRInfo {
    /// Create a new CoreCLR GCInfo entry.
    pub fn new(return_address: u64, method_size: u32) -> Self {
        X86GCCoreCLRInfo {
            version: 2,
            return_address,
            method_size,
            is_fully_interruptible: false,
            interruptible_regions: Vec::new(),
            live_slots: Vec::new(),
            transitions: Vec::new(),
            has_security_object: false,
            has_gen_cookie: false,
            epilog_count: 0,
        }
    }

    /// Mark as fully interruptible.
    pub fn mark_fully_interruptible(&mut self) {
        self.is_fully_interruptible = true;
    }

    /// Add an interruptible region.
    pub fn add_region(&mut self, start: u32, end: u32) {
        self.interruptible_regions.push(X86GCCoreCLRRegion {
            start_offset: start,
            end_offset: end,
        });
    }

    /// Add a live slot.
    pub fn add_live_slot(&mut self, offset: i32, is_byref: bool, is_pinned: bool) {
        self.live_slots.push(X86GCCoreCLRLiveSlot {
            stack_offset: offset,
            is_byref,
            is_pinned,
        });
    }

    /// Add a transition.
    pub fn add_transition(&mut self, inst_offset: u32, code_offset: u32, is_call: bool) {
        self.transitions.push(X86GCCoreCLRTransition {
            instruction_offset: inst_offset,
            code_offset,
            is_call_site: is_call,
        });
    }

    /// Encode the GCInfo to a compact binary representation.
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::new();

        // Header
        buf.push(self.version);
        buf.push(if self.is_fully_interruptible { 1 } else { 0 });
        buf.push(self.epilog_count);

        // Flags
        let mut flags: u8 = 0;
        if self.has_security_object {
            flags |= 1;
        }
        if self.has_gen_cookie {
            flags |= 2;
        }
        buf.push(flags);

        // Method size (LEB128 encoded)
        encode_uleb128(&mut buf, self.method_size as u64);

        // Live slots
        encode_uleb128(&mut buf, self.live_slots.len() as u64);
        for slot in &self.live_slots {
            encode_sleb128(&mut buf, slot.stack_offset as i64);
            let slot_flags: u8 =
                if slot.is_byref { 1 } else { 0 } | if slot.is_pinned { 2 } else { 0 };
            buf.push(slot_flags);
        }

        // Transitions
        encode_uleb128(&mut buf, self.transitions.len() as u64);
        for t in &self.transitions {
            encode_uleb128(&mut buf, t.instruction_offset as u64);
            encode_uleb128(&mut buf, t.code_offset as u64);
            buf.push(if t.is_call_site { 1 } else { 0 });
        }

        buf
    }
}

// ============================================================================
// Helpers
// ============================================================================

/// Encode an unsigned value as ULEB128.
fn encode_uleb128(buf: &mut Vec<u8>, mut value: u64) {
    loop {
        let mut byte = (value & 0x7F) as u8;
        value >>= 7;
        if value != 0 {
            byte |= 0x80;
        }
        buf.push(byte);
        if value == 0 {
            break;
        }
    }
}

/// Encode a signed value as SLEB128.
fn encode_sleb128(buf: &mut Vec<u8>, mut value: i64) {
    loop {
        let mut byte = (value & 0x7F) as u8;
        value >>= 7;
        if (value == 0 && (byte & 0x40) == 0) || (value == -1 && (byte & 0x40) != 0) {
            buf.push(byte);
            break;
        }
        byte |= 0x80;
        buf.push(byte);
    }
}

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

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

    // --- X86GCStrategy tests ---

    #[test]
    fn test_strategy_names() {
        assert_eq!(X86GCStrategy::ShadowStack.name(), "shadow-stack");
        assert_eq!(X86GCStrategy::Statepoint.name(), "statepoint");
        assert_eq!(X86GCStrategy::CoreCLR.name(), "coreclr");
        assert_eq!(X86GCStrategy::Erlang.name(), "erlang");
        assert_eq!(X86GCStrategy::OCaml.name(), "ocaml");
    }

    #[test]
    fn test_strategy_uses_statepoints() {
        assert!(X86GCStrategy::Statepoint.uses_statepoints());
        assert!(!X86GCStrategy::ShadowStack.uses_statepoints());
        assert!(!X86GCStrategy::CoreCLR.uses_statepoints());
    }

    #[test]
    fn test_strategy_supports_generational() {
        assert!(X86GCStrategy::ShadowStack.supports_generational());
        assert!(X86GCStrategy::Statepoint.supports_generational());
        assert!(!X86GCStrategy::OCaml.supports_generational());
    }

    #[test]
    fn test_strategy_requires_write_barriers() {
        assert!(X86GCStrategy::CoreCLR.requires_write_barriers());
        assert!(!X86GCStrategy::Statepoint.requires_write_barriers());
    }

    #[test]
    fn test_custom_strategy_default() {
        let custom = X86GCCustomStrategy::default();
        assert_eq!(custom.name, "custom");
        assert!(!custom.uses_statepoints);
        assert!(!custom.uses_shadow_stack);
        assert_eq!(custom.suspension, X86GCSuspension::Polling);
    }

    #[test]
    fn test_strategy_display() {
        assert_eq!(format!("{}", X86GCStrategy::ShadowStack), "shadow-stack");
        assert_eq!(format!("{}", X86GCStrategy::Erlang), "erlang");
    }

    #[test]
    fn test_strategy_default() {
        let default = X86GCStrategy::default();
        assert_eq!(default, X86GCStrategy::Statepoint);
    }

    #[test]
    fn test_suspension_display() {
        assert_eq!(format!("{}", X86GCSuspension::Polling), "polling");
        assert_eq!(format!("{}", X86GCSuspension::None), "none");
        assert_eq!(format!("{}", X86GCSuspension::PageFault), "pagefault");
    }

    // --- X86GCRoot tests ---

    #[test]
    fn test_root_new_base() {
        let root = X86GCRoot::new_base(1, -8);
        assert_eq!(root.id, 1);
        assert_eq!(root.frame_offset, -8);
        assert!(!root.is_derived);
        assert!(root.is_live);
        assert_eq!(root.pointer_size, 8);
    }

    #[test]
    fn test_root_new_derived() {
        let root = X86GCRoot::new_derived(2, -16, 1, 24);
        assert_eq!(root.id, 2);
        assert!(root.is_derived);
        assert_eq!(root.base_root_id, Some(1));
        assert_eq!(root.interior_offset, 24);
    }

    #[test]
    fn test_root_new_register() {
        let root = X86GCRoot::new_register(3, DWARF_REG_RAX);
        assert_eq!(root.id, 3);
        assert_eq!(root.register, Some(DWARF_REG_RAX));
    }

    #[test]
    fn test_root_new_static() {
        let root = X86GCRoot::new_static(4, "my_global".to_string());
        assert!(root.is_constant);
        assert_eq!(root.symbol_name, Some("my_global".to_string()));
    }

    #[test]
    fn test_root_new_thread_local() {
        let root = X86GCRoot::new_thread_local(5, 42);
        assert_eq!(root.tls_index, Some(42));
    }

    #[test]
    fn test_root_with_type_metadata() {
        let root = X86GCRoot::new_base(1, -8)
            .with_type_metadata(X86GCRootType::PointerArray { length: 10 });
        assert!(root.type_metadata.is_some());
        assert_eq!(root.slot_size(), 80);
    }

    #[test]
    fn test_root_with_language() {
        let root = X86GCRoot::new_base(1, -8).with_language(X86GCRootLanguage::Rust);
        assert_eq!(root.source_language, X86GCRootLanguage::Rust);
    }

    #[test]
    fn test_root_is_live_at() {
        let root = X86GCRoot::new_base(1, -8).with_live_range(10, 100);
        assert!(root.is_live_at(50));
        assert!(!root.is_live_at(5));
        assert!(!root.is_live_at(200));
    }

    #[test]
    fn test_root_mark_dead() {
        let root = X86GCRoot::new_base(1, -8).mark_dead();
        assert!(!root.is_live);
    }

    #[test]
    fn test_root_needs_conservative_scan() {
        let opaque =
            X86GCRoot::new_base(1, -8).with_type_metadata(X86GCRootType::Opaque { size: 64 });
        assert!(opaque.needs_conservative_scan());

        let precise = X86GCRoot::new_base(2, -16);
        assert!(!precise.needs_conservative_scan());
    }

    // --- X86GCRootType tests ---

    #[test]
    fn test_root_type_has_pointers() {
        assert!(X86GCRootType::Pointer.has_pointers());
        assert!(!X86GCRootType::Leaf.has_pointers());
        assert!(X86GCRootType::WeakPointer.has_pointers());
    }

    #[test]
    fn test_root_type_is_precise() {
        assert!(X86GCRootType::Pointer.is_precise());
        assert!(!X86GCRootType::Opaque { size: 32 }.is_precise());
    }

    // --- X86GCBarrier tests ---

    #[test]
    fn test_barrier_card_marking() {
        let barrier = X86GCBarrier::new_card_marking(0x1000, 0x10, 0x2000);
        assert_eq!(barrier.barrier_type, X86GCBarrierType::Write);
        assert_eq!(
            barrier.write_barrier_kind,
            X86GCWriteBarrierKind::CardMarking
        );
        assert_eq!(barrier.object_base, 0x1000);
        assert_eq!(barrier.field_offset, 0x10);
    }

    #[test]
    fn test_barrier_satb() {
        let barrier = X86GCBarrier::new_satb(0x1000, 0x10, 0xDEAD);
        assert_eq!(barrier.write_barrier_kind, X86GCWriteBarrierKind::SATB);
        assert_eq!(barrier.old_value, Some(0xDEAD));
    }

    #[test]
    fn test_barrier_brooks_read() {
        let barrier = X86GCBarrier::new_brooks_read(0x3000);
        assert_eq!(barrier.barrier_type, X86GCBarrierType::Read);
        assert_eq!(barrier.read_barrier_kind, X86GCReadBarrierKind::Brooks);
    }

    #[test]
    fn test_barrier_acquire_load() {
        let barrier = X86GCBarrier::new_acquire_load(0x4000);
        assert_eq!(barrier.read_barrier_kind, X86GCReadBarrierKind::AcquireLoad);
    }

    #[test]
    fn test_barrier_mark_array_element() {
        let barrier = X86GCBarrier::new_card_marking(0x1000, 0x20, 0x3000).mark_array_element();
        assert!(barrier.is_array_element);
    }

    #[test]
    fn test_barrier_emit_card_marking_asm() {
        let barrier = X86GCBarrier::new_card_marking(0x1000, 0x8, 0x42);
        let code = barrier.emit_x86_card_marking_asm(0x8000, 9);
        assert!(!code.is_empty());
        assert!(code.len() > 8);
    }

    #[test]
    fn test_barrier_emit_satb_asm() {
        let barrier = X86GCBarrier::new_satb(0x1000, 0x8, 0xABCD);
        let code = barrier.emit_x86_satb_asm(0x9000, 0xA000);
        assert!(!code.is_empty());
    }

    #[test]
    fn test_barrier_emit_brooks_read_asm() {
        let barrier = X86GCBarrier::new_brooks_read(0x5000);
        let code = barrier.emit_x86_brooks_read_asm();
        assert!(!code.is_empty());
        assert!(code.len() >= 10);
    }

    #[test]
    fn test_write_barrier_kind_display() {
        assert_eq!(
            format!("{}", X86GCWriteBarrierKind::CardMarking),
            "card-marking"
        );
        assert_eq!(format!("{}", X86GCWriteBarrierKind::SATB), "satb");
        assert_eq!(format!("{}", X86GCWriteBarrierKind::None), "none");
    }

    // --- X86GCBumpAllocator tests ---

    #[test]
    fn test_bump_allocator_allocate() {
        let mut alloc = X86GCBumpAllocator::new(0x1000, 4096, 8);
        let addr1 = alloc.allocate_fast(64);
        assert_ne!(addr1, 0);
        assert_eq!(addr1, 0x1000);

        let addr2 = alloc.allocate_fast(128);
        assert_eq!(addr2, 0x1000 + 64);

        assert_eq!(alloc.allocation_count, 2);
    }

    #[test]
    fn test_bump_allocator_exhaustion() {
        let mut alloc = X86GCBumpAllocator::new(0x1000, 256, 8);
        let addr = alloc.allocate_fast(300);
        assert_eq!(addr, 0);
        assert_eq!(alloc.slow_path_count, 1);
    }

    #[test]
    fn test_bump_allocator_alignment() {
        let mut alloc = X86GCBumpAllocator::new(0x1000, 4096, 16);
        let addr = alloc.allocate_fast(13);
        assert_eq!(addr % 16, 0);
        assert_eq!(alloc.bytes_allocated, 16); // Rounded up
    }

    #[test]
    fn test_bump_allocator_reset() {
        let mut alloc = X86GCBumpAllocator::new(0x1000, 4096, 8);
        let _ = alloc.allocate_fast(64);
        alloc.reset();
        assert_eq!(alloc.cursor, alloc.base);
        assert_eq!(alloc.remaining(), 4096);
    }

    #[test]
    fn test_bump_allocator_remaining() {
        let mut alloc = X86GCBumpAllocator::new(0x1000, 4096, 8);
        assert_eq!(alloc.remaining(), 4096);
        let _ = alloc.allocate_fast(1024);
        assert_eq!(alloc.remaining(), 4096 - 1024);
    }

    // --- X86GCFreeListAllocator tests ---

    #[test]
    fn test_free_list_allocate_exact() {
        let mut alloc = X86GCFreeListAllocator::new(1024 * 1024);
        alloc.add_free_block(0x1000, 64);
        let addr = alloc.allocate(64);
        assert_eq!(addr, 0x1000);
    }

    #[test]
    fn test_free_list_allocate_split() {
        let mut alloc = X86GCFreeListAllocator::new(1024 * 1024);
        alloc.add_free_block(0x1000, 128);
        let addr = alloc.allocate(64);
        assert_eq!(addr, 0x1000);
        // Check remainder is in free list
        assert!(alloc.free_bytes() >= 64);
    }

    #[test]
    fn test_free_list_allocate_no_fit() {
        let mut alloc = X86GCFreeListAllocator::new(1024 * 1024);
        let addr = alloc.allocate(1024);
        assert_eq!(addr, 0);
    }

    #[test]
    fn test_free_list_free_and_allocate() {
        let mut alloc = X86GCFreeListAllocator::new(1024 * 1024);
        alloc.add_free_block(0x1000, 256);
        let addr = alloc.allocate(128);
        assert_eq!(addr, 0x1000);
        alloc.free(addr, 128);
        let addr2 = alloc.allocate(128);
        assert_eq!(addr2, 0x1000);
    }

    #[test]
    fn test_free_list_size_class() {
        assert_eq!(X86GCFreeListAllocator::size_class(8), 16);
        assert_eq!(X86GCFreeListAllocator::size_class(32), 32);
        assert_eq!(X86GCFreeListAllocator::size_class(100), 128);
        assert_eq!(X86GCFreeListAllocator::size_class(500), 512);
        assert_eq!(X86GCFreeListAllocator::size_class(5000), 8192);
    }

    // --- X86GCTLAB tests ---

    #[test]
    fn test_tlab_allocate() {
        let mut tlab = X86GCTLAB::new(1, 0x1000, 1024);
        let addr = tlab.allocate_fast(64);
        assert_ne!(addr, 0);
        assert_eq!(tlab.bytes_allocated, 64);
    }

    #[test]
    fn test_tlab_exhaustion() {
        let mut tlab = X86GCTLAB::new(1, 0x1000, 128);
        let _ = tlab.allocate_fast(64);
        let addr = tlab.allocate_fast(128); // Too big
        assert_eq!(addr, 0);
    }

    #[test]
    fn test_tlab_refill() {
        let mut tlab = X86GCTLAB::new(1, 0x1000, 128);
        assert_eq!(tlab.refill_count, 0);
        tlab.refill(0x2000, 256);
        assert_eq!(tlab.refill_count, 1);
        assert_eq!(tlab.base, 0x2000);
        assert!(tlab.is_active);
    }

    #[test]
    fn test_tlab_retire() {
        let mut tlab = X86GCTLAB::new(1, 0x1000, 256);
        assert!(tlab.is_active);
        tlab.retire();
        assert!(!tlab.is_active);
    }

    #[test]
    fn test_tlab_needs_refill() {
        let mut tlab = X86GCTLAB::new(1, 0x1000, 256);
        assert!(!tlab.needs_refill(128));
        assert!(tlab.needs_refill(512));
    }

    // --- X86GCLargeObjectAllocator tests ---

    #[test]
    fn test_large_object_allocate() {
        let mut lo = X86GCLargeObjectAllocator::new(85 * 1024);
        let addr = lo.allocate(100 * 1024);
        assert_ne!(addr, 0);
        assert_eq!(lo.count, 1);
        assert!(lo.contains(addr));
    }

    #[test]
    fn test_large_object_below_threshold() {
        let mut lo = X86GCLargeObjectAllocator::new(85 * 1024);
        let addr = lo.allocate(64);
        assert_eq!(addr, 0);
    }

    #[test]
    fn test_large_object_free() {
        let mut lo = X86GCLargeObjectAllocator::new(85 * 1024);
        let addr = lo.allocate(100 * 1024);
        assert!(lo.free(addr));
        assert!(!lo.contains(addr));
        assert_eq!(lo.count, 0);
    }

    #[test]
    fn test_large_object_find_enclosing() {
        let mut lo = X86GCLargeObjectAllocator::new(85 * 1024);
        let addr = lo.allocate(200 * 1024);
        let interior = addr + 1000;
        let found = lo.find_enclosing_object(interior);
        assert!(found.is_some());
        assert_eq!(found.unwrap().0, addr);
    }

    // --- X86GCMarkSweepCollector tests ---

    #[test]
    fn test_mark_sweep_new() {
        let ms = X86GCMarkSweepCollector::new(0x10000, 1024 * 1024);
        assert_eq!(ms.heap_base, 0x10000);
        assert_eq!(ms.heap_size, 1024 * 1024);
        assert_eq!(ms.collections, 0);
        assert!(!ms.collecting);
    }

    #[test]
    fn test_mark_sweep_set_get_mark() {
        let mut ms = X86GCMarkSweepCollector::new(0x10000, 1024 * 1024);
        ms.set_mark(0x10000);
        assert!(ms.is_marked(0x10000));
        assert!(!ms.is_marked(0x10008));
        ms.set_mark(0x10008);
        assert!(ms.is_marked(0x10008));
    }

    #[test]
    fn test_mark_sweep_mark_out_of_range() {
        let mut ms = X86GCMarkSweepCollector::new(0x10000, 4096);
        ms.set_mark(0x20000); // Out of range
        assert!(!ms.is_marked(0x20000));
    }

    #[test]
    fn test_mark_sweep_collect() {
        let mut ms = X86GCMarkSweepCollector::new(0x10000, 1024 * 1024);
        let roots = vec![X86GCRoot::new_base(1, -8)];
        let freed = ms.collect(&roots);
        assert_eq!(ms.collections, 1);
        let _ = freed;
    }

    // --- X86GCCopyingCollector tests ---

    #[test]
    fn test_copying_new() {
        let cp = X86GCCopyingCollector::new(0x10000, 0x40000, 0x30000);
        assert_eq!(cp.fromspace_base, 0x10000);
        assert_eq!(cp.tospace_base, 0x40000);
        assert_eq!(cp.semispace_size, 0x30000);
    }

    #[test]
    fn test_copying_allocate_fast() {
        let mut cp = X86GCCopyingCollector::new(0x10000, 0x40000, 0x30000);
        let addr = cp.allocate_fast(64);
        assert_eq!(addr, 0x10000);
        let addr2 = cp.allocate_fast(128);
        assert_eq!(addr2, 0x10040);
    }

    #[test]
    fn test_copying_forward() {
        let mut cp = X86GCCopyingCollector::new(0x10000, 0x40000, 0x30000);
        cp.free = 0x40000; // Start of to-space
        let new_addr = cp.forward(0x10050, 64);
        assert_eq!(new_addr, 0x40000);
        // Forward again — should return same address
        let again = cp.forward(0x10050, 64);
        assert_eq!(again, 0x40000);
    }

    #[test]
    fn test_copying_collect() {
        let mut cp = X86GCCopyingCollector::new(0x10000, 0x40000, 0x30000);
        cp.free = 0x10080; // Some allocations happened
        let roots: Vec<u64> = vec![0x10000];
        let copied = cp.collect(&roots);
        assert_eq!(cp.collections, 1);
        let _ = copied;
    }

    // --- X86GCGenerationalCollector tests ---

    #[test]
    fn test_generational_new() {
        let r#gen = X86GCGenerationalCollector::new(0x10000, 1024 * 1024, 0x200000, 8 * 1024 * 1024);
        assert_eq!(r#gen.minor_collections, 0);
        assert_eq!(r#gen.major_collections, 0);
    }

    #[test]
    fn test_generational_nursery_allocate() {
        let mut r#gen =
            X86GCGenerationalCollector::new(0x10000, 1024 * 1024, 0x200000, 8 * 1024 * 1024);
        let addr = r#gen.nursery_allocate(128);
        assert_eq!(addr, 0x10000);
    }

    #[test]
    fn test_generational_record_write() {
        let mut r#gen =
            X86GCGenerationalCollector::new(0x10000, 1024 * 1024, 0x200000, 8 * 1024 * 1024);
        r#gen.record_write(0x200100); // Old-gen address
        assert!(r#gen.remembered_set.contains(&0x200100));
    }

    #[test]
    fn test_generational_minor_collect() {
        let mut r#gen =
            X86GCGenerationalCollector::new(0x10000, 1024 * 1024, 0x200000, 8 * 1024 * 1024);
        let roots = vec![X86GCRoot::new_base(1, -8)];
        let root_vals = vec![0x10040u64];
        r#gen.minor_collect(&roots, &root_vals);
        assert_eq!(r#gen.minor_collections, 1);
    }

    // --- X86GCIncrementalCollector tests ---

    #[test]
    fn test_incremental_new() {
        let inc = X86GCIncrementalCollector::new(0x10000, 1024 * 1024);
        assert_eq!(inc.collections, 0);
        assert!(!inc.marking);
        assert!(!inc.sweeping);
    }

    #[test]
    fn test_incremental_color() {
        let mut inc = X86GCIncrementalCollector::new(0x10000, 1024 * 1024);
        assert_eq!(inc.color(0x10000), X86GCTriColor::White);
        inc.set_color(0x10000, X86GCTriColor::Gray);
        assert_eq!(inc.color(0x10000), X86GCTriColor::Gray);
        inc.set_color(0x10000, X86GCTriColor::Black);
        assert_eq!(inc.color(0x10000), X86GCTriColor::Black);
    }

    #[test]
    fn test_incremental_marking_step() {
        let mut inc = X86GCIncrementalCollector::new(0x10000, 1024 * 1024);
        inc.start_mark(&[0x10000, 0x10040]);
        assert!(inc.marking);
        let complete = inc.marking_step(10);
        // Since we haven't added child pointers, marking should complete
        assert!(complete);
        assert!(!inc.marking);
        assert_eq!(inc.collections, 1);
    }

    #[test]
    fn test_incremental_write_barrier() {
        let mut inc = X86GCIncrementalCollector::new(0x10000, 1024 * 1024);
        inc.start_mark(&[0x10040]);
        inc.set_color(0x10040, X86GCTriColor::Black);
        inc.write_barrier(0x10040, 0x10080);
        assert_eq!(inc.color(0x10080), X86GCTriColor::Gray);
        assert_eq!(inc.write_barriers_applied, 1);
    }

    #[test]
    fn test_incremental_sweeping_step() {
        let mut inc = X86GCIncrementalCollector::new(0x10000, 64 * 1024);
        inc.sweeping = true;
        inc.sweep_cursor = 0x10000;
        let complete = inc.sweeping_step();
        assert!(complete); // Small heap, one step should sweep everything
    }

    // --- X86GCStackMap tests ---

    #[test]
    fn test_stack_map_new() {
        let sm = X86GCStackMap::new();
        assert_eq!(sm.version, 3);
        assert_eq!(sm.functions.len(), 0);
        assert_eq!(sm.records.len(), 0);
    }

    #[test]
    fn test_stack_map_add_function() {
        let mut sm = X86GCStackMap::new();
        let idx = sm.add_function(0x400000, 128);
        assert_eq!(idx, 0);
        assert_eq!(sm.functions.len(), 1);
        assert_eq!(sm.functions[0].function_address, 0x400000);
        assert_eq!(sm.functions[0].stack_size, 128);
    }

    #[test]
    fn test_stack_map_add_record() {
        let mut sm = X86GCStackMap::new();
        let func_idx = sm.add_function(0x400000, 128);

        let record = X86GCStackMapRecord {
            id: 1,
            instruction_offset: 0x10,
            flags: 0,
            locations: vec![X86GCStackMapLocation::new_register(DWARF_REG_RBP, 8)],
            live_outs: vec![],
            function_index: func_idx,
        };
        sm.add_record(record, func_idx);
        assert_eq!(sm.records.len(), 1);
        assert_eq!(sm.functions[0].record_count, 1);
    }

    #[test]
    fn test_stack_map_emit_bytes() {
        let mut sm = X86GCStackMap::new();
        let func_idx = sm.add_function(0x400000, 128);
        let record = X86GCStackMapRecord {
            id: 1,
            instruction_offset: 0x10,
            flags: 0,
            locations: vec![],
            live_outs: vec![],
            function_index: func_idx,
        };
        sm.add_record(record, func_idx);
        let bytes = sm.emit_bytes();
        assert!(!bytes.is_empty());
        assert!(bytes.len() >= 16); // Header + function
    }

    #[test]
    fn test_stack_map_emit_assembly() {
        let mut sm = X86GCStackMap::new();
        sm.add_function(0x400000, 128);
        let asm = sm.emit_assembly();
        assert!(asm.contains(X86_GC_STACK_MAP_SECTION));
        assert!(asm.contains("version"));
    }

    // --- X86GCStackMapLocation tests ---

    #[test]
    fn test_location_register() {
        let loc = X86GCStackMapLocation::new_register(DWARF_REG_RAX, 8);
        assert_eq!(loc.kind, X86GCStackMapLocationKind::Register);
        assert_eq!(loc.dwarf_reg, DWARF_REG_RAX);
    }

    #[test]
    fn test_location_direct() {
        let loc = X86GCStackMapLocation::new_direct(-8, 8);
        assert_eq!(loc.kind, X86GCStackMapLocationKind::Direct);
        assert_eq!(loc.offset, -8);
    }

    #[test]
    fn test_location_kind_from_u8() {
        assert_eq!(
            X86GCStackMapLocationKind::from_u8(1),
            Some(X86GCStackMapLocationKind::Register)
        );
        assert_eq!(
            X86GCStackMapLocationKind::from_u8(2),
            Some(X86GCStackMapLocationKind::Direct)
        );
        assert_eq!(X86GCStackMapLocationKind::from_u8(0), None);
        assert_eq!(X86GCStackMapLocationKind::from_u8(6), None);
    }

    // --- X86GCStackMapGenerator tests ---

    #[test]
    fn test_generator_begin_end_function() {
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test_func", 0x400000);
        assert_eq!(r#gen.current_function_name, Some("test_func".to_string()));
        assert!(r#gen.current_function_index.is_some());
        r#gen.end_function();
        assert!(r#gen.current_function_name.is_none());
    }

    #[test]
    fn test_generator_generate_record() {
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test", 0x400000);

        r#gen.live_var_state.record_register("ptr1", DWARF_REG_RBX, 8);
        r#gen.live_var_state.mark_gc_pointer("ptr1");

        r#gen.advance_offset(0x20);
        let id = r#gen.generate_record(true);
        assert!(id > 0);
        assert_eq!(r#gen.stack_map.records.len(), 1);
        assert_eq!(r#gen.stack_map.records[0].flags, 1); // is_call
    }

    #[test]
    fn test_generator_generate_for_patchpoint() {
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test", 0x400000);
        r#gen.live_var_state.record_register("ptr1", DWARF_REG_R12, 8);
        r#gen.live_var_state.mark_gc_pointer("ptr1");
        r#gen.advance_offset(0x30);
        let id = r#gen.generate_for_patchpoint(100, "target_fn");
        assert!(id > 0);
    }

    #[test]
    fn test_generator_generate_for_statepoint() {
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test", 0x400000);
        r#gen.live_var_state.record_stack("root1", -16, 8);
        r#gen.live_var_state.mark_gc_pointer("root1");
        r#gen.advance_offset(0x40);
        let id = r#gen.generate_for_statepoint(200, "callee_fn", &["root1"]);
        assert!(id > 0);
    }

    #[test]
    fn test_generator_finalize() {
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test", 0x400000);
        r#gen.end_function();
        let sm = r#gen.finalize();
        assert_eq!(sm.functions.len(), 1);
    }

    // --- X86GCLiveVarState tests ---

    #[test]
    fn test_live_var_state_record_register() {
        let mut state = X86GCLiveVarState::new(256);
        state.record_register("x", DWARF_REG_RAX, 8);
        assert!(state.get_location("x").is_some());
    }

    #[test]
    fn test_live_var_state_allocate_stack_slot() {
        let mut state = X86GCLiveVarState::new(256);
        let offset = state.allocate_stack_slot("y", 8);
        assert!(offset < 0);
        assert!(state.get_location("y").is_some());
    }

    #[test]
    fn test_live_var_state_gc_pointers() {
        let mut state = X86GCLiveVarState::new(256);
        state.record_register("gc_ptr", DWARF_REG_RCX, 8);
        state.mark_gc_pointer("gc_ptr");
        assert!(state.is_gc_pointer("gc_ptr"));
        let locs = state.get_gc_pointer_locations();
        assert_eq!(locs.len(), 1);
    }

    // --- X86GCStackMapParser tests ---

    #[test]
    fn test_parser_new() {
        let parser = X86GCStackMapParser::new();
        assert!(!parser.parsed);
        assert_eq!(parser.record_count(), 0);
    }

    #[test]
    fn test_parser_parse_invalid() {
        let mut parser = X86GCStackMapParser::new();
        assert!(!parser.parse(&[0; 4]));
        assert!(!parser.warnings.is_empty());
    }

    #[test]
    fn test_parser_parse_valid_minimal() {
        let mut parser = X86GCStackMapParser::new();
        // Build a minimal valid stack map
        let mut sm = X86GCStackMap::new();
        sm.add_function(0x400000, 128);
        let bytes = sm.emit_bytes();
        assert!(parser.parse(&bytes));
        assert!(parser.parsed);
    }

    #[test]
    fn test_parser_lookup_by_id() {
        let mut sm = X86GCStackMap::new();
        let fi = sm.add_function(0x400000, 128);
        let rec = X86GCStackMapRecord {
            id: 42,
            instruction_offset: 0x10,
            flags: 0,
            locations: vec![],
            live_outs: vec![],
            function_index: fi,
        };
        sm.add_record(rec, fi);
        let bytes = sm.emit_bytes();

        let mut parser = X86GCStackMapParser::new();
        parser.parse(&bytes);
        let found = parser.lookup_by_id(42);
        assert!(found.is_some());
        assert_eq!(found.unwrap().id, 42);
    }

    // --- X86GCSafepoints tests ---

    #[test]
    fn test_safepoints_new() {
        let sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        assert!(sp.enabled);
        assert_eq!(sp.polling_page_address, X86_GC_POLLING_PAGE_ADDR);
        assert_eq!(sp.safepoint_count, 0);
    }

    #[test]
    fn test_safepoints_insert_entry() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test_fn", 0x400000);
        let id = sp.insert_entry_safepoint("test_fn", &mut r#gen);
        assert!(id.is_some());
        assert_eq!(sp.stats.entry_safepoints, 1);
    }

    #[test]
    fn test_safepoints_insert_backedge() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test_fn", 0x400000);
        let id = sp.insert_backedge_safepoint("test_fn", 0x20, &mut r#gen);
        assert!(id.is_some());
        assert_eq!(sp.stats.backedge_safepoints, 1);
    }

    #[test]
    fn test_safepoints_disabled() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        sp.set_enabled(false);
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("test_fn", 0x400000);
        let id = sp.insert_entry_safepoint("test_fn", &mut r#gen);
        assert!(id.is_none());
    }

    #[test]
    fn test_safepoints_generate_poll_bytes() {
        let sp = X86GCSafepoints::new(0x7FFF_FFFF_FFFF_F000);
        let bytes = sp.generate_poll_bytes();
        assert!(!bytes.is_empty());
        // Should be: REX.W + MOV RAX, moffs64
        assert_eq!(bytes[0], 0x48);
        assert_eq!(bytes[1], 0xA1);
    }

    #[test]
    fn test_safepoints_should_insert_backedge() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        sp.configure(true, true, false, 4);
        assert!(sp.should_insert_backedge(0)); // 0 % 4 == 0
        assert!(sp.should_insert_backedge(4)); // 4 % 4 == 0
        assert!(!sp.should_insert_backedge(1)); // 1 % 4 != 0
        assert!(!sp.should_insert_backedge(3)); // 3 % 4 != 0
    }

    #[test]
    fn test_safepoints_reset() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        let mut r#gen = X86GCStackMapGenerator::new();
        r#gen.begin_function("fn", 0x400000);
        sp.insert_entry_safepoint("fn", &mut r#gen);
        sp.reset();
        assert_eq!(sp.safepoint_count, 0);
        assert_eq!(sp.stats.total(), 0);
    }

    #[test]
    fn test_safepoints_record_statepoint() {
        let mut sp = X86GCSafepoints::new(X86_GC_POLLING_PAGE_ADDR);
        sp.record_statepoint("fn", 0x50, 99);
        assert_eq!(sp.stats.statepoint_safepoints, 1);
        let fn_sps = sp.get_function_safepoints("fn");
        assert!(fn_sps.is_some());
        assert_eq!(fn_sps.unwrap().len(), 1);
    }

    // --- X86GCFinalization tests ---

    #[test]
    fn test_finalization_new() {
        let fin = X86GCFinalization::new();
        assert!(fin.enabled);
        assert_eq!(fin.pending_finalizer_count(), 0);
    }

    #[test]
    fn test_finalization_register() {
        let mut fin = X86GCFinalization::new();
        fin.register_finalizer(0x1000, 0x2000, 0);
        assert!(fin.has_finalizer(0x1000));
        assert_eq!(fin.pending_finalizer_count(), 1);
    }

    #[test]
    fn test_finalization_process() {
        let mut fin = X86GCFinalization::new();
        fin.register_finalizer(0x1000, 0x2000, 0);
        fin.register_finalizer(0x2000, 0x3000, 1);
        let processed = fin.process_finalizers(10);
        assert_eq!(processed, 2);
        assert_eq!(fin.total_finalizers_run, 2);
        assert_eq!(fin.pending_finalizer_count(), 0);
    }

    #[test]
    fn test_finalization_double_finalize_prevented() {
        let mut fin = X86GCFinalization::new();
        fin.register_finalizer(0x1000, 0x2000, 0);
        fin.process_finalizers(10);
        // Re-register same object
        fin.register_finalizer(0x1000, 0x2000, 0);
        let processed = fin.process_finalizers(10);
        assert_eq!(processed, 0); // Should be skipped
    }

    #[test]
    fn test_weak_reference_register_and_process() {
        let mut fin = X86GCFinalization::new();
        fin.register_weak_reference(0x5000, 0x6000, true);

        // Simulate marking: 0x6000 is NOT marked
        let cleared = fin.process_weak_references(&|addr| addr != 0x6000);
        assert_eq!(cleared, 1);
        assert_eq!(fin.total_weak_cleared, 1);
    }

    #[test]
    fn test_weak_reference_referent_live() {
        let mut fin = X86GCFinalization::new();
        fin.register_weak_reference(0x5000, 0x6000, true);

        // 0x6000 IS marked
        let cleared = fin.process_weak_references(&|addr| addr == 0x6000);
        assert_eq!(cleared, 0);
    }

    #[test]
    fn test_phantom_reference() {
        let mut fin = X86GCFinalization::new();
        fin.register_phantom_reference(0x7000, 0x8000);
        // Register finalizer so phantom knows the object was finalized
        fin.register_finalizer(0x8000, 0x9000, 0);
        fin.process_finalizers(10);

        let processed = fin.process_phantom_references(&|addr| addr != 0x8000);
        assert_eq!(processed, 1);
    }

    #[test]
    fn test_ephemeron() {
        let mut fin = X86GCFinalization::new();
        fin.register_ephemeron(0xA000, 0xB000);
        // Key IS reachable
        let cleared = fin.process_ephemerons(&|addr| addr == 0xA000);
        assert_eq!(cleared, 0);

        // Reset and test with dead key
        fin.register_ephemeron(0xC000, 0xD000);
        let cleared = fin.process_ephemerons(&|_| false);
        assert_eq!(cleared, 1);
    }

    #[test]
    fn test_finalization_cleanup() {
        let mut fin = X86GCFinalization::new();
        fin.register_weak_reference(0x5000, 0x6000, false);
        fin.process_weak_references(&|_| false);
        fin.cleanup();
        assert!(fin.weak_references.is_empty());
    }

    #[test]
    fn test_finalization_reset() {
        let mut fin = X86GCFinalization::new();
        fin.register_finalizer(0x1000, 0x2000, 0);
        fin.register_weak_reference(0x3000, 0x4000, false);
        fin.reset();
        assert_eq!(fin.pending_finalizer_count(), 0);
        assert!(fin.weak_references.is_empty());
    }

    // --- X86GCCardTable tests ---

    #[test]
    fn test_card_table_new() {
        let ct = X86GCCardTable::new(0x10000, 1024 * 1024, 9);
        assert!(!ct.is_dirty(0x10010));
        assert_eq!(ct.dirty_count(), 0);
    }

    #[test]
    fn test_card_table_mark_and_check() {
        let mut ct = X86GCCardTable::new(0x10000, 1024 * 1024, 9);
        ct.mark_dirty(0x10000);
        assert!(ct.is_dirty(0x10000));
        assert!(ct.is_dirty(0x10100)); // Same card
        assert_eq!(ct.dirty_count(), 1);
    }

    #[test]
    fn test_card_table_clear_card() {
        let mut ct = X86GCCardTable::new(0x10000, 1024 * 1024, 9);
        ct.mark_dirty(0x10000);
        ct.clear_card(0x10000);
        assert!(!ct.is_dirty(0x10000));
    }

    #[test]
    fn test_card_table_clear_all() {
        let mut ct = X86GCCardTable::new(0x10000, 1024 * 1024, 9);
        ct.mark_dirty(0x10000);
        ct.mark_dirty(0x20000);
        ct.clear_all();
        assert_eq!(ct.dirty_count(), 0);
    }

    #[test]
    fn test_card_table_dirty_cards() {
        let mut ct = X86GCCardTable::new(0x10000, 1024 * 1024, 9);
        ct.mark_dirty(0x10000);
        ct.mark_dirty(0x20000);
        let dirty = ct.dirty_cards();
        assert_eq!(dirty.len(), 2);
    }

    // --- X86GCSATBBuffer tests ---

    #[test]
    fn test_satb_buffer_log() {
        let mut buf = X86GCSATBBuffer::new(1024);
        buf.log(0xDEAD);
        buf.log(0xBEEF);
        assert_eq!(buf.entries.len(), 2);
        assert!(!buf.overflowed);
    }

    #[test]
    fn test_satb_buffer_overflow() {
        let mut buf = X86GCSATBBuffer::new(2);
        buf.log(1);
        buf.log(2);
        buf.log(3); // Should overflow
        assert!(buf.overflowed);
    }

    #[test]
    fn test_satb_buffer_drain() {
        let mut buf = X86GCSATBBuffer::new(1024);
        buf.log(0x42);
        let entries = buf.drain();
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0], 0x42);
        assert!(buf.is_empty());
    }

    // --- X86GCFull tests ---

    #[test]
    fn test_gc_full_new() {
        let gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        assert!(gc.is_enabled());
        assert_eq!(gc.gc_cycles(), 0);
    }

    #[test]
    fn test_gc_full_begin_end_function() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.begin_function("test", 0x400000);
        assert_eq!(
            gc.stack_map_generator.current_function_name,
            Some("test".to_string())
        );
        gc.end_function();
        assert!(gc.stack_map_generator.current_function_name.is_none());
    }

    #[test]
    fn test_gc_full_add_root() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.add_root(X86GCRoot::new_base(1, -8));
        assert_eq!(gc.roots.len(), 1);
    }

    #[test]
    fn test_gc_full_add_safepoint() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.begin_function("test", 0x400000);
        let id = gc.add_safepoint("test", 0x20, X86GCSafepointKind::LoopBackedge);
        assert!(id.is_some());
    }

    #[test]
    fn test_gc_full_record_write_barrier() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::CoreCLR,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::Generational,
                ..Default::default()
            },
        );
        gc.record_write_barrier(0x10000, 0x8, 0xDEAD);
        if let Some(ref ct) = gc.card_table {
            assert!(ct.is_dirty(0x10000));
        }
    }

    #[test]
    fn test_gc_full_collect() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                initial_heap_size: 64 * 1024 * 1024,
                ..Default::default()
            },
        );
        gc.add_root(X86GCRoot::new_base(1, -8));
        gc.collect();
        assert_eq!(gc.gc_cycles(), 1);
        assert!(gc.is_enabled());
    }

    #[test]
    fn test_gc_full_allocate() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                initial_heap_size: 1024 * 1024,
                ..Default::default()
            },
        );
        let addr = gc.allocate(64);
        assert_ne!(addr, 0);
        assert!(gc.total_allocated() >= 64);
    }

    #[test]
    fn test_gc_full_disable_enable() {
        let gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        assert!(gc.is_enabled());
        gc.disable();
        assert!(!gc.is_enabled());
        gc.enable();
        assert!(gc.is_enabled());
    }

    #[test]
    fn test_gc_full_validate_empty_roots() {
        let gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                ..Default::default()
            },
        );
        let result = gc.validate();
        assert!(result.is_err());
    }

    #[test]
    fn test_gc_full_validate_with_roots() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                ..Default::default()
            },
        );
        gc.add_root(X86GCRoot::new_base(1, -8));
        let result = gc.validate();
        assert!(result.is_ok());
    }

    #[test]
    fn test_gc_full_finalize_stack_maps() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.begin_function("test", 0x400000);
        gc.end_function();
        let sm = gc.finalize_stack_maps();
        assert_eq!(sm.functions.len(), 1);
    }

    #[test]
    fn test_gc_full_emit_stack_map_bytes() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.begin_function("test", 0x400000);
        gc.end_function();
        let bytes = gc.emit_stack_map_bytes();
        assert!(!bytes.is_empty());
    }

    #[test]
    fn test_gc_full_emit_stack_map_assembly() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());
        gc.begin_function("test", 0x400000);
        gc.end_function();
        let asm = gc.emit_stack_map_assembly();
        assert!(!asm.is_empty());
        assert!(asm.contains(X86_GC_STACK_MAP_SECTION));
    }

    // --- X86GCFrameDescriptor tests (OCaml) ---

    #[test]
    fn test_frame_descriptor_new() {
        let fd = X86GCFrameDescriptor::new(0x400100, 256);
        assert_eq!(fd.return_address, 0x400100);
        assert_eq!(fd.frame_size, 256);
        assert_eq!(fd.num_roots, 0);
        assert!(fd.is_valid);
    }

    #[test]
    fn test_frame_descriptor_add_root() {
        let mut fd = X86GCFrameDescriptor::new(0x400100, 256);
        fd.add_root(0);
        fd.add_root(3);
        assert!(fd.is_root(0));
        assert!(fd.is_root(3));
        assert!(!fd.is_root(1));
        assert_eq!(fd.num_roots, 2);
    }

    #[test]
    fn test_frame_descriptor_root_offsets() {
        let mut fd = X86GCFrameDescriptor::new(0x400100, 256);
        fd.add_root(0);
        fd.add_root(2);
        let offsets = fd.root_offsets();
        assert_eq!(offsets.len(), 2);
        // Slot 0 = offset -8 from RBP, Slot 2 = offset -24 from RBP
        assert!(offsets.contains(&-8));
        assert!(offsets.contains(&-24));
    }

    #[test]
    fn test_frame_descriptor_out_of_range() {
        let mut fd = X86GCFrameDescriptor::new(0x400100, 256);
        fd.add_root(63); // Last valid slot
        assert!(fd.is_root(63));
        fd.add_root(100); // Should be silently ignored
        assert!(!fd.is_root(100));
    }

    // --- X86GCOCamlTable tests ---

    #[test]
    fn test_ocaml_table_add_and_lookup() {
        let mut table = X86GCOCamlTable::new();
        let fd = X86GCFrameDescriptor::new(0x400100, 256);
        table.add_descriptor(fd);
        assert_eq!(table.len(), 1);

        let found = table.lookup(0x400100);
        assert!(found.is_some());
        assert_eq!(found.unwrap().frame_size, 256);
    }

    #[test]
    fn test_ocaml_table_lookup_missing() {
        let table = X86GCOCamlTable::new();
        assert!(table.lookup(0xDEAD).is_none());
    }

    // --- X86GCCoreCLRInfo tests ---

    #[test]
    fn test_coreclr_info_new() {
        let info = X86GCCoreCLRInfo::new(0x400000, 1024);
        assert_eq!(info.version, 2);
        assert!(!info.is_fully_interruptible);
        assert_eq!(info.method_size, 1024);
    }

    #[test]
    fn test_coreclr_info_fully_interruptible() {
        let mut info = X86GCCoreCLRInfo::new(0x400000, 1024);
        info.mark_fully_interruptible();
        assert!(info.is_fully_interruptible);
    }

    #[test]
    fn test_coreclr_info_add_region() {
        let mut info = X86GCCoreCLRInfo::new(0x400000, 1024);
        info.add_region(0x10, 0x50);
        assert_eq!(info.interruptible_regions.len(), 1);
        assert_eq!(info.interruptible_regions[0].start_offset, 0x10);
        assert_eq!(info.interruptible_regions[0].end_offset, 0x50);
    }

    #[test]
    fn test_coreclr_info_add_live_slot() {
        let mut info = X86GCCoreCLRInfo::new(0x400000, 1024);
        info.add_live_slot(-16, false, true);
        assert_eq!(info.live_slots.len(), 1);
        assert!(info.live_slots[0].is_pinned);
        assert!(!info.live_slots[0].is_byref);
    }

    #[test]
    fn test_coreclr_info_encode() {
        let mut info = X86GCCoreCLRInfo::new(0x400000, 512);
        info.add_live_slot(-8, false, false);
        info.add_transition(0x10, 0x10, true);
        let encoded = info.encode();
        assert!(!encoded.is_empty());
        assert_eq!(encoded[0], 2); // version
    }

    // --- LEB128 encoding tests ---

    #[test]
    fn test_uleb128_encode() {
        let mut buf = Vec::new();
        encode_uleb128(&mut buf, 0);
        assert_eq!(buf, vec![0]);

        buf.clear();
        encode_uleb128(&mut buf, 127);
        assert_eq!(buf, vec![127]);

        buf.clear();
        encode_uleb128(&mut buf, 128);
        assert_eq!(buf, vec![0x80, 0x01]);

        buf.clear();
        encode_uleb128(&mut buf, 624485);
        // 624485 = 0x98765 → encoding: E5 8E 26
        assert_eq!(buf.len(), 3);
    }

    #[test]
    fn test_sleb128_encode() {
        let mut buf = Vec::new();
        encode_sleb128(&mut buf, 0);
        assert_eq!(buf, vec![0]);

        buf.clear();
        encode_sleb128(&mut buf, -1);
        assert_eq!(buf, vec![0x7F]);

        buf.clear();
        encode_sleb128(&mut buf, 64);
        assert_eq!(buf, vec![64]);

        buf.clear();
        encode_sleb128(&mut buf, -64);
        assert_eq!(buf, vec![0x40]);
    }

    // --- X86GCFullConfig tests ---

    #[test]
    fn test_config_default() {
        let config = X86GCFullConfig::default();
        assert!(config.emit_stack_maps);
        assert!(config.rewrite_statepoints);
        assert!(!config.concurrent_gc);
        assert_eq!(
            config.collection_algorithm,
            X86GCCollectionAlgorithm::MarkSweep
        );
    }

    #[test]
    fn test_collection_algorithm_display() {
        assert_eq!(format!("{}", X86GCCollectionAlgorithm::Copying), "copying");
        assert_eq!(
            format!("{}", X86GCCollectionAlgorithm::MarkCompact),
            "mark-compact"
        );
        assert_eq!(format!("{}", X86GCCollectionAlgorithm::None), "none");
    }

    // --- Integration test: Full GC cycle ---

    #[test]
    fn test_full_gc_cycle_mark_sweep() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                initial_heap_size: 64 * 1024 * 1024,
                ..Default::default()
            },
        );

        // Register function
        gc.begin_function("allocate_test", 0x400000);

        // Add live root
        gc.add_root(X86GCRoot::new_base(1, -8).with_language(X86GCRootLanguage::Rust));

        // Allocate some objects
        let addr1 = gc.allocate(128);
        let addr2 = gc.allocate(256);
        assert_ne!(addr1, 0);
        assert_ne!(addr2, 0);
        assert!(gc.total_allocated() >= 384);

        // Trigger GC
        gc.collect();
        assert_eq!(gc.gc_cycles(), 1);

        gc.end_function();
    }

    #[test]
    fn test_full_gc_cycle_with_finalization() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::CoreCLR,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                enable_finalization: true,
                process_weak_refs: true,
                initial_heap_size: 64 * 1024 * 1024,
                ..Default::default()
            },
        );

        gc.begin_function("test_with_finalizers", 0x500000);
        gc.add_root(X86GCRoot::new_base(1, -8));

        // Register finalizers
        gc.finalization.register_finalizer(0x1000, 0x2000, 0);
        gc.finalization.register_finalizer(0x3000, 0x2000, 1);

        // Register weak reference
        gc.finalization
            .register_weak_reference(0x7000, 0x8000, true);

        // Allocate and collect
        gc.allocate(128);
        gc.collect();

        // After GC, finalizers should have been processed
        assert_eq!(gc.gc_cycles(), 1);
        assert!(gc.is_enabled());

        gc.end_function();
    }

    #[test]
    fn test_full_gc_cycle_with_safepoints() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::CoreCLR,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::MarkSweep,
                insert_loop_polls: true,
                initial_heap_size: 64 * 1024 * 1024,
                ..Default::default()
            },
        );

        gc.begin_function("test_safepoints", 0x600000);

        // Insert various safepoints
        gc.add_safepoint("test_safepoints", 0x20, X86GCSafepointKind::LoopBackedge);
        gc.add_safepoint("test_safepoints", 0x40, X86GCSafepointKind::LoopBackedge);
        gc.add_safepoint("test_safepoints", 0x60, X86GCSafepointKind::AfterCall);

        let fn_safepoints = gc.safepoints.get_function_safepoints("test_safepoints");
        assert!(fn_safepoints.is_some());
        assert!(fn_safepoints.unwrap().len() >= 3);

        gc.end_function();
    }

    #[test]
    fn test_full_gc_cycle_incremental() {
        let mut gc = X86GCFull::new(
            X86GCStrategy::Statepoint,
            X86GCFullConfig {
                collection_algorithm: X86GCCollectionAlgorithm::Incremental,
                concurrent_gc: true,
                initial_heap_size: 64 * 1024 * 1024,
                ..Default::default()
            },
        );

        gc.begin_function("test_incremental", 0x700000);
        gc.add_root(X86GCRoot::new_base(1, -8));
        gc.allocate(64);

        // Start incremental marking
        match gc.incremental_collector {
            Some(ref mut inc) => {
                inc.start_mark(&[0x10000]);
                assert!(inc.marking);
            }
            None => panic!("Expected incremental collector"),
        }

        // Perform marking steps
        let complete = gc.incremental_marking_step(10);
        assert!(complete);

        // Perform sweeping steps
        let sweep_done = gc.incremental_sweeping_step();
        assert!(sweep_done);

        gc.end_function();
    }

    #[test]
    fn test_full_gc_cycle_stack_map_emission() {
        let mut gc = X86GCFull::new(X86GCStrategy::Statepoint, X86GCFullConfig::default());

        // Simulate multiple functions
        for i in 0..3 {
            gc.begin_function(&format!("func_{}", i), 0x400000 + i * 0x1000);

            gc.stack_map_generator.live_var_state.record_register(
                &format!("ptr_{}", i),
                DWARF_REG_RBX,
                8,
            );
            gc.stack_map_generator
                .live_var_state
                .mark_gc_pointer(&format!("ptr_{}", i));

            gc.stack_map_generator.generate_record(true);
            gc.end_function();
        }

        let sm = gc.finalize_stack_maps();
        assert_eq!(sm.functions.len(), 3);
        assert_eq!(sm.records.len(), 3);

        let bytes = sm.emit_bytes();
        assert!(bytes.len() > 24 * 3); // At least 3 function records

        // Parse and verify
        let mut parser = X86GCStackMapParser::new();
        assert!(parser.parse(&bytes));
        assert_eq!(parser.record_count(), 3);
    }
}