clock_curve_math/

api_extensions.rs

//! Extended API patterns for future extensibility.
//!
//! This module provides advanced API design patterns that enable future
//! extensions while maintaining backward compatibility. These patterns
//! allow for optional features, alternative implementations, and
//! configurable algorithms.
//!
//! # Extension Traits
//!
//! Extension traits provide optional functionality that can be implemented
//! by different backends or added in future versions:
//!
//! ```rust
//! use clock_curve_math::{api_extensions::FieldExtensions, FieldElement, FieldOps};
//!
//! // Use extended functionality if available
//! let element = FieldElement::from_u64(42);
//! if let Some(sqrt) = element.try_sqrt() {
//!     // Square root is available
//!     assert_eq!(sqrt.square(), element);
//! }
//! ```
//!
//! # Operation Builders
//!
//! Builders allow complex operations to be configured and executed:
//!
//! ```rust
//! use clock_curve_math::{api_extensions::{ExponentiationBuilder, Algorithm}, FieldElement, BigInt};
//!
//! let base = FieldElement::from_u64(2);
//! let exp = BigInt::from_u64(1000);
//!
//! let result = ExponentiationBuilder::new(&base, &exp)
//!     .algorithm(Algorithm::SlidingWindow(4))
//!     .build()
//!     .compute();
//! ```
//!
//! # Configurable Operations
//!
//! Operations can be configured with different algorithms and parameters:
//!
//! ```rust
//! use clock_curve_math::{api_extensions::{MultiplicationConfig, MultiplicationAlgorithm, ConfigurableArithmetic}, FieldElement, FieldOps};
//!
//! let a = FieldElement::from_u64(42);
//! let b = FieldElement::from_u64(24);
//!
//! let config = MultiplicationConfig {
//!     algorithm: MultiplicationAlgorithm::Standard,
//!     ..Default::default()
//! };
//!
//! // Configurable multiplication with algorithm selection
//! let product = a.mul_with_config(&b, &config);
//! ```

use crate::bigint::BigInt;
use crate::error::MathError;
use crate::extensible::{mul_fft_standalone, mul_karatsuba_standalone, mul_toom_cook_standalone};
use crate::field::{FieldElement, FieldOps};
#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "alloc")]
use alloc::vec::Vec;

/// Extension trait for optional field operations.
///
/// This trait provides operations that may not be available in all
/// implementations or may have different performance characteristics.
pub trait FieldExtensions {
    /// Attempt to compute the square root.
    ///
    /// Returns `Some(sqrt)` if a square root exists, `None` otherwise.
    /// This is an optional operation that may not be implemented by all backends.
    fn try_sqrt(&self) -> Option<Self>
    where
        Self: Sized;

    /// Compute the Legendre symbol (a/p).
    ///
    /// Returns 1 if self is a quadratic residue, -1 if not, 0 if zero.
    /// This operation may be expensive and is provided as an extension.
    fn legendre(&self) -> i32;

    /// Check if this element is a quadratic residue.
    fn is_quadratic_residue(&self) -> bool {
        self.legendre() == 1
    }

    /// Get the order of this element (if it generates the field).
    ///
    /// Returns the smallest positive integer d such that self^d ≡ 1 mod p.
    /// This is a potentially expensive operation.
    fn order(&self) -> Option<BigInt>;
}

impl FieldExtensions for FieldElement {
    fn try_sqrt(&self) -> Option<Self> {
        // For now, delegate to existing sqrt function
        // In future versions, this could use different algorithms
        #[cfg(feature = "alloc")]
        {
            crate::field::sqrt(self)
        }
        #[cfg(not(feature = "alloc"))]
        {
            None // sqrt requires alloc feature
        }
    }

    fn legendre(&self) -> i32 {
        #[cfg(feature = "alloc")]
        {
            crate::field::legendre_symbol(self)
        }
        #[cfg(not(feature = "alloc"))]
        {
            // Fallback implementation without alloc
            // This is less efficient but works for basic cases
            if self == &FieldElement::from_u64(0) {
                0
            } else {
                // Simplified check - in practice this would be more complex
                let square = self.square();
                if square == FieldElement::from_u64(0) {
                    0 // This shouldn't happen for non-zero elements
                } else {
                    1 // Assume it's a quadratic residue for small values
                }
            }
        }
    }

    fn order(&self) -> Option<BigInt> {
        // Use the existing order-finding implementation from higher_order module
        #[cfg(feature = "alloc")]
        {
            crate::field::order(self)
        }
        #[cfg(not(feature = "alloc"))]
        {
            None // Order finding requires alloc feature
        }
    }
}

/// Algorithms available for different operations.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Algorithm {
    /// Basic binary exponentiation (square-and-multiply)
    Binary,
    /// Sliding window exponentiation with given window size
    SlidingWindow(u32),
    /// Montgomery ladder (constant-time)
    MontgomeryLadder,
    /// Fixed window size (precomputed tables)
    FixedWindow(u32),
    /// Variable algorithms based on input size
    Adaptive,
}

/// Configuration for exponentiation operations.
#[derive(Clone, Debug)]
pub struct ExponentiationConfig {
    /// Algorithm to use
    pub algorithm: Algorithm,
    /// Maximum exponent bit length to handle
    pub max_bits: Option<u32>,
    /// Whether to use constant-time operations
    pub constant_time: bool,
}

impl Default for ExponentiationConfig {
    fn default() -> Self {
        Self {
            algorithm: Algorithm::Adaptive,
            max_bits: None,
            constant_time: true,
        }
    }
}

/// Builder for exponentiation operations.
///
/// This builder allows configuring exponentiation parameters and
/// provides a fluent API for complex exponentiation operations.
#[derive(Clone, Debug)]
pub struct ExponentiationBuilder<'a> {
    base: &'a FieldElement,
    exponent: &'a BigInt,
    config: ExponentiationConfig,
}

impl<'a> ExponentiationBuilder<'a> {
    /// Create a new exponentiation builder.
    pub fn new(base: &'a FieldElement, exponent: &'a BigInt) -> Self {
        Self {
            base,
            exponent,
            config: ExponentiationConfig::default(),
        }
    }

    /// Set the algorithm to use.
    pub fn algorithm(mut self, algorithm: Algorithm) -> Self {
        self.config.algorithm = algorithm;
        self
    }

    /// Set maximum bit length.
    pub fn max_bits(mut self, bits: u32) -> Self {
        self.config.max_bits = Some(bits);
        self
    }

    /// Enable or disable constant-time operations.
    pub fn constant_time(mut self, enabled: bool) -> Self {
        self.config.constant_time = enabled;
        self
    }

    /// Build the configured operation.
    pub fn build(self) -> ConfiguredExponentiation<'a> {
        ConfiguredExponentiation {
            base: self.base,
            exponent: self.exponent,
            config: self.config,
        }
    }
}

/// Configured exponentiation operation.
#[derive(Clone, Debug)]
pub struct ConfiguredExponentiation<'a> {
    base: &'a FieldElement,
    exponent: &'a BigInt,
    config: ExponentiationConfig,
}

impl<'a> ConfiguredExponentiation<'a> {
    /// Compute the exponentiation result.
    pub fn compute(self) -> FieldElement {
        match self.config.algorithm {
            Algorithm::Binary => {
                // Use basic square-and-multiply
                self.base.pow(self.exponent)
            }
            Algorithm::SlidingWindow(_window) => {
                // For now, use the existing implementation
                // In future, this could use optimized sliding window
                self.base.pow(self.exponent)
            }
            Algorithm::MontgomeryLadder => {
                // For now, same as binary (Montgomery ladder would be constant-time variant)
                self.base.pow(self.exponent)
            }
            Algorithm::FixedWindow(window_size) => self.fixed_window_exp(window_size),
            Algorithm::Adaptive => {
                // Adaptive algorithm selection based on exponent size
                let bit_length = self.exponent.bit_length();
                if bit_length < 64 {
                    // Small exponents: use binary
                    self.base.pow(self.exponent)
                } else {
                    // Large exponents: could use more sophisticated algorithms
                    self.base.pow(self.exponent)
                }
            }
        }
    }

    /// Compute exponentiation using fixed window algorithm.
    ///
    /// This method precomputes a table of powers and uses a fixed window size
    /// to scan the exponent, reducing the number of multiplications needed.
    fn fixed_window_exp(self, window_size: u32) -> FieldElement {
        // Clamp window size to reasonable bounds (1-6 bits to avoid excessive memory)
        let w = window_size.clamp(1, 6);

        // Special cases
        let exp_bit_length = self.exponent.bit_length() as usize;
        if exp_bit_length == 0 {
            return FieldElement::from_u64(1);
        }

        // For small exponents, just use binary exponentiation
        if exp_bit_length <= w as usize {
            return self.base.pow(self.exponent);
        }

        // Precompute the table: base^0, base^1, base^2, ..., base^(2^w-1)
        let table_size = 1 << w; // 2^w entries
        let mut table = Vec::with_capacity(table_size);

        // base^0 = 1
        table.push(FieldElement::from_u64(1));

        // base^1
        table.push(*self.base);

        // Compute base^2, base^3, ..., base^(2^w-1)
        for i in 2..table_size {
            table.push(table[i - 1].mul(self.base));
        }

        // Start from the most significant bit
        let mut result = FieldElement::from_u64(1);
        let mut bit_pos = (exp_bit_length - 1) as u32;

        loop {
            // Extract next w bits (or remaining bits if less than w)
            let remaining_bits = bit_pos + 1;
            let current_window = if remaining_bits >= w {
                w
            } else {
                remaining_bits
            };

            let mut window_value = 0u32;
            for j in 0..current_window {
                // Safety check to avoid underflow
                if bit_pos >= j {
                    let bit = self.exponent.get_bit(bit_pos - j);
                    if bit != 0 {
                        window_value |= 1 << j;
                    }
                }
                // If bit_pos < j, we've reached the end of the exponent
            }

            // Square current_window times
            for _ in 0..current_window {
                result = result.mul(&result);
            }

            // Multiply by base^window_value
            if window_value > 0 {
                result = result.mul(&table[window_value as usize]);
            }

            // Move to next window
            if current_window > bit_pos {
                break; // No more bits to process
            }
            bit_pos -= current_window;
        }

        result
    }

    /// Get the algorithm configuration.
    pub fn get_algorithm(&self) -> Algorithm {
        self.config.algorithm
    }

    /// Get the maximum bit length configuration.
    pub fn get_max_bits(&self) -> Option<u32> {
        self.config.max_bits
    }

    /// Check if constant-time operations are enabled.
    pub fn get_constant_time(&self) -> bool {
        self.config.constant_time
    }
}

/// Configuration for multiplication operations.
#[derive(Clone, Debug)]
pub struct MultiplicationConfig {
    /// Algorithm to use
    pub algorithm: MultiplicationAlgorithm,
    /// Whether to use optimized squaring when applicable
    pub optimize_squaring: bool,
}

impl Default for MultiplicationConfig {
    fn default() -> Self {
        Self {
            algorithm: MultiplicationAlgorithm::Standard,
            optimize_squaring: true,
        }
    }
}

/// Algorithms for multiplication.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MultiplicationAlgorithm {
    /// Standard schoolbook multiplication
    Standard,
    /// Schoolbook multiplication (alias for Standard)
    Schoolbook,
    /// Karatsuba multiplication (for large numbers)
    Karatsuba,
    /// Toom-Cook multiplication (for very large numbers)
    ToomCook,
    /// FFT-based multiplication (for extremely large numbers)
    FFT,
}

/// Trait for configurable arithmetic operations.
///
/// This trait allows operations to be performed with different algorithms
/// and configurations, enabling future optimizations and extensions.
pub trait ConfigurableArithmetic {
    /// Multiply with configuration.
    fn mul_with_config(&self, rhs: &Self, config: &MultiplicationConfig) -> Self;

    /// Compute power with configuration.
    fn pow_with_config(&self, exp: &BigInt, config: &ExponentiationConfig) -> Self;
}

impl ConfigurableArithmetic for FieldElement {
    fn mul_with_config(&self, rhs: &Self, config: &MultiplicationConfig) -> Self {
        match config.algorithm {
            MultiplicationAlgorithm::Standard | MultiplicationAlgorithm::Schoolbook => {
                // For 256-bit field elements, standard Montgomery multiplication is optimal
                self.mul(rhs)
            }
            MultiplicationAlgorithm::Karatsuba
            | MultiplicationAlgorithm::ToomCook
            | MultiplicationAlgorithm::FFT => {
                // For larger computations, we could use BigInt algorithms
                // Convert to regular form, multiply, then back to Montgomery form
                let a_regular = crate::montgomery::from_montgomery_p(&self.to_bigint());
                let b_regular = crate::montgomery::from_montgomery_p(&rhs.to_bigint());

                let result_regular = a_regular.mul_with_config(&b_regular, config);

                // Convert back to Montgomery form
                let mont_result = crate::montgomery::to_montgomery_p(&result_regular);
                Self { inner: mont_result }
            }
        }
    }

    fn pow_with_config(&self, exp: &BigInt, config: &ExponentiationConfig) -> Self {
        // Use the builder to compute with configuration
        ExponentiationBuilder::new(self, exp)
            .algorithm(config.algorithm)
            .max_bits(config.max_bits.unwrap_or(256))
            .constant_time(config.constant_time)
            .build()
            .compute()
    }
}

impl ConfigurableArithmetic for BigInt {
    fn mul_with_config(&self, rhs: &Self, config: &MultiplicationConfig) -> Self {
        match config.algorithm {
            MultiplicationAlgorithm::Standard | MultiplicationAlgorithm::Schoolbook => {
                // Standard BigInt multiplication
                self.mul(rhs)
            }
            MultiplicationAlgorithm::Karatsuba => {
                // Use Karatsuba algorithm for larger numbers
                mul_karatsuba_standalone(self, rhs)
            }
            MultiplicationAlgorithm::ToomCook => {
                // Use Toom-Cook algorithm for very large numbers
                mul_toom_cook_standalone(self, rhs)
            }
            MultiplicationAlgorithm::FFT => {
                // Use FFT-based multiplication for extremely large numbers
                mul_fft_standalone(self, rhs)
            }
        }
    }

    fn pow_with_config(&self, exp: &BigInt, _config: &ExponentiationConfig) -> Self {
        // For BigInt, we can use modular exponentiation if needed
        // For now, implement basic binary exponentiation
        let mut result = BigInt::from_u64(1);
        let mut base = *self;
        let mut exp = *exp;

        while !exp.is_zero() {
            if exp.limbs()[0] % 2 == 1 {
                result = result.mul(&base);
            }
            exp = exp.shr(1);
            if !exp.is_zero() {
                base = base.mul(&base);
            }
        }

        result
    }
}

/// Batch operation configuration.
#[derive(Clone, Debug)]
#[cfg(feature = "alloc")]
pub struct BatchConfig {
    /// Maximum batch size
    pub max_batch_size: usize,
    /// Whether to use parallel processing (future extension)
    pub parallel: bool,
    /// Memory allocation strategy
    pub allocation_strategy: AllocationStrategy,
}

#[cfg(feature = "alloc")]
impl Default for BatchConfig {
    fn default() -> Self {
        Self {
            max_batch_size: 1000,
            parallel: false,
            allocation_strategy: AllocationStrategy::default(),
        }
    }
}

/// Memory allocation strategies for batch operations.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum AllocationStrategy {
    /// Pre-allocate all memory upfront
    #[default]
    Preallocate,
    /// Allocate memory as needed
    OnDemand,
    /// Reuse memory from previous operations
    Reuse,
}

/// Builder for batch inversion operations.
#[derive(Clone, Debug)]
#[cfg(feature = "alloc")]
pub struct BatchInverseBuilder<'a> {
    elements: &'a [FieldElement],
    config: BatchConfig,
}

#[cfg(feature = "alloc")]
impl<'a> BatchInverseBuilder<'a> {
    /// Create a new batch inverse builder.
    pub fn new(elements: &'a [FieldElement]) -> Self {
        Self {
            elements,
            config: BatchConfig::default(),
        }
    }

    /// Set maximum batch size.
    pub fn max_batch_size(mut self, size: usize) -> Self {
        self.config.max_batch_size = size;
        self
    }

    /// Enable parallel processing.
    pub fn parallel(mut self, enabled: bool) -> Self {
        self.config.parallel = enabled;
        self
    }

    /// Set allocation strategy.
    pub fn allocation_strategy(mut self, strategy: AllocationStrategy) -> Self {
        self.config.allocation_strategy = strategy;
        self
    }

    /// Get the current maximum batch size.
    pub fn get_max_batch_size(&self) -> usize {
        self.config.max_batch_size
    }

    /// Check if parallel processing is enabled.
    pub fn get_parallel(&self) -> bool {
        self.config.parallel
    }

    /// Get the current allocation strategy.
    pub fn get_allocation_strategy(&self) -> AllocationStrategy {
        self.config.allocation_strategy
    }

    /// Compute the batch inverse.
    pub fn compute(self) -> Result<crate::field::BatchInverseResult, MathError> {
        // For now, delegate to existing implementation
        // In future, this could use the configuration
        crate::field::batch_inverse_checked(self.elements)
    }
}

/// Future operation hooks.
///
/// This trait defines hooks for operations that may be implemented
/// in future versions or by third-party crates.
pub trait FutureOperations {
    /// Reserved for future batch operations.
    fn batch_op_reserved(&self, _op: u32) -> Result<Self, MathError>
    where
        Self: Sized,
    {
        Err(MathError::NotImplemented)
    }

    /// Reserved for future cryptographic operations.
    fn crypto_op_reserved(&self, _op: u32, _params: &[u8]) -> Result<Vec<u8>, MathError> {
        Err(MathError::NotImplemented)
    }

    /// Check if a future operation is supported.
    fn supports_future_op(&self, op: u32) -> bool {
        let _ = op;
        false
    }
}

impl FutureOperations for FieldElement {}

/// Version information for API compatibility.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ApiVersion {
    /// Major version
    pub major: u32,
    /// Minor version
    pub minor: u32,
    /// Patch version
    pub patch: u32,
}

impl ApiVersion {
    /// Current API version.
    pub const CURRENT: ApiVersion = ApiVersion {
        major: 0,
        minor: 8,
        patch: 0,
    };

    /// Check if this version supports a feature.
    pub fn supports(&self, feature: ApiFeature) -> bool {
        match feature {
            ApiFeature::BasicArithmetic => true,
            ApiFeature::BatchOperations => self.minor >= 6,
            ApiFeature::AdvancedArithmetic => self.minor >= 6,
            ApiFeature::ExtensibleApi => self.minor >= 8,
        }
    }
}

/// API features that may be version-dependent.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ApiFeature {
    /// Basic arithmetic operations
    BasicArithmetic,
    /// Batch operations (inversion, exponentiation)
    BatchOperations,
    /// Advanced arithmetic (square root, Legendre symbol)
    AdvancedArithmetic,
    /// Extensible API patterns
    ExtensibleApi,
}

/// Advanced computational traits for future extensibility.
///
/// This trait provides hooks for advanced mathematical operations that
/// may be implemented in future versions or by specialized backends.
///
pub trait AdvancedComputation {
    /// Compute result of a polynomial evaluation.
    ///
    /// Evaluates the polynomial with coefficients `coeffs` at point `x`.
    /// This is useful for advanced cryptographic constructions.
    ///
    #[cfg(feature = "alloc")]
    fn evaluate_polynomial(&self, coeffs: &[Self], x: &Self) -> Self
    where
        Self: Sized;

    /// Compute the greatest common divisor of two elements.
    ///
    /// Extended from the basic gcd to support more advanced use cases.
    ///
    fn gcd_extended(&self, other: &Self) -> Self
    where
        Self: Sized;
}

impl AdvancedComputation for FieldElement {
    #[cfg(feature = "alloc")]
    fn evaluate_polynomial(&self, coeffs: &[Self], x: &Self) -> Self {
        // Horner's method for polynomial evaluation
        let mut result = coeffs
            .last()
            .cloned()
            .unwrap_or_else(|| FieldElement::from_u64(0));

        for coeff in coeffs.iter().rev().skip(1) {
            result = result.mul(x).add(coeff);
        }

        result
    }

    fn gcd_extended(&self, other: &Self) -> Self {
        // For field elements, GCD is always 1 for non-zero elements
        if *self == FieldElement::from_u64(0) && *other == FieldElement::from_u64(0) {
            FieldElement::from_u64(0)
        } else {
            FieldElement::from_u64(1)
        }
    }
}

/// Hardware acceleration traits for future optimized implementations.
///
/// This trait provides hooks for hardware-accelerated operations that
/// may be available on specialized hardware or through optimized libraries.
///
pub trait HardwareAcceleration {
    /// Check if hardware acceleration is available for this operation.
    fn hardware_accelerated(&self, operation: HardwareOperation) -> bool {
        let _ = operation;
        false // No hardware acceleration by default
    }
}

/// Hardware operations that may be accelerated.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum HardwareOperation {
    /// Montgomery multiplication
    MontgomeryMul,
    /// Modular exponentiation
    ModularExp,
    /// Batch inversion
    BatchInverse,
    /// Multi-exponentiation
    MultiExp,
    /// Square root computation
    SquareRoot,
}

impl HardwareAcceleration for FieldElement {}

/// Memory layout optimizations for cache-friendly operations.
///
/// This trait provides hooks for memory layout optimizations that
/// can improve cache performance and memory access patterns.
///
pub trait MemoryOptimization {
    /// Get the preferred memory alignment for this type.
    fn preferred_alignment(&self) -> usize
    where
        Self: Sized,
    {
        core::mem::align_of::<Self>()
    }
}

impl MemoryOptimization for FieldElement {}

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

    #[test]
    fn test_field_extensions() {
        let zero = FieldElement::from_u64(0);
        let one = FieldElement::from_u64(1);
        let four = FieldElement::from_u64(4);

        // Test Legendre symbol
        assert_eq!(zero.legendre(), 0);
        assert_eq!(one.legendre(), 1); // 1 is always a quadratic residue

        // Test quadratic residue check
        assert!(!zero.is_quadratic_residue());
        assert!(one.is_quadratic_residue());

        // Test sqrt for perfect squares
        #[cfg(feature = "alloc")]
        {
            if let Some(sqrt_four) = four.try_sqrt() {
                assert_eq!(sqrt_four.square(), four);
            }
            if let Some(sqrt_one) = one.try_sqrt() {
                assert_eq!(sqrt_one.square(), one);
            }
        }

        // Test order function
        #[cfg(feature = "alloc")]
        {
            // Order of 1 should be 1
            let order_one = one.order();
            assert_eq!(order_one, Some(BigInt::from_u64(1)));

            // Order of 0 should be None (infinite order)
            let order_zero = zero.order();
            assert!(order_zero.is_none());
        }
    }

    #[test]
    fn test_exponentiation_builder() {
        let base = FieldElement::from_u64(2);
        let exp = BigInt::from_u64(10);

        // Test basic builder
        let result = ExponentiationBuilder::new(&base, &exp)
            .algorithm(Algorithm::Binary)
            .build()
            .compute();

        let expected = FieldElement::from_u64(1024); // 2^10
        assert_eq!(result, expected);
    }

    #[test]
    fn test_fixed_window_exponentiation() {
        let base = FieldElement::from_u64(2);

        // Test exponent = 1 (should return base)
        let exp_one = BigInt::from_u64(1);
        let binary_result_one = ExponentiationBuilder::new(&base, &exp_one)
            .algorithm(Algorithm::Binary)
            .build()
            .compute();

        assert_eq!(
            binary_result_one, base,
            "Binary exponentiation with exp=1 should return base"
        );

        let fixed_result_one = ExponentiationBuilder::new(&base, &exp_one)
            .algorithm(Algorithm::FixedWindow(2))
            .build()
            .compute();

        assert_eq!(
            fixed_result_one, base,
            "Fixed window with exp=1 should return base"
        );

        // Test exponent = 0 (should return 1)
        let exp_zero = BigInt::from_u64(0);
        let result_zero = ExponentiationBuilder::new(&base, &exp_zero)
            .algorithm(Algorithm::FixedWindow(2))
            .build()
            .compute();

        assert_eq!(
            result_zero,
            FieldElement::from_u64(1),
            "Fixed window with exp=0 should return 1"
        );

        // Test exponent = 3 (2^3 = 8)
        let exp_three = BigInt::from_u64(3);
        let result_three_binary = ExponentiationBuilder::new(&base, &exp_three)
            .algorithm(Algorithm::Binary)
            .build()
            .compute();

        let result_three_fixed = ExponentiationBuilder::new(&base, &exp_three)
            .algorithm(Algorithm::FixedWindow(2))
            .build()
            .compute();

        assert_eq!(
            result_three_fixed, result_three_binary,
            "Fixed window should match binary for exp=3"
        );

        // Test with different window sizes
        let result_w1 = ExponentiationBuilder::new(&base, &exp_three)
            .algorithm(Algorithm::FixedWindow(1))
            .build()
            .compute();

        let result_w3 = ExponentiationBuilder::new(&base, &exp_three)
            .algorithm(Algorithm::FixedWindow(3))
            .build()
            .compute();

        assert_eq!(result_w1, result_three_binary, "Window size 1 should work");
        assert_eq!(result_w3, result_three_binary, "Window size 3 should work");
    }

    #[test]
    fn test_configurable_arithmetic() {
        let a = FieldElement::from_u64(3);
        let b = FieldElement::from_u64(4);
        let exp = BigInt::from_u64(5);

        // Test multiplication with config
        let mul_config = MultiplicationConfig::default();
        let product = a.mul_with_config(&b, &mul_config);
        assert_eq!(product, FieldElement::from_u64(12));

        // Test different multiplication algorithms
        let karatsuba_config = MultiplicationConfig {
            algorithm: MultiplicationAlgorithm::Karatsuba,
            optimize_squaring: true,
        };
        let product_karatsuba = a.mul_with_config(&b, &karatsuba_config);
        assert_eq!(product_karatsuba, FieldElement::from_u64(12));

        let toom_cook_config = MultiplicationConfig {
            algorithm: MultiplicationAlgorithm::ToomCook,
            optimize_squaring: true,
        };
        let product_toom_cook = a.mul_with_config(&b, &toom_cook_config);
        assert_eq!(product_toom_cook, FieldElement::from_u64(12));

        let fft_config = MultiplicationConfig {
            algorithm: MultiplicationAlgorithm::FFT,
            optimize_squaring: true,
        };
        let product_fft = a.mul_with_config(&b, &fft_config);
        assert_eq!(product_fft, FieldElement::from_u64(12));

        // Test exponentiation with config
        let pow_config = ExponentiationConfig::default();
        let power = a.pow_with_config(&exp, &pow_config);
        assert_eq!(power, FieldElement::from_u64(243)); // 3^5
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn test_batch_builder() {
        let elements = alloc::vec![
            FieldElement::from_u64(2),
            FieldElement::from_u64(3),
            FieldElement::from_u64(5),
        ];

        let result = BatchInverseBuilder::new(&elements)
            .max_batch_size(10)
            .compute()
            .unwrap();

        // Verify inverses
        assert_eq!(elements[0].mul(&result.get(0)), FieldElement::from_u64(1));
        assert_eq!(elements[1].mul(&result.get(1)), FieldElement::from_u64(1));
        assert_eq!(elements[2].mul(&result.get(2)), FieldElement::from_u64(1));
    }

    #[test]
    fn test_api_version() {
        let version = ApiVersion::CURRENT;

        assert!(version.supports(ApiFeature::BasicArithmetic));
        assert!(version.supports(ApiFeature::BatchOperations));
        assert!(version.supports(ApiFeature::AdvancedArithmetic));
        // Extensible API is supported in version 0.8.0+
        assert!(version.supports(ApiFeature::ExtensibleApi));
    }

    #[test]
    fn test_future_operations() {
        let element = FieldElement::from_u64(42);

        // Future operations should not be supported yet
        assert!(!element.supports_future_op(0));
        assert!(matches!(
            element.batch_op_reserved(0),
            Err(MathError::NotImplemented)
        ));
    }
}