dotscope 0.6.0

//! Fluent API builder for CIL instruction assembly.
//!
//! This module provides a high-level, fluent API for assembling CIL instructions with
//! enhanced ergonomics and type safety. The fluent builder wraps the core instruction
//! encoder while providing convenient methods for common instruction patterns and
//! automatic operand type selection.
//!
//! # Architecture
//!
//! The fluent API is built around the [`InstructionAssembler`] struct, which provides
//! method-specific encoding functions that automatically handle operand types and
//! instruction selection. This approach reduces the verbosity of manual instruction
//! encoding while maintaining full control over the generated bytecode.
//!
//! # Key Components
//!
//! - [`InstructionAssembler`] - Main fluent API for instruction assembly
//! - Automatic operand size optimization (e.g., `ldarg.0` vs `ldarg.s` vs `ldarg`)
//! - Type-safe method signatures that prevent invalid operand combinations
//! - Integration with the label resolution system from the core encoder
//!
//! # Usage Examples
//!
//! ## Basic Instruction Assembly
//!
//! ```rust,no_run
//! use dotscope::assembly::InstructionAssembler;
//!
//! let mut assembler = InstructionAssembler::new();
//!
//! // Arithmetic operations
//! assembler
//!     .ldarg_0()?
//!     .ldarg_1()?
//!     .add()?
//!     .ret()?;
//!
//! let (bytecode, max_stack, handlers) = assembler.finish()?;
//! # Ok::<(), dotscope::Error>(())
//! ```
//!
//! ## Control Flow with Labels
//!
//! ```rust,no_run
//! use dotscope::assembly::InstructionAssembler;
//!
//! let mut assembler = InstructionAssembler::new();
//!
//! assembler
//!     .ldarg_0()?
//!     .brfalse_s("false_case")?
//!     .ldc_i4_1()?
//!     .br_s("end")?
//!     .label("false_case")?
//!     .ldc_i4_0()?
//!     .label("end")?
//!     .ret()?;
//!
//! let (bytecode, max_stack, handlers) = assembler.finish()?;
//! # Ok::<(), dotscope::Error>(())
//! ```
//!
//! ## Method Implementation Example
//!
//! ```rust,no_run
//! use dotscope::assembly::InstructionAssembler;
//!
//! // Simple addition method: int Add(int a, int b) => a + b;
//! let mut assembler = InstructionAssembler::new();
//!
//! assembler
//!     .ldarg_1()? // Load first parameter (a)
//!     .ldarg_2()? // Load second parameter (b)
//!     .add()?     // Add them
//!     .ret()?;    // Return result
//!
//! let (bytecode, max_stack, handlers) = assembler.finish()?;
//! # Ok::<(), dotscope::Error>(())
//! ```

use std::collections::HashMap;

use crate::{
    assembly::{encoder::InstructionEncoder, Immediate, Operand},
    metadata::{
        method::{ExceptionHandler, ExceptionHandlerFlags},
        token::Token,
    },
    Error, Result,
};

/// Types of exception handlers that can be attached to a try block.
#[derive(Debug, Clone)]
enum HandlerKind {
    /// A catch handler that catches a specific exception type.
    /// The token is a TypeDef, TypeRef, or TypeSpec for the exception type.
    Catch(Token),
    /// A filter handler with custom filter logic.
    /// The filter expression evaluates to determine if the handler should run.
    Filter,
    /// A finally handler that always executes.
    Finally,
    /// A fault handler that executes only on exceptions.
    Fault,
}

/// Information about a handler block being built.
#[derive(Debug, Clone)]
struct HandlerInfo {
    /// The kind of handler (catch, filter, finally, fault).
    kind: HandlerKind,
    /// Label marking the start of the handler.
    start_label: String,
    /// Label marking the end of the handler (optional, set when handler ends).
    end_label: Option<String>,
    /// For filter handlers, the label marking the filter expression start.
    filter_label: Option<String>,
}

/// Information about a try block being built.
#[derive(Debug, Clone)]
struct TryBlockInfo {
    /// Label marking the start of the try block.
    start_label: String,
    /// Label marking the end of the try block (set when try block ends).
    end_label: Option<String>,
    /// Handlers attached to this try block.
    handlers: Vec<HandlerInfo>,
}

/// High-level fluent API for assembling CIL instructions.
///
/// This struct provides a convenient, chainable interface for generating CIL bytecode
/// with automatic operand size optimization and type safety. It wraps the core
/// [`InstructionEncoder`] while providing specialized methods for common instruction
/// patterns used in .NET method bodies.
///
/// # Design Philosophy
///
/// The fluent API prioritizes:
/// - **Ergonomics**: Method names match CIL mnemonics for familiarity
/// - **Type Safety**: Invalid operand combinations are prevented at compile time
/// - **Optimization**: Automatic selection of the most efficient instruction encoding
/// - **Completeness**: Coverage of all commonly used CIL instructions
///
/// # Automatic Optimizations
///
/// The assembler automatically selects the most efficient instruction encodings:
/// - `ldarg_0()` through `ldarg_3()` use single-byte opcodes when possible
/// - `ldarg_s(index)` uses short form for indices 0-255
/// - `ldarg(index)` uses full form for larger indices
/// - Similar optimizations apply to `ldloc`, `stloc`, `starg`, and constant loading
///
/// # Examples
///
/// ## Simple Method Body
///
/// ```rust,no_run
/// use dotscope::assembly::InstructionAssembler;
///
/// // Generate: return arg0 + arg1;
/// let mut asm = InstructionAssembler::new();
/// asm.ldarg_0()?
///    .ldarg_1()?
///    .add()?
///    .ret()?;
///
/// let (bytecode, max_stack, handlers) = asm.finish()?;
/// # Ok::<(), dotscope::Error>(())
/// ```
///
/// ## Conditional Logic
///
/// ```rust,no_run
/// use dotscope::assembly::InstructionAssembler;
///
/// // Generate: return arg0 > 0 ? 1 : 0;
/// let mut asm = InstructionAssembler::new();
/// asm.ldarg_0()?
///    .ldc_i4_0()?
///    .bgt_s("positive")?
///    .ldc_i4_0()?
///    .ret()?
///    .label("positive")?
///    .ldc_i4_1()?
///    .ret()?;
///
/// let (bytecode, max_stack, handlers) = asm.finish()?;
/// # Ok::<(), dotscope::Error>(())
/// ```
pub struct InstructionAssembler {
    /// Core encoder for instruction generation with built-in stack tracking
    encoder: InstructionEncoder,
    /// Try blocks being built, keyed by their name
    try_blocks: HashMap<String, TryBlockInfo>,
    /// Counter for generating unique internal labels
    label_counter: u32,
}

impl InstructionAssembler {
    /// Create a new instruction assembler.
    ///
    /// Initializes a fresh assembler ready for instruction emission. The assembler
    /// maintains internal state for bytecode generation and label resolution.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut assembler = InstructionAssembler::new();
    /// // Ready for instruction assembly
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    #[must_use]
    pub fn new() -> Self {
        Self {
            encoder: InstructionEncoder::new(),
            try_blocks: HashMap::new(),
            label_counter: 0,
        }
    }

    /// Finalize assembly and return the complete bytecode with stack and handler info.
    ///
    /// This method completes the assembly process by resolving all label references,
    /// generating the final CIL bytecode, and building exception handler metadata
    /// from any try/catch/finally blocks defined using the structured API.
    ///
    /// # Returns
    ///
    /// A tuple containing:
    /// - The complete CIL bytecode with all labels resolved
    /// - The maximum stack depth required during execution
    /// - Exception handlers built from structured try/catch/finally blocks (empty if none)
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Any referenced labels are undefined
    /// - Branch offsets exceed the allowed range for their instruction type
    /// - Stack underflow occurred during assembly (negative stack depth)
    /// - Exception handlers are incomplete (missing end labels)
    ///
    /// # Examples
    ///
    /// ## Simple method without exception handlers
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut assembler = InstructionAssembler::new();
    /// assembler.ldc_i4_1()?.ret()?; // Pushes 1, then returns
    ///
    /// let (bytecode, max_stack, handlers) = assembler.finish()?;
    /// assert_eq!(bytecode, vec![0x17, 0x2A]); // ldc.i4.1, ret
    /// assert_eq!(max_stack, 1); // Maximum stack depth was 1
    /// assert!(handlers.is_empty()); // No exception handlers
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// ## Method with try/catch
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    /// use dotscope::metadata::token::Token;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// let exception_type = Token::new(0x01000001); // TypeRef for System.Exception
    ///
    /// asm.try_start("my_try")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("my_try")?
    ///     .catch_start("my_try", exception_type)?
    ///     .pop()?  // Pop the exception object
    ///     .ldc_i4_0()?
    ///     .leave_s("end")?
    ///     .catch_end("my_try")?
    ///     .label("end")?
    ///     .ret()?;
    ///
    /// let (bytecode, max_stack, handlers) = asm.finish()?;
    /// assert_eq!(handlers.len(), 1);
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn finish(self) -> Result<(Vec<u8>, u16, Vec<ExceptionHandler>)> {
        // Finalize encoder and get label positions
        let (bytecode, max_stack, labels) = self.encoder.finalize()?;

        // Build exception handlers from try block info
        let mut handlers = Vec::new();
        for try_block in self.try_blocks.values() {
            let try_start = labels
                .get(&try_block.start_label)
                .ok_or_else(|| Error::UndefinedLabel(try_block.start_label.clone()))?;
            let try_end_label = try_block
                .end_label
                .as_ref()
                .ok_or_else(|| malformed_error!("Try block has no end label"))?;
            let try_end = labels
                .get(try_end_label)
                .ok_or_else(|| Error::UndefinedLabel(try_end_label.clone()))?;

            for handler in &try_block.handlers {
                let handler_start = labels
                    .get(&handler.start_label)
                    .ok_or_else(|| Error::UndefinedLabel(handler.start_label.clone()))?;
                let handler_end_label = handler
                    .end_label
                    .as_ref()
                    .ok_or_else(|| malformed_error!("Handler has no end label"))?;
                let handler_end = labels
                    .get(handler_end_label)
                    .ok_or_else(|| Error::UndefinedLabel(handler_end_label.clone()))?;

                let (flags, filter_offset, class_token) = match &handler.kind {
                    HandlerKind::Catch(token) => {
                        (ExceptionHandlerFlags::EXCEPTION, token.value(), None)
                    }
                    HandlerKind::Filter => {
                        let filter_label = handler.filter_label.as_ref().ok_or_else(|| {
                            malformed_error!("Filter handler has no filter label")
                        })?;
                        let filter_offset = labels
                            .get(filter_label)
                            .ok_or_else(|| Error::UndefinedLabel(filter_label.clone()))?;
                        (ExceptionHandlerFlags::FILTER, *filter_offset, None)
                    }
                    HandlerKind::Finally => (ExceptionHandlerFlags::FINALLY, 0, None),
                    HandlerKind::Fault => (ExceptionHandlerFlags::FAULT, 0, None),
                };

                handlers.push(ExceptionHandler {
                    flags,
                    try_offset: *try_start,
                    try_length: try_end - try_start,
                    handler_offset: *handler_start,
                    handler_length: handler_end - handler_start,
                    handler: class_token,
                    filter_offset,
                });
            }
        }

        Ok((bytecode, max_stack, handlers))
    }

    /// Get the current maximum stack depth without finalizing the assembly.
    ///
    /// This method allows checking the maximum stack depth that has been reached
    /// so far during assembly without consuming the assembler.
    ///
    /// # Returns
    ///
    /// The maximum stack depth reached so far during instruction assembly.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut assembler = InstructionAssembler::new();
    /// assembler.ldc_i4_1()?; // Pushes 1 item
    /// assert_eq!(assembler.max_stack_depth(), 1);
    ///
    /// assembler.ldc_i4_2()?; // Pushes another item
    /// assert_eq!(assembler.max_stack_depth(), 2);
    ///
    /// assembler.add()?; // Pops 2, pushes 1 (net: -1)
    /// assert_eq!(assembler.max_stack_depth(), 2); // Max is still 2
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    #[must_use]
    pub fn max_stack_depth(&self) -> u16 {
        self.encoder.max_stack_depth()
    }

    /// Get the current stack depth without finalizing the assembly.
    ///
    /// This method returns the current number of items on the evaluation stack.
    /// Useful for debugging or validation during assembly.
    ///
    /// # Returns
    ///
    /// The current stack depth (number of items on evaluation stack).
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut assembler = InstructionAssembler::new();
    /// assert_eq!(assembler.current_stack_depth(), 0);
    ///
    /// assembler.ldc_i4_1()?; // Pushes 1 item
    /// assert_eq!(assembler.current_stack_depth(), 1);
    ///
    /// assembler.ldc_i4_2()?; // Pushes another item
    /// assert_eq!(assembler.current_stack_depth(), 2);
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    #[must_use]
    pub fn current_stack_depth(&self) -> i16 {
        self.encoder.current_stack_depth()
    }

    /// Get the position of a defined label.
    ///
    /// This method allows accessing label positions before finalization,
    /// which is useful for exception handler offset calculation.
    ///
    /// # Parameters
    ///
    /// * `label_name` - The name of the label to look up
    ///
    /// # Returns
    ///
    /// The byte position of the label if it exists, otherwise None.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.nop()?.label("test_label")?;
    ///
    /// if let Some(position) = asm.get_label_position("test_label") {
    ///     println!("Label 'test_label' is at byte position {}", position);
    /// }
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    #[must_use]
    pub fn get_label_position(&self, label_name: &str) -> Option<u32> {
        self.encoder.get_label_position(label_name)
    }

    /// Define a label at the current position.
    ///
    /// Labels mark positions in the bytecode that can be referenced by branch
    /// instructions. Each label must have a unique name within the assembler scope.
    ///
    /// # Parameters
    ///
    /// * `name` - Unique label name
    ///
    /// # Errors
    ///
    /// Returns an error if a label with the same name has already been defined.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.nop()?
    ///    .label("loop_start")?
    ///    .ldarg_0()?
    ///    .br_s("loop_start")?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn label(&mut self, name: &str) -> Result<&mut Self> {
        self.encoder.define_label(name)?;
        Ok(self)
    }

    /// Generate a unique internal label name.
    fn generate_label(&mut self, prefix: &str) -> String {
        self.label_counter += 1;
        format!("__{}_{}", prefix, self.label_counter)
    }

    /// Start a try block with the given name.
    ///
    /// This marks the beginning of a protected region. The try block must be
    /// ended with [`try_end`](Self::try_end) before adding handlers.
    ///
    /// # Parameters
    ///
    /// * `name` - Unique name for this try block (used to attach handlers)
    ///
    /// # Errors
    ///
    /// Returns an error if a try block with the same name already exists.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    /// use dotscope::metadata::token::Token;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// let exception_type = Token::new(0x01000001);
    ///
    /// asm.try_start("my_try")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("my_try")?
    ///     .catch_start("my_try", exception_type)?
    ///     .pop()?
    ///     .ldc_i4_0()?
    ///     .leave_s("end")?
    ///     .catch_end("my_try")?
    ///     .label("end")?
    ///     .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn try_start(&mut self, name: &str) -> Result<&mut Self> {
        if self.try_blocks.contains_key(name) {
            return Err(malformed_error!("Try block '{}' already exists", name));
        }

        let start_label = self.generate_label(&format!("try_{name}_start"));
        self.encoder.define_label(&start_label)?;

        self.try_blocks.insert(
            name.to_string(),
            TryBlockInfo {
                start_label,
                end_label: None,
                handlers: Vec::new(),
            },
        );

        Ok(self)
    }

    /// End a try block.
    ///
    /// This marks the end of the protected region. After calling this, you can
    /// attach handlers using [`catch_start`](Self::catch_start),
    /// [`finally_start`](Self::finally_start), [`fault_start`](Self::fault_start),
    /// or [`filter_start`](Self::filter_start).
    ///
    /// # Parameters
    ///
    /// * `name` - The name of the try block to end
    ///
    /// # Errors
    ///
    /// Returns an error if the try block doesn't exist or was already ended.
    pub fn try_end(&mut self, name: &str) -> Result<&mut Self> {
        // Check that try block exists and is not already ended
        {
            let try_block = self
                .try_blocks
                .get(name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", name))?;

            if try_block.end_label.is_some() {
                return Err(malformed_error!("Try block '{}' already ended", name));
            }
        }

        // Generate label and define it (requires mutable self)
        let end_label = self.generate_label(&format!("try_{name}_end"));
        self.encoder.define_label(&end_label)?;

        // Update try block with end label
        if let Some(try_block) = self.try_blocks.get_mut(name) {
            try_block.end_label = Some(end_label);
        }

        Ok(self)
    }

    /// Start a catch handler for a try block.
    ///
    /// The catch handler catches exceptions of the specified type. At the start
    /// of a catch handler, the CLR pushes the exception object onto the stack,
    /// so the stack depth is automatically bumped by 1.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block this handler belongs to
    /// * `exception_type` - Token for the exception type to catch (TypeDef/TypeRef/TypeSpec)
    ///
    /// # Errors
    ///
    /// Returns an error if the try block doesn't exist or hasn't been ended.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    /// use dotscope::metadata::token::Token;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// let exception_type = Token::new(0x01000001);
    ///
    /// asm.try_start("try1")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("try1")?
    ///     .catch_start("try1", exception_type)?
    ///     // Exception object is on the stack here
    ///     .pop()?  // Remove it if not needed
    ///     .ldc_i4_m1()?
    ///     .leave_s("end")?
    ///     .catch_end("try1")?
    ///     .label("end")?
    ///     .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn catch_start(&mut self, try_name: &str, exception_type: Token) -> Result<&mut Self> {
        // Check that try block exists and is ended
        {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            if try_block.end_label.is_none() {
                return Err(malformed_error!(
                    "Try block '{}' must be ended before adding handlers",
                    try_name
                ));
            }
        }

        // Generate label and set up stack (requires mutable self)
        let start_label = self.generate_label(&format!("catch_{try_name}"));
        self.encoder.define_label(&start_label)?;

        // Catch handlers have the exception object pushed by the CLR
        // Set stack depth to 1 at this label
        self.encoder.set_stack_depth(1);
        self.encoder.set_label_stack_depth(&start_label, 1);

        // Add handler to try block
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers.push(HandlerInfo {
                kind: HandlerKind::Catch(exception_type),
                start_label,
                end_label: None,
                filter_label: None,
            });
        }

        Ok(self)
    }

    /// End a catch handler.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block whose catch handler to end
    ///
    /// # Errors
    ///
    /// Returns an error if no catch handler is active for this try block.
    pub fn catch_end(&mut self, try_name: &str) -> Result<&mut Self> {
        // Find the handler index (immutable borrow)
        let handler_idx = {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            try_block
                .handlers
                .iter()
                .enumerate()
                .rev()
                .find(|(_, h)| matches!(h.kind, HandlerKind::Catch(_)) && h.end_label.is_none())
                .map(|(i, _)| i)
                .ok_or_else(|| {
                    malformed_error!("No active catch handler for try block '{}'", try_name)
                })?
        };

        // Generate label (requires mutable self)
        let end_label = self.generate_label(&format!("catch_{try_name}_end"));
        self.encoder.define_label(&end_label)?;

        // Update handler (mutable borrow)
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers[handler_idx].end_label = Some(end_label);
        }

        Ok(self)
    }

    /// Start a finally handler for a try block.
    ///
    /// Finally handlers always execute, whether the try block completes normally
    /// or throws an exception. Finally handlers do not have the exception object
    /// on the stack - they execute with an empty evaluation stack.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block this handler belongs to
    ///
    /// # Errors
    ///
    /// Returns an error if the try block doesn't exist or hasn't been ended.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    ///
    /// asm.try_start("try1")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("try1")?
    ///     .finally_start("try1")?
    ///     // Cleanup code here - stack is empty
    ///     .endfinally()?
    ///     .finally_end("try1")?
    ///     .label("end")?
    ///     .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn finally_start(&mut self, try_name: &str) -> Result<&mut Self> {
        // Check that try block exists and is ended
        {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            if try_block.end_label.is_none() {
                return Err(malformed_error!(
                    "Try block '{}' must be ended before adding handlers",
                    try_name
                ));
            }
        }

        // Generate label and set up stack (requires mutable self)
        let start_label = self.generate_label(&format!("finally_{try_name}"));
        self.encoder.define_label(&start_label)?;

        // Finally handlers have an empty stack
        self.encoder.set_stack_depth(0);
        self.encoder.set_label_stack_depth(&start_label, 0);

        // Add handler to try block
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers.push(HandlerInfo {
                kind: HandlerKind::Finally,
                start_label,
                end_label: None,
                filter_label: None,
            });
        }

        Ok(self)
    }

    /// End a finally handler.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block whose finally handler to end
    ///
    /// # Errors
    ///
    /// Returns an error if no finally handler is active for this try block.
    pub fn finally_end(&mut self, try_name: &str) -> Result<&mut Self> {
        // Find the handler index (immutable borrow)
        let handler_idx = {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            try_block
                .handlers
                .iter()
                .enumerate()
                .rev()
                .find(|(_, h)| matches!(h.kind, HandlerKind::Finally) && h.end_label.is_none())
                .map(|(i, _)| i)
                .ok_or_else(|| {
                    malformed_error!("No active finally handler for try block '{}'", try_name)
                })?
        };

        // Generate label (requires mutable self)
        let end_label = self.generate_label(&format!("finally_{try_name}_end"));
        self.encoder.define_label(&end_label)?;

        // Update handler (mutable borrow)
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers[handler_idx].end_label = Some(end_label);
        }

        Ok(self)
    }

    /// Start a fault handler for a try block.
    ///
    /// Fault handlers only execute when an exception is thrown. Like finally
    /// handlers, they do not have the exception object on the stack.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block this handler belongs to
    ///
    /// # Errors
    ///
    /// Returns an error if the try block doesn't exist or hasn't been ended.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    ///
    /// asm.try_start("try1")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("try1")?
    ///     .fault_start("try1")?
    ///     // Error cleanup code here - only runs on exception
    ///     .endfinally()?  // Note: endfinally is used for both finally and fault
    ///     .fault_end("try1")?
    ///     .label("end")?
    ///     .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn fault_start(&mut self, try_name: &str) -> Result<&mut Self> {
        // Check that try block exists and is ended
        {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            if try_block.end_label.is_none() {
                return Err(malformed_error!(
                    "Try block '{}' must be ended before adding handlers",
                    try_name
                ));
            }
        }

        // Generate label and set up stack (requires mutable self)
        let start_label = self.generate_label(&format!("fault_{try_name}"));
        self.encoder.define_label(&start_label)?;

        // Fault handlers have an empty stack
        self.encoder.set_stack_depth(0);
        self.encoder.set_label_stack_depth(&start_label, 0);

        // Add handler to try block
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers.push(HandlerInfo {
                kind: HandlerKind::Fault,
                start_label,
                end_label: None,
                filter_label: None,
            });
        }

        Ok(self)
    }

    /// End a fault handler.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block whose fault handler to end
    ///
    /// # Errors
    ///
    /// Returns an error if no fault handler is active for this try block.
    pub fn fault_end(&mut self, try_name: &str) -> Result<&mut Self> {
        // Find the handler index (immutable borrow)
        let handler_idx = {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            try_block
                .handlers
                .iter()
                .enumerate()
                .rev()
                .find(|(_, h)| matches!(h.kind, HandlerKind::Fault) && h.end_label.is_none())
                .map(|(i, _)| i)
                .ok_or_else(|| {
                    malformed_error!("No active fault handler for try block '{}'", try_name)
                })?
        };

        // Generate label (requires mutable self)
        let end_label = self.generate_label(&format!("fault_{try_name}_end"));
        self.encoder.define_label(&end_label)?;

        // Update handler (mutable borrow)
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers[handler_idx].end_label = Some(end_label);
        }

        Ok(self)
    }

    /// Start a filter handler for a try block.
    ///
    /// Filter handlers use custom logic to determine whether to handle an exception.
    /// At the filter expression entry, the exception object is on the stack.
    /// The filter expression must leave a value on the stack (non-zero to handle,
    /// zero to continue searching). Use [`endfilter`](Self::endfilter) to end the
    /// filter expression, then the actual handler code follows.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block this handler belongs to
    ///
    /// # Errors
    ///
    /// Returns an error if the try block doesn't exist or hasn't been ended.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    ///
    /// asm.try_start("try1")?
    ///     .ldarg_0()?
    ///     .leave_s("end")?
    ///     .try_end("try1")?
    ///     .filter_start("try1")?
    ///     // Filter expression: exception object is on stack
    ///     .pop()?  // Pop exception, push filter decision
    ///     .ldc_i4_1()?  // Always handle (return true)
    ///     .filter_handler("try1")?  // End filter, start handler
    ///     // Handler code: exception object is on stack again
    ///     .pop()?
    ///     .ldc_i4_m1()?
    ///     .leave_s("end")?
    ///     .filter_end("try1")?
    ///     .label("end")?
    ///     .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn filter_start(&mut self, try_name: &str) -> Result<&mut Self> {
        // Check that try block exists and is ended
        {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            if try_block.end_label.is_none() {
                return Err(malformed_error!(
                    "Try block '{}' must be ended before adding handlers",
                    try_name
                ));
            }
        }

        // Generate label and set up stack (requires mutable self)
        let filter_label = self.generate_label(&format!("filter_{try_name}"));
        self.encoder.define_label(&filter_label)?;

        // Filter expression entry: exception object is on stack
        self.encoder.set_stack_depth(1);
        self.encoder.set_label_stack_depth(&filter_label, 1);

        // Add handler to try block
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers.push(HandlerInfo {
                kind: HandlerKind::Filter,
                start_label: String::new(), // Will be set in filter_handler
                end_label: None,
                filter_label: Some(filter_label),
            });
        }

        Ok(self)
    }

    /// End filter expression and start the handler code.
    ///
    /// This method emits the `endfilter` instruction and marks the start of
    /// the actual handler code. At this point, the exception object is pushed
    /// onto the stack again.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block whose filter handler to transition
    ///
    /// # Errors
    ///
    /// Returns an error if no filter handler is active for this try block.
    pub fn filter_handler(&mut self, try_name: &str) -> Result<&mut Self> {
        // Emit endfilter instruction (pops the filter result)
        self.encoder.emit_instruction("endfilter", None)?;

        // Find the handler index (immutable borrow)
        let handler_idx = {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            try_block
                .handlers
                .iter()
                .enumerate()
                .rev()
                .find(|(_, h)| matches!(h.kind, HandlerKind::Filter) && h.start_label.is_empty())
                .map(|(i, _)| i)
                .ok_or_else(|| {
                    malformed_error!("No active filter expression for try block '{}'", try_name)
                })?
        };

        // Generate label and set up stack (requires mutable self)
        let start_label = self.generate_label(&format!("filter_{try_name}_handler"));
        self.encoder.define_label(&start_label)?;

        // Handler entry: exception object is on stack again
        self.encoder.set_stack_depth(1);
        self.encoder.set_label_stack_depth(&start_label, 1);

        // Update handler (mutable borrow)
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers[handler_idx].start_label = start_label;
        }

        Ok(self)
    }

    /// End a filter handler.
    ///
    /// # Parameters
    ///
    /// * `try_name` - The name of the try block whose filter handler to end
    ///
    /// # Errors
    ///
    /// Returns an error if no filter handler is active for this try block.
    pub fn filter_end(&mut self, try_name: &str) -> Result<&mut Self> {
        // Find the handler index (immutable borrow)
        let handler_idx = {
            let try_block = self
                .try_blocks
                .get(try_name)
                .ok_or_else(|| malformed_error!("Try block '{}' not found", try_name))?;

            try_block
                .handlers
                .iter()
                .enumerate()
                .rev()
                .find(|(_, h)| {
                    matches!(h.kind, HandlerKind::Filter)
                        && !h.start_label.is_empty()
                        && h.end_label.is_none()
                })
                .map(|(i, _)| i)
                .ok_or_else(|| {
                    malformed_error!("No active filter handler for try block '{}'", try_name)
                })?
        };

        // Generate label (requires mutable self)
        let end_label = self.generate_label(&format!("filter_{try_name}_end"));
        self.encoder.define_label(&end_label)?;

        // Update handler (mutable borrow)
        if let Some(try_block) = self.try_blocks.get_mut(try_name) {
            try_block.handlers[handler_idx].end_label = Some(end_label);
        }

        Ok(self)
    }

    /// Check if a try block with the given name exists.
    ///
    /// # Parameters
    ///
    /// * `name` - The name of the try block to check
    ///
    /// # Returns
    ///
    /// `true` if a try block with the given name exists, `false` otherwise.
    #[must_use]
    pub fn has_try_block(&self, name: &str) -> bool {
        self.try_blocks.contains_key(name)
    }

    /// Get the number of handlers attached to a try block.
    ///
    /// # Parameters
    ///
    /// * `name` - The name of the try block
    ///
    /// # Returns
    ///
    /// The number of handlers, or 0 if the try block doesn't exist.
    #[must_use]
    pub fn handler_count(&self, name: &str) -> usize {
        self.try_blocks.get(name).map_or(0, |tb| tb.handlers.len())
    }

    /// Emit a NOP (no operation) instruction.
    ///
    /// The NOP instruction performs no operation and advances to the next instruction.
    /// It's commonly used for padding, debugging, or placeholder purposes.
    ///
    /// **Opcode**: `0x00`
    /// **Stack**: `... → ...` (no change)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.nop()?.ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn nop(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("nop", None)?;
        Ok(self)
    }

    /// Emit a RET (return) instruction.
    ///
    /// The RET instruction returns from the current method, optionally returning
    /// a value if the method signature specifies a return type.
    ///
    /// **Opcode**: `0x2A`
    /// **Stack**: `retVal → ...` (if returning value) or `... → ...` (if void)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// // Void method
    /// let mut asm = InstructionAssembler::new();
    /// asm.ret()?;
    ///
    /// // Method returning a value
    /// let mut asm2 = InstructionAssembler::new();
    /// asm2.ldc_i4_const(42)?.ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn ret(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ret", None)?;
        Ok(self)
    }

    /// Load argument 0 onto the stack.
    ///
    /// This is an optimized single-byte instruction for loading the first argument
    /// (typically 'this' in instance methods, or the first parameter in static methods).
    ///
    /// **Opcode**: `0x02`
    /// **Stack**: `... → ..., arg0`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldarg_0()?.ret()?; // Return first argument
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn ldarg_0(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldarg.0", None)?;
        Ok(self)
    }

    /// Load argument 1 onto the stack.
    ///
    /// Optimized single-byte instruction for loading the second argument.
    ///
    /// **Opcode**: `0x03`
    /// **Stack**: `... → ..., arg1`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg_1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldarg.1", None)?;
        Ok(self)
    }

    /// Load argument 2 onto the stack.
    ///
    /// Optimized single-byte instruction for loading the third argument.
    ///
    /// **Opcode**: `0x04`
    /// **Stack**: `... → ..., arg2`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg_2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldarg.2", None)?;
        Ok(self)
    }

    /// Load argument 3 onto the stack.
    ///
    /// Optimized single-byte instruction for loading the fourth argument.
    ///
    /// **Opcode**: `0x05`
    /// **Stack**: `... → ..., arg3`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg_3(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldarg.3", None)?;
        Ok(self)
    }

    /// Load argument by index (short form).
    ///
    /// Load an argument by its index using the short form instruction, which
    /// uses a single byte for the index (0-127 due to signed byte encoding).
    ///
    /// **Opcode**: `0x0E`
    /// **Stack**: `... → ..., argN`
    ///
    /// # Parameters
    ///
    /// * `index` - Argument index (0-127)
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldarg_s(5)?.ret()?; // Load argument 5
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg_s(&mut self, index: u8) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldarg.s", Some(Operand::Immediate(Immediate::UInt8(index))))?;
        Ok(self)
    }

    /// Load argument by index (full form).
    ///
    /// Load an argument by its index using the full form instruction, which
    /// supports the complete range of argument indices (0-65535).
    ///
    /// **Opcode**: `0xFE 0x09`
    /// **Stack**: `... → ..., argN`
    ///
    /// # Parameters
    ///
    /// * `index` - Argument index (0-65535)
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldarg(1000)?.ret()?; // Load argument 1000
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg(&mut self, index: i16) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldarg", Some(Operand::Immediate(Immediate::Int16(index))))?;
        Ok(self)
    }

    /// Store a value into an argument (short form).
    ///
    /// Store the value from the top of the stack into the specified argument slot.
    /// This is the short form instruction supporting argument indices 0-127.
    ///
    /// **Opcode**: `0x10`
    /// **Stack**: `..., value → ...`
    ///
    /// # Parameters
    ///
    /// * `index` - Argument index (0-127, but encoded as signed i8)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn starg_s(&mut self, index: u8) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("starg.s", Some(Operand::Immediate(Immediate::UInt8(index))))?;
        Ok(self)
    }

    /// Store a value into an argument (full form).
    ///
    /// Store the value from the top of the stack into the specified argument slot.
    /// This is the full form instruction supporting the complete range of
    /// argument indices (0-65535).
    ///
    /// **Opcode**: `0xFE 0x0B`
    /// **Stack**: `..., value → ...`
    ///
    /// # Parameters
    ///
    /// * `index` - Argument index (0-65535)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn starg(&mut self, index: i16) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("starg", Some(Operand::Immediate(Immediate::Int16(index))))?;
        Ok(self)
    }

    /// Load local variable 0 onto the stack.
    ///
    /// Optimized single-byte instruction for loading the first local variable.
    ///
    /// **Opcode**: `0x06`
    /// **Stack**: `... → ..., local0`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_0(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldloc.0", None)?;
        Ok(self)
    }

    /// Load local variable 1 onto the stack.
    ///
    /// **Opcode**: `0x07`
    /// **Stack**: `... → ..., local1`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldloc.1", None)?;
        Ok(self)
    }

    /// Load local variable 2 onto the stack.
    ///
    /// **Opcode**: `0x08`
    /// **Stack**: `... → ..., local2`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldloc.2", None)?;
        Ok(self)
    }

    /// Load local variable 3 onto the stack.
    ///
    /// **Opcode**: `0x09`
    /// **Stack**: `... → ..., local3`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_3(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldloc.3", None)?;
        Ok(self)
    }

    /// Load local variable by index (short form).
    ///
    /// **Opcode**: `0x11`
    /// **Stack**: `... → ..., localN`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_s(&mut self, index: u8) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldloc.s", Some(Operand::Immediate(Immediate::UInt8(index))))?;
        Ok(self)
    }

    /// Load local variable by index (full form).
    ///
    /// **Opcode**: `0xFE 0x0C`
    /// **Stack**: `... → ..., localN`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc(&mut self, index: i16) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldloc", Some(Operand::Immediate(Immediate::Int16(index))))?;
        Ok(self)
    }

    /// Store value into local variable 0.
    ///
    /// **Opcode**: `0x0A`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_0(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("stloc.0", None)?;
        Ok(self)
    }

    /// Store value into local variable 1.
    ///
    /// **Opcode**: `0x0B`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("stloc.1", None)?;
        Ok(self)
    }

    /// Store value into local variable 2.
    ///
    /// **Opcode**: `0x0C`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("stloc.2", None)?;
        Ok(self)
    }

    /// Store value into local variable 3.
    ///
    /// **Opcode**: `0x0D`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_3(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("stloc.3", None)?;
        Ok(self)
    }

    /// Store value into local variable by index (short form).
    ///
    /// **Opcode**: `0x13`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_s(&mut self, index: u8) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("stloc.s", Some(Operand::Immediate(Immediate::UInt8(index))))?;
        Ok(self)
    }

    /// Store value into local variable by index (full form).
    ///
    /// **Opcode**: `0xFE 0x0E`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc(&mut self, index: i16) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("stloc", Some(Operand::Immediate(Immediate::Int16(index))))?;
        Ok(self)
    }

    /// Load constant -1 onto the stack.
    ///
    /// **Opcode**: `0x15`
    /// **Stack**: `... → ..., -1`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_m1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.m1", None)?;
        Ok(self)
    }

    /// Load constant 0 onto the stack.
    ///
    /// **Opcode**: `0x16`
    /// **Stack**: `... → ..., 0`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_0(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.0", None)?;
        Ok(self)
    }

    /// Load constant 1 onto the stack.
    ///
    /// **Opcode**: `0x17`
    /// **Stack**: `... → ..., 1`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.1", None)?;
        Ok(self)
    }

    /// Load constant 2 onto the stack.
    ///
    /// **Opcode**: `0x18`
    /// **Stack**: `... → ..., 2`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.2", None)?;
        Ok(self)
    }

    /// Load constant 3 onto the stack.
    ///
    /// **Opcode**: `0x19`
    /// **Stack**: `... → ..., 3`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_3(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.3", None)?;
        Ok(self)
    }

    /// Load constant 4 onto the stack.
    ///
    /// **Opcode**: `0x1A`
    /// **Stack**: `... → ..., 4`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.4", None)?;
        Ok(self)
    }

    /// Load constant 5 onto the stack.
    ///
    /// **Opcode**: `0x1B`
    /// **Stack**: `... → ..., 5`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_5(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.5", None)?;
        Ok(self)
    }

    /// Load constant 6 onto the stack.
    ///
    /// **Opcode**: `0x1C`
    /// **Stack**: `... → ..., 6`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_6(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.6", None)?;
        Ok(self)
    }

    /// Load constant 7 onto the stack.
    ///
    /// **Opcode**: `0x1D`
    /// **Stack**: `... → ..., 7`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_7(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.7", None)?;
        Ok(self)
    }

    /// Load constant 8 onto the stack.
    ///
    /// **Opcode**: `0x1E`
    /// **Stack**: `... → ..., 8`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_8(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldc.i4.8", None)?;
        Ok(self)
    }

    /// Load a small constant using the short form.
    ///
    /// **Opcode**: `0x1F`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_s(&mut self, value: i8) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldc.i4.s", Some(Operand::Immediate(Immediate::Int8(value))))?;
        Ok(self)
    }

    /// Load a 32-bit integer constant.
    ///
    /// **Opcode**: `0x20`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4(&mut self, value: i32) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldc.i4", Some(Operand::Immediate(Immediate::Int32(value))))?;
        Ok(self)
    }

    /// Load a 64-bit integer constant.
    ///
    /// **Opcode**: `0x21`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i8(&mut self, value: i64) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldc.i8", Some(Operand::Immediate(Immediate::Int64(value))))?;
        Ok(self)
    }

    /// Load a 32-bit floating point constant.
    ///
    /// **Opcode**: `0x22`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_r4(&mut self, value: f32) -> Result<&mut Self> {
        self.encoder.emit_instruction(
            "ldc.r4",
            Some(Operand::Immediate(Immediate::Float32(value))),
        )?;
        Ok(self)
    }

    /// Load a 64-bit floating point constant.
    ///
    /// **Opcode**: `0x23`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_r8(&mut self, value: f64) -> Result<&mut Self> {
        self.encoder.emit_instruction(
            "ldc.r8",
            Some(Operand::Immediate(Immediate::Float64(value))),
        )?;
        Ok(self)
    }

    /// Add two values.
    ///
    /// **Opcode**: `0x58`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn add(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("add", None)?;
        Ok(self)
    }

    /// Subtract value2 from value1.
    ///
    /// **Opcode**: `0x59`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn sub(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("sub", None)?;
        Ok(self)
    }

    /// Multiply two values.
    ///
    /// **Opcode**: `0x5A`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn mul(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("mul", None)?;
        Ok(self)
    }

    /// Divide value1 by value2.
    ///
    /// **Opcode**: `0x5B`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn div(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("div", None)?;
        Ok(self)
    }

    /// Compute remainder of value1 divided by value2.
    ///
    /// **Opcode**: `0x5C`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn rem(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("rem", None)?;
        Ok(self)
    }

    /// Divide two unsigned values.
    ///
    /// **Opcode**: `0x5D`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn div_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("div.un", None)?;
        Ok(self)
    }

    /// Compute unsigned remainder of value1 divided by value2.
    ///
    /// **Opcode**: `0x5E`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn rem_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("rem.un", None)?;
        Ok(self)
    }

    /// Add two values with overflow check (signed).
    ///
    /// **Opcode**: `0xD6`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn add_ovf(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("add.ovf", None)?;
        Ok(self)
    }

    /// Add two unsigned values with overflow check.
    ///
    /// **Opcode**: `0xD7`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn add_ovf_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("add.ovf.un", None)?;
        Ok(self)
    }

    /// Multiply two values with overflow check (signed).
    ///
    /// **Opcode**: `0xD8`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn mul_ovf(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("mul.ovf", None)?;
        Ok(self)
    }

    /// Multiply two unsigned values with overflow check.
    ///
    /// **Opcode**: `0xD9`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn mul_ovf_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("mul.ovf.un", None)?;
        Ok(self)
    }

    /// Subtract two values with overflow check (signed).
    ///
    /// **Opcode**: `0xDA`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn sub_ovf(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("sub.ovf", None)?;
        Ok(self)
    }

    /// Subtract two unsigned values with overflow check.
    ///
    /// **Opcode**: `0xDB`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn sub_ovf_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("sub.ovf.un", None)?;
        Ok(self)
    }

    /// Unconditional branch (short form).
    ///
    /// **Opcode**: `0x2B`
    /// **Stack**: `... → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn br_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("br.s", label)?;
        Ok(self)
    }

    /// Branch if false (short form).
    ///
    /// **Opcode**: `0x2C`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn brfalse_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("brfalse.s", label)?;
        Ok(self)
    }

    /// Branch if true (short form).
    ///
    /// **Opcode**: `0x2D`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn brtrue_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("brtrue.s", label)?;
        Ok(self)
    }

    /// Branch if equal (short form).
    ///
    /// **Opcode**: `0x2E`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn beq_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("beq.s", label)?;
        Ok(self)
    }

    /// Branch if greater or equal (short form).
    ///
    /// **Opcode**: `0x2F`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bge_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bge.s", label)?;
        Ok(self)
    }

    /// Branch if greater than (short form).
    ///
    /// **Opcode**: `0x30`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bgt_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bgt.s", label)?;
        Ok(self)
    }

    /// Branch if less or equal (short form).
    ///
    /// **Opcode**: `0x31`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ble_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("ble.s", label)?;
        Ok(self)
    }

    /// Branch if less than (short form).
    ///
    /// **Opcode**: `0x32`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn blt_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("blt.s", label)?;
        Ok(self)
    }

    /// Branch if not equal (short form).
    ///
    /// **Opcode**: `0x33`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bne_un_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bne.un.s", label)?;
        Ok(self)
    }

    /// Call a method.
    ///
    /// **Opcode**: `0x28`
    /// **Stack**: `..., arg1, arg2, ... argN → ..., returnValue` (if not void)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn call(&mut self, method_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("call", Some(Operand::Token(method_token)))?;
        Ok(self)
    }

    /// Call a virtual method.
    ///
    /// **Opcode**: `0x6F`
    /// **Stack**: `..., obj, arg1, arg2, ... argN → ..., returnValue` (if not void)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn callvirt(&mut self, method_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("callvirt", Some(Operand::Token(method_token)))?;
        Ok(self)
    }

    /// Duplicate the top stack value.
    ///
    /// **Opcode**: `0x25`
    /// **Stack**: `..., value → ..., value, value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn dup(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("dup", None)?;
        Ok(self)
    }

    /// Pop the top stack value.
    ///
    /// **Opcode**: `0x26`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn pop(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("pop", None)?;
        Ok(self)
    }

    /// Load a constant value with automatic instruction selection.
    ///
    /// This method automatically selects the most efficient instruction for loading
    /// the given constant value, choosing between `ldc.i4.m1`, `ldc.i4.0` through
    /// `ldc.i4.8`, `ldc.i4.s`, and `ldc.i4` based on the value.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldc_i4_const(5)?;    // Uses ldc.i4.5 (single byte)
    /// asm.ldc_i4_const(100)?;  // Uses ldc.i4.s (two bytes)
    /// asm.ldc_i4_const(1000)?; // Uses ldc.i4 (five bytes)
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_i4_const(&mut self, value: i32) -> Result<&mut Self> {
        match value {
            -1 => self.ldc_i4_m1(),
            0 => self.ldc_i4_0(),
            1 => self.ldc_i4_1(),
            2 => self.ldc_i4_2(),
            3 => self.ldc_i4_3(),
            4 => self.ldc_i4_4(),
            5 => self.ldc_i4_5(),
            6 => self.ldc_i4_6(),
            7 => self.ldc_i4_7(),
            8 => self.ldc_i4_8(),
            v if i8::try_from(v).is_ok() => self.ldc_i4_s(
                i8::try_from(v).map_err(|_| malformed_error!("Constant value too large for i8"))?,
            ),
            v => self.ldc_i4(v),
        }
    }

    /// Load an argument with automatic instruction selection.
    ///
    /// This method automatically selects the most efficient instruction for loading
    /// the given argument, choosing between `ldarg.0` through `ldarg.3`, `ldarg.s`,
    /// and `ldarg` based on the index.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldarg_auto(0)?;   // Uses ldarg.0 (single byte)
    /// asm.ldarg_auto(5)?;   // Uses ldarg.s (two bytes)
    /// asm.ldarg_auto(500)?; // Uses ldarg (three bytes)
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldarg_auto(&mut self, index: u16) -> Result<&mut Self> {
        match index {
            0 => self.ldarg_0(),
            1 => self.ldarg_1(),
            2 => self.ldarg_2(),
            3 => self.ldarg_3(),
            i if i <= 255 => self.ldarg_s(
                u8::try_from(i).map_err(|_| malformed_error!("Argument index too large for u8"))?,
            ),
            i => self.ldarg(
                i16::try_from(i)
                    .map_err(|_| malformed_error!("Argument index too large for i16"))?,
            ),
        }
    }

    /// Store to a local with automatic instruction selection.
    ///
    /// This method automatically selects the most efficient instruction for storing
    /// to the given local variable, choosing between `stloc.0` through `stloc.3`,
    /// `stloc.s`, and `stloc` based on the index.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stloc_auto(&mut self, index: u16) -> Result<&mut Self> {
        match index {
            0 => self.stloc_0(),
            1 => self.stloc_1(),
            2 => self.stloc_2(),
            3 => self.stloc_3(),
            i if i <= 255 => self.stloc_s(
                u8::try_from(i).map_err(|_| malformed_error!("Local index too large for u8"))?,
            ),
            i => self.stloc(
                i16::try_from(i).map_err(|_| malformed_error!("Local index too large for i16"))?,
            ),
        }
    }

    /// Load from a local with automatic instruction selection.
    ///
    /// This method automatically selects the most efficient instruction for loading
    /// from the given local variable, choosing between `ldloc.0` through `ldloc.3`,
    /// `ldloc.s`, and `ldloc` based on the index.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldloc_auto(&mut self, index: u16) -> Result<&mut Self> {
        match index {
            0 => self.ldloc_0(),
            1 => self.ldloc_1(),
            2 => self.ldloc_2(),
            3 => self.ldloc_3(),
            i if i <= 255 => self.ldloc_s(
                u8::try_from(i).map_err(|_| malformed_error!("Local index too large for u8"))?,
            ),
            i => self.ldloc(
                i16::try_from(i).map_err(|_| malformed_error!("Local index too large for i16"))?,
            ),
        }
    }

    /// Bitwise AND operation.
    ///
    /// **Opcode**: `0x5F`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn and(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("and", None)?;
        Ok(self)
    }

    /// Bitwise OR operation.
    ///
    /// **Opcode**: `0x60`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn or(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("or", None)?;
        Ok(self)
    }

    /// Bitwise XOR operation.
    ///
    /// **Opcode**: `0x61`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn xor(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("xor", None)?;
        Ok(self)
    }

    /// Bitwise NOT operation.
    ///
    /// **Opcode**: `0x66`
    /// **Stack**: `..., value → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn not(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("not", None)?;
        Ok(self)
    }

    /// Shift left operation.
    ///
    /// **Opcode**: `0x62`
    /// **Stack**: `..., value, shiftAmount → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn shl(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("shl", None)?;
        Ok(self)
    }

    /// Shift right operation.
    ///
    /// **Opcode**: `0x63`
    /// **Stack**: `..., value, shiftAmount → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn shr(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("shr", None)?;
        Ok(self)
    }

    /// Unsigned shift right operation.
    ///
    /// **Opcode**: `0x64`
    /// **Stack**: `..., value, shiftAmount → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn shr_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("shr.un", None)?;
        Ok(self)
    }

    /// Negate value.
    ///
    /// **Opcode**: `0x65`
    /// **Stack**: `..., value → ..., -value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn neg(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("neg", None)?;
        Ok(self)
    }

    /// Convert to int8, with overflow check.
    ///
    /// **Opcode**: `0x68`
    /// **Stack**: `..., value → ..., int8`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_i1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.i1", None)?;
        Ok(self)
    }

    /// Convert to int16, with overflow check.
    ///
    /// **Opcode**: `0x69`
    /// **Stack**: `..., value → ..., int16`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_i2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.i2", None)?;
        Ok(self)
    }

    /// Convert to int32, with overflow check.
    ///
    /// **Opcode**: `0x69`
    /// **Stack**: `..., value → ..., int32`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_i4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.i4", None)?;
        Ok(self)
    }

    /// Convert to int64, with overflow check.
    ///
    /// **Opcode**: `0x6B`
    /// **Stack**: `..., value → ..., int64`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_i8(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.i8", None)?;
        Ok(self)
    }

    /// Convert to float32.
    ///
    /// **Opcode**: `0x6C`
    /// **Stack**: `..., value → ..., float32`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_r4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.r4", None)?;
        Ok(self)
    }

    /// Convert to float64.
    ///
    /// **Opcode**: `0x6C`
    /// **Stack**: `..., value → ..., float64`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_r8(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.r8", None)?;
        Ok(self)
    }

    /// Convert to uint8, with overflow check.
    ///
    /// **Opcode**: `0xD2`
    /// **Stack**: `..., value → ..., uint8`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_u1(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.u1", None)?;
        Ok(self)
    }

    /// Convert to uint16, with overflow check.
    ///
    /// **Opcode**: `0xD1`
    /// **Stack**: `..., value → ..., uint16`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_u2(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.u2", None)?;
        Ok(self)
    }

    /// Convert to uint32, with overflow check.
    ///
    /// **Opcode**: `0x6E`
    /// **Stack**: `..., value → ..., uint32`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_u4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.u4", None)?;
        Ok(self)
    }

    /// Convert to uint64, with overflow check.
    ///
    /// **Opcode**: `0x6F`
    /// **Stack**: `..., value → ..., uint64`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn conv_u8(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("conv.u8", None)?;
        Ok(self)
    }

    /// Compare equal.
    ///
    /// **Opcode**: `0xFE01`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ceq(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ceq", None)?;
        Ok(self)
    }

    /// Compare greater than.
    ///
    /// **Opcode**: `0xFE02`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn cgt(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("cgt", None)?;
        Ok(self)
    }

    /// Compare greater than (unsigned).
    ///
    /// **Opcode**: `0xFE03`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn cgt_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("cgt.un", None)?;
        Ok(self)
    }

    /// Compare less than.
    ///
    /// **Opcode**: `0xFE04`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn clt(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("clt", None)?;
        Ok(self)
    }

    /// Compare less than (unsigned).
    ///
    /// **Opcode**: `0xFE05`
    /// **Stack**: `..., value1, value2 → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn clt_un(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("clt.un", None)?;
        Ok(self)
    }

    /// Load null reference.
    ///
    /// **Opcode**: `0x14`
    /// **Stack**: `... → ..., null`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldnull(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldnull", None)?;
        Ok(self)
    }

    /// Load string literal.
    ///
    /// **Opcode**: `0x72`
    /// **Stack**: `... → ..., string`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldstr(&mut self, string_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldstr", Some(Operand::Token(string_token)))?;
        Ok(self)
    }

    /// Create new object instance.
    ///
    /// **Opcode**: `0x73`
    /// **Stack**: `..., arg1, arg2, ... argN → ..., obj`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn newobj(&mut self, constructor_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("newobj", Some(Operand::Token(constructor_token)))?;
        Ok(self)
    }

    /// Cast class check.
    ///
    /// **Opcode**: `0x74`
    /// **Stack**: `..., obj → ..., obj2`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn castclass(&mut self, type_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("castclass", Some(Operand::Token(type_token)))?;
        Ok(self)
    }

    /// Instance of check.
    ///
    /// **Opcode**: `0x75`
    /// **Stack**: `..., obj → ..., result`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn isinst(&mut self, type_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("isinst", Some(Operand::Token(type_token)))?;
        Ok(self)
    }

    /// Load field.
    ///
    /// **Opcode**: `0x7B`
    /// **Stack**: `..., obj → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldfld(&mut self, field_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldfld", Some(Operand::Token(field_token)))?;
        Ok(self)
    }

    /// Store field.
    ///
    /// **Opcode**: `0x7D`
    /// **Stack**: `..., obj, value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stfld(&mut self, field_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("stfld", Some(Operand::Token(field_token)))?;
        Ok(self)
    }

    /// Load static field.
    ///
    /// **Opcode**: `0x7E`
    /// **Stack**: `... → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldsfld(&mut self, field_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("ldsfld", Some(Operand::Token(field_token)))?;
        Ok(self)
    }

    /// Store static field.
    ///
    /// **Opcode**: `0x80`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stsfld(&mut self, field_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("stsfld", Some(Operand::Token(field_token)))?;
        Ok(self)
    }

    /// Throw exception.
    ///
    /// **Opcode**: `0x7A`
    /// **Stack**: `..., obj → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn throw(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("throw", None)?;
        Ok(self)
    }

    /// End of finally block.
    ///
    /// **Opcode**: `0xDC`
    /// **Stack**: `... → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn endfinally(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("endfinally", None)?;
        Ok(self)
    }

    /// End filter clause and transfer control to the exception handler.
    ///
    /// This instruction terminates the filter clause of an exception handler.
    /// The value on the stack determines whether the handler will execute:
    /// - Non-zero (typically 1): Execute the handler
    /// - Zero: Continue searching for another handler
    ///
    /// **Opcode**: `0xFE 0x11`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn endfilter(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("endfilter", None)?;
        Ok(self)
    }

    /// Load element from array.
    ///
    /// **Opcode**: `0x8F`
    /// **Stack**: `..., array, index → ..., value`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldelem_i4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldelem.i4", None)?;
        Ok(self)
    }

    /// Store element to array.
    ///
    /// **Opcode**: `0x9C`
    /// **Stack**: `..., array, index, value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn stelem_i4(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("stelem.i4", None)?;
        Ok(self)
    }

    /// Load array length.
    ///
    /// **Opcode**: `0x8E`
    /// **Stack**: `..., array → ..., length`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldlen(&mut self) -> Result<&mut Self> {
        self.encoder.emit_instruction("ldlen", None)?;
        Ok(self)
    }

    /// Create new array.
    ///
    /// **Opcode**: `0x8D`
    /// **Stack**: `..., numElems → ..., array`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn newarr(&mut self, element_type_token: Token) -> Result<&mut Self> {
        self.encoder
            .emit_instruction("newarr", Some(Operand::Token(element_type_token)))?;
        Ok(self)
    }

    /// Unconditional branch (long form).
    ///
    /// **Opcode**: `0x38`
    /// **Stack**: `... → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn br(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("br", label)?;
        Ok(self)
    }

    /// Branch if false (long form).
    ///
    /// **Opcode**: `0x39`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn brfalse(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("brfalse", label)?;
        Ok(self)
    }

    /// Branch if true (long form).
    ///
    /// **Opcode**: `0x3A`
    /// **Stack**: `..., value → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn brtrue(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("brtrue", label)?;
        Ok(self)
    }

    /// Leave protected region for exception handling (short form).
    ///
    /// **Opcode**: `0xDE`
    /// **Stack**: `... → ...`
    ///
    /// Exits a protected region of code, unconditionally transferring control
    /// to a specific target instruction (typically at the end of a finally clause).
    /// This is used in structured exception handling.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn leave_s(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("leave.s", label)?;
        Ok(self)
    }

    /// Leave protected region for exception handling (long form).
    ///
    /// **Opcode**: `0xDD`
    /// **Stack**: `... → ...`
    ///
    /// Exits a protected region of code, unconditionally transferring control
    /// to a specific target instruction (typically at the end of a finally clause).
    /// This is used in structured exception handling.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn leave(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("leave", label)?;
        Ok(self)
    }

    /// Multi-way branch (switch statement).
    ///
    /// **Opcode**: `0x45`
    /// **Stack**: `..., value → ...`
    ///
    /// Pops an unsigned integer from the stack and uses it as an index into a table
    /// of branch targets. If the value is within range (0 to n-1), execution transfers
    /// to the corresponding label. If out of range, execution continues to the next
    /// instruction (fall-through).
    ///
    /// # Parameters
    ///
    /// * `labels` - Target label names for each switch case (0-indexed)
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldarg_0()?                      // Load switch value
    ///    .switch(&["case0", "case1"])?   // Switch on value
    ///    .ldc_i4_m1()?                   // Default: return -1
    ///    .ret()?
    ///    .label("case0")?
    ///    .ldc_i4_0()?                    // Case 0: return 0
    ///    .ret()?
    ///    .label("case1")?
    ///    .ldc_i4_1()?                    // Case 1: return 1
    ///    .ret()?;
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn switch(&mut self, labels: &[&str]) -> Result<&mut Self> {
        self.encoder.emit_switch(labels)?;
        Ok(self)
    }

    /// Branch if equal (long form).
    ///
    /// **Opcode**: `0x3B`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn beq(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("beq", label)?;
        Ok(self)
    }

    /// Branch if greater or equal (long form).
    ///
    /// **Opcode**: `0x3C`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bge(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bge", label)?;
        Ok(self)
    }

    /// Branch if greater than (long form).
    ///
    /// **Opcode**: `0x3D`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bgt(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bgt", label)?;
        Ok(self)
    }

    /// Branch if less or equal (long form).
    ///
    /// **Opcode**: `0x3E`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ble(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("ble", label)?;
        Ok(self)
    }

    /// Branch if less than (long form).
    ///
    /// **Opcode**: `0x3F`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn blt(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("blt", label)?;
        Ok(self)
    }

    /// Branch if not equal (long form).
    ///
    /// **Opcode**: `0x40`
    /// **Stack**: `..., value1, value2 → ...`
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn bne_un(&mut self, label: &str) -> Result<&mut Self> {
        self.encoder.emit_branch("bne.un", label)?;
        Ok(self)
    }

    /// Load a boolean constant (0 or 1).
    ///
    /// Maps to `ldc.i4.0` for false and `ldc.i4.1` for true.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.ldc_bool(true)?;   // Uses ldc.i4.1
    /// asm.ldc_bool(false)?;  // Uses ldc.i4.0
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    pub fn ldc_bool(&mut self, value: bool) -> Result<&mut Self> {
        if value {
            self.ldc_i4_1()
        } else {
            self.ldc_i4_0()
        }
    }

    /// Common pattern: load argument, check if null, branch if not null.
    ///
    /// This is a convenience method that combines three common instructions
    /// used for null checking patterns.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.check_null_and_branch(0, "not_null")?;  // if (arg0 != null) goto not_null
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn check_null_and_branch(&mut self, arg_index: u16, label: &str) -> Result<&mut Self> {
        self.ldarg_auto(arg_index)?.ldnull()?.bne_un_s(label)
    }

    /// Common pattern: compare two arguments and branch.
    ///
    /// Loads two arguments and performs an equality comparison with branching.
    ///
    /// # Errors
    ///
    /// Returns an error if instruction encoding fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use dotscope::assembly::InstructionAssembler;
    ///
    /// let mut asm = InstructionAssembler::new();
    /// asm.compare_args_and_branch(0, 1, "equal")?;  // if (arg0 == arg1) goto equal
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    pub fn compare_args_and_branch(
        &mut self,
        arg1: u16,
        arg2: u16,
        label: &str,
    ) -> Result<&mut Self> {
        self.ldarg_auto(arg1)?.ldarg_auto(arg2)?.beq_s(label)
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::metadata::token::Token;

    #[test]
    fn test_fluent_api_basic() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.nop()?.ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode, vec![0x00, 0x2A]); // nop, ret

        Ok(())
    }

    #[test]
    fn test_arithmetic_method() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        // Simple addition: return arg0 + arg1
        asm.ldarg_0()?.ldarg_1()?.add()?.ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode, vec![0x02, 0x03, 0x58, 0x2A]); // ldarg.0, ldarg.1, add, ret

        Ok(())
    }

    #[test]
    fn test_conditional_logic() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        // if (arg0 > 0) return 1; else return 0;
        asm.ldarg_0()?
            .ldc_i4_0()?
            .bgt_s("positive")?
            .ldc_i4_0()?
            .ret()?
            .label("positive")?
            .ldc_i4_1()?
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldarg.0 (0x02), ldc.i4.0 (0x16), bgt.s (0x30) + offset, ldc.i4.0 (0x16), ret (0x2A), ldc.i4.1 (0x17), ret (0x2A)
        assert_eq!(bytecode.len(), 8); // Total should be 8 bytes
        assert_eq!(bytecode[0], 0x02); // ldarg.0
        assert_eq!(bytecode[1], 0x16); // ldc.i4.0
        assert_eq!(bytecode[2], 0x30); // bgt.s

        Ok(())
    }

    #[test]
    fn test_constant_optimization() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldc_i4_const(-1)? // ldc.i4.m1
            .ldc_i4_const(5)? // ldc.i4.5
            .ldc_i4_const(42)? // ldc.i4.s 42
            .ldc_i4_const(1000)?; // ldc.i4 1000

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode[0], 0x15); // ldc.i4.m1
        assert_eq!(bytecode[1], 0x1B); // ldc.i4.5
        assert_eq!(bytecode[2], 0x1F); // ldc.i4.s
        assert_eq!(bytecode[3], 42); // value
        assert_eq!(bytecode[4], 0x20); // ldc.i4

        Ok(())
    }

    #[test]
    fn test_argument_optimization() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_auto(0)? // ldarg.0
            .ldarg_auto(1)? // ldarg.1
            .ldarg_auto(5)? // ldarg.s 5
            .ldarg_auto(500)?; // ldarg 500

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode[0], 0x02); // ldarg.0
        assert_eq!(bytecode[1], 0x03); // ldarg.1
        assert_eq!(bytecode[2], 0x0E); // ldarg.s
        assert_eq!(bytecode[3], 5); // index
        assert_eq!(bytecode[4], 0xFE); // ldarg prefix
        assert_eq!(bytecode[5], 0x09); // ldarg opcode
        assert_eq!(bytecode[6], 244); // 500 & 0xFF (low byte)
        assert_eq!(bytecode[7], 1); // (500 >> 8) & 0xFF (high byte)

        Ok(())
    }

    #[test]
    fn test_local_variable_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .stloc_0()? // Store arg0 to local 0
            .ldloc_0()? // Load local 0
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode, vec![0x02, 0x0A, 0x06, 0x2A]); // ldarg.0, stloc.0, ldloc.0, ret

        Ok(())
    }

    #[test]
    fn test_stack_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .dup()? // Duplicate the value
            .pop()? // Remove one copy
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode, vec![0x02, 0x25, 0x26, 0x2A]); // ldarg.0, dup, pop, ret

        Ok(())
    }

    #[test]
    fn test_bitwise_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .ldarg_1()?
            .and()? // Bitwise AND
            .ldarg_0()?
            .ldarg_1()?
            .or()? // Bitwise OR
            .xor()? // XOR the results
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldarg.0 (0x02), ldarg.1 (0x03), and (0x5F), ldarg.0 (0x02), ldarg.1 (0x03), or (0x60), xor (0x61), ret (0x2A)
        assert_eq!(
            bytecode,
            vec![0x02, 0x03, 0x5F, 0x02, 0x03, 0x60, 0x61, 0x2A]
        );

        Ok(())
    }

    #[test]
    fn test_comparison_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .ldarg_1()?
            .ceq()? // Compare equal
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldarg.0 (0x02), ldarg.1 (0x03), ceq (0xFE 0x01), ret (0x2A)
        assert_eq!(bytecode, vec![0x02, 0x03, 0xFE, 0x01, 0x2A]);

        Ok(())
    }

    #[test]
    fn test_conversion_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .conv_i4()? // Convert to int32
            .conv_r8()? // Convert to double
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldarg.0 (0x02), conv.i4 (0x69), conv.r8 (0x6C), ret (0x2A)
        assert_eq!(bytecode, vec![0x02, 0x69, 0x6C, 0x2A]);

        Ok(())
    }

    #[test]
    fn test_boolean_constants() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldc_bool(true)? // Should use ldc.i4.1
            .ldc_bool(false)? // Should use ldc.i4.0
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldc.i4.1 (0x17), ldc.i4.0 (0x16), ret (0x2A)
        assert_eq!(bytecode, vec![0x17, 0x16, 0x2A]);

        Ok(())
    }

    #[test]
    fn test_null_operations() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        asm.ldnull()? // Load null
            .ldarg_0()?
            .ceq()? // Compare with argument
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // ldnull (0x14), ldarg.0 (0x02), ceq (0xFE 0x01), ret (0x2A)
        assert_eq!(bytecode, vec![0x14, 0x02, 0xFE, 0x01, 0x2A]);

        Ok(())
    }

    #[test]
    fn test_branch_optimization() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        // Even when using long-form branch API, the encoder optimizes to short form
        // when the offset fits in a signed byte.
        // Valid CIL: both paths must have same stack depth at join point.
        asm.ldarg_0()? // depth: 0→1
            .brfalse("else")? // depth: 1→0, records 'else' expects 0
            .ldc_i4_1()? // depth: 0→1
            .ret()? // terminates this path
            .label("else")? // depth: 0 (from branch, after ret is unreachable)
            .ldc_i4_0()? // depth: 0→1
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        // Optimized: ldarg.0(1) + brfalse.s+offset(2) + ldc.i4.1(1) + ret(1) + ldc.i4.0(1) + ret(1) = 7 bytes
        assert_eq!(bytecode.len(), 7);
        assert_eq!(bytecode[0], 0x02); // ldarg.0
        assert_eq!(bytecode[1], 0x2C); // brfalse.s (short form - optimized!)

        Ok(())
    }

    #[test]
    fn test_convenience_methods() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        // Test null check pattern
        asm.check_null_and_branch(0, "not_null")?
            .ldc_i4_0()? // null case
            .ret()?
            .label("not_null")?
            .ldc_i4_1()? // not null case
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode[0], 0x02); // ldarg.0
        assert_eq!(bytecode[1], 0x14); // ldnull
        assert_eq!(bytecode[2], 0x33); // bne.un.s

        Ok(())
    }

    #[test]
    fn test_field_operations_with_tokens() -> Result<()> {
        let field_token = Token::new(0x04000001); // Example field token
        let mut asm = InstructionAssembler::new();

        asm.ldarg_0()?
            .ldfld(field_token)? // Load field
            .ret()?;

        let (bytecode, _max_stack, _) = asm.finish()?;
        assert_eq!(bytecode[0], 0x02); // ldarg.0
        assert_eq!(bytecode[1], 0x7B); // ldfld

        Ok(())
    }

    #[test]
    fn test_try_catch_basic() -> Result<()> {
        let mut asm = InstructionAssembler::new();
        let exception_type = Token::new(0x01000001); // TypeRef for System.Exception

        // Note: leave clears the evaluation stack, so we must not have values
        // on the stack before leave. Use stloc/ldloc pattern if needed.
        asm.try_start("try1")?
            .nop()? // Some code in try block
            .leave_s("end")?
            .try_end("try1")?
            .catch_start("try1", exception_type)?
            .pop()? // Pop the exception object pushed by CLR
            .leave_s("end")?
            .catch_end("try1")?
            .label("end")?
            .ldc_i4_0()?
            .ret()?;

        let (bytecode, max_stack, handlers) = asm.finish()?;

        // Verify we have one handler
        assert_eq!(handlers.len(), 1);

        // Verify it's a catch handler
        let handler = &handlers[0];
        assert!(handler.is_catch());
        assert!(!handler.is_finally());
        assert!(!handler.is_fault());
        assert!(!handler.is_filter());

        // Verify offsets are reasonable
        assert!(handler.try_offset < handler.handler_offset);
        assert!(handler.try_length > 0);
        assert!(handler.handler_length > 0);

        // Verify type token is stored in filter_offset for EXCEPTION handlers
        assert_eq!(handler.filter_offset, exception_type.value());

        // Verify bytecode is generated
        assert!(!bytecode.is_empty());
        assert!(max_stack > 0);

        Ok(())
    }

    #[test]
    fn test_try_finally_basic() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        // leave clears the stack, so we must not have values before leave
        asm.try_start("try1")?
            .nop()? // Some code in try block
            .leave_s("end")?
            .try_end("try1")?
            .finally_start("try1")?
            .nop()? // Some cleanup code
            .endfinally()?
            .finally_end("try1")?
            .label("end")?
            .ldc_i4_0()?
            .ret()?;

        let (bytecode, _max_stack, handlers) = asm.finish()?;

        assert_eq!(handlers.len(), 1);

        let handler = &handlers[0];
        assert!(handler.is_finally());
        assert!(!handler.is_catch());

        assert!(!bytecode.is_empty());

        Ok(())
    }

    #[test]
    fn test_nested_try_blocks() -> Result<()> {
        let mut asm = InstructionAssembler::new();
        let exception_type1 = Token::new(0x01000001);
        let exception_type2 = Token::new(0x01000002);

        // Outer try
        asm.try_start("outer")?
            // Inner try
            .try_start("inner")?
            .nop()?
            .leave_s("inner_end")?
            .try_end("inner")?
            .catch_start("inner", exception_type2)?
            .pop()?
            .leave_s("inner_end")?
            .catch_end("inner")?
            .label("inner_end")?
            .leave_s("outer_end")?
            .try_end("outer")?
            .catch_start("outer", exception_type1)?
            .pop()?
            .leave_s("outer_end")?
            .catch_end("outer")?
            .label("outer_end")?
            .ldc_i4_0()?
            .ret()?;

        let (_bytecode, _max_stack, handlers) = asm.finish()?;

        // We should have 2 handlers (inner and outer)
        assert_eq!(handlers.len(), 2);

        // Both should be catch handlers
        for handler in &handlers {
            assert!(handler.is_catch());
        }

        Ok(())
    }

    #[test]
    fn test_multiple_handlers_same_try() -> Result<()> {
        let mut asm = InstructionAssembler::new();
        let exception_type1 = Token::new(0x01000001);
        let exception_type2 = Token::new(0x01000002);

        asm.try_start("try1")?
            .nop()?
            .leave_s("end")?
            .try_end("try1")?
            // First catch for exception_type1
            .catch_start("try1", exception_type1)?
            .pop()?
            .leave_s("end")?
            .catch_end("try1")?
            // Second catch for exception_type2
            .catch_start("try1", exception_type2)?
            .pop()?
            .leave_s("end")?
            .catch_end("try1")?
            .label("end")?
            .ldc_i4_0()?
            .ret()?;

        let (_bytecode, _max_stack, handlers) = asm.finish()?;

        // We should have 2 handlers for the same try block
        assert_eq!(handlers.len(), 2);

        // Both should be catch handlers with the same try region
        assert!(handlers[0].is_catch());
        assert!(handlers[1].is_catch());
        assert_eq!(handlers[0].try_offset, handlers[1].try_offset);
        assert_eq!(handlers[0].try_length, handlers[1].try_length);

        Ok(())
    }

    #[test]
    fn test_has_try_block() -> Result<()> {
        let mut asm = InstructionAssembler::new();

        assert!(!asm.has_try_block("test"));

        asm.try_start("test")?;
        assert!(asm.has_try_block("test"));
        assert!(!asm.has_try_block("other"));

        Ok(())
    }

    #[test]
    fn test_handler_count() -> Result<()> {
        let mut asm = InstructionAssembler::new();
        let exception_type = Token::new(0x01000001);

        assert_eq!(asm.handler_count("test"), 0);

        asm.try_start("test")?
            .nop()?
            .leave_s("end")?
            .try_end("test")?;

        assert_eq!(asm.handler_count("test"), 0);

        asm.catch_start("test", exception_type)?
            .pop()?
            .leave_s("end")?
            .catch_end("test")?;

        assert_eq!(asm.handler_count("test"), 1);

        asm.finally_start("test")?
            .nop()?
            .endfinally()?
            .finally_end("test")?
            .label("end")?
            .ldc_i4_0()?
            .ret()?;

        assert_eq!(asm.handler_count("test"), 2);

        Ok(())
    }

    #[test]
    fn test_try_block_errors() -> Result<()> {
        let mut asm = InstructionAssembler::new();
        let exception_type = Token::new(0x01000001);

        // Cannot add handler before ending try
        asm.try_start("test")?.ldarg_0()?;
        assert!(asm.catch_start("test", exception_type).is_err());

        // Cannot end non-existent try
        assert!(asm.try_end("nonexistent").is_err());

        Ok(())
    }
}