lua_stdlib/

math_lib.rs

//! Standard mathematical library — `math.*`
//!
//! Translated from `src/lmathlib.c` (Lua 5.4.7, 782 lines, 28 functions).
//!
//! The PRNG is xoshiro256** operating on four 64-bit words. In C the
//! implementation has two code paths (64-bit integers vs two 32-bit halves);
//! Rust always has `u64`, so only the 64-bit path is kept.
//!
//! Deprecated compat functions guarded by `LUA_COMPAT_MATHLIB` (cosh, sinh,
//! tanh, pow, frexp, ldexp, log10, atan2) ship in the default lua5.3.6 build
//! and are registered only under the 5.3 backend (`luaopen_math` gates them on
//! `LuaVersion::V53`); they remain absent in 5.4/5.5. `atan2` is an alias of
//! the existing `math_atan`. See `specs/followup/5.3-math.md`.

// PORT NOTE: All imports below will be unresolved until Phase B lands the
// lua-types crate. Expected Phase-A errors: E0432, E0412, E0433, E0425.
use lua_types::{LuaError, LuaType, LuaValue};
use crate::state_stub::{LuaState, LuaStateStubExt as _};

// ── Constants ──────────────────────────────────────────────────────────────

///
/// Higher precision than `std::f64::consts::PI`; matches the C source literal.
const PI: f64 = 3.141592653589793238462643383279502884_f64;

/// Number of binary digits in the mantissa of `lua_Number` (f64).
const FIGS: u32 = 53; // DBL_MANT_DIG for f64

/// Bits to discard from the 64-bit random word before float conversion.
const SHIFT64_FIG: u32 = 64 - FIGS; // = 11

// ── Type aliases for library registration ─────────────────────────────────

/// A Lua C-style function: takes the Lua state, returns count of pushed values.
/// PORT NOTE: Phase B will unify with `lua_types::LuaCFunction`.
type LuaCFunction = fn(&mut LuaState) -> Result<usize, LuaError>;

/// An entry in the library registration table (name, optional function).
/// `None` is used for placeholder entries whose values are set manually
/// (e.g. `pi`, `huge`, `maxinteger`, `mininteger`, `random`, `randomseed`).
/// PORT NOTE: Phase B will unify with `lua_types::LibReg`.
#[expect(dead_code, reason = "ported stdlib helper; not yet wired into the runtime")]
struct LibReg {
    name: &'static [u8],
    func: Option<LuaCFunction>,
}

// ── PRNG state ────────────────────────────────────────────────────────────

/// State for the xoshiro256** PRNG.
///
/// In C this is stored as raw `lua_newuserdatauv` memory and accessed by
/// casting the userdata pointer. Until typed-userdata closure upvalues land
/// in Phase B, we keep the PRNG state in a thread-local cell so that
/// `math.random` and `math.randomseed` are callable from Lua. This collapses
/// per-lua_State PRNG isolation to per-thread, which is sufficient for the
/// 5.4 test corpus.
struct RanState {
    s: [u64; 4],
}

thread_local! {
    static RAN_STATE: std::cell::RefCell<RanState> =
        std::cell::RefCell::new(RanState { s: [0xff, 0xff, 0xff, 0xff] });
}

// ── Pure PRNG algorithms ──────────────────────────────────────────────────

/// Advance the xoshiro256** state by one step and return the next raw 64-bit
/// pseudo-random value.
///
fn next_rand(s: &mut [u64; 4]) -> u64 {
    let s0 = s[0];
    let s1 = s[1];
    let s2 = s[2] ^ s0;
    let s3 = s[3] ^ s1;
    let res = s1.wrapping_mul(5).rotate_left(7).wrapping_mul(9);
    s[0] = s0 ^ s3;
    s[1] = s1 ^ s2;
    s[2] = s2 ^ (s1 << 17);
    s[3] = s3.rotate_left(45);
    res
}

/// Convert a raw 64-bit PRNG output to a float in [0.0, 1.0).
///
/// Takes the top FIGS=53 bits, interprets them as a signed integer, scales
/// by `scaleFIG = 0.5 / 2^52`, then corrects the two's-complement sign.
fn rand_to_float(x: u64) -> f64 {
    let sx = (x >> SHIFT64_FIG) as i64;
    //            = 0.5 / 2^52
    let scale_fig: f64 = 0.5 / ((1u64 << (FIGS - 1)) as f64);
    let mut res = (sx as f64) * scale_fig;
    if sx < 0 {
        res += 1.0;
    }
    debug_assert!(0.0 <= res && res < 1.0);
    res
}

/// Initialise the four PRNG words from two seed values.
///
///
/// PORT NOTE: The Lua pushes (n1, n2) are done at the call site in Rust so
/// that this function does not need `&mut LuaState`, avoiding a borrow
/// conflict with the upvalue `RanState`.
fn set_seed_words(s: &mut [u64; 4], n1: u64, n2: u64) {
    s[0] = n1;
    s[1] = 0xff; // avoid a zero state
    s[2] = n2;
    s[3] = 0;
    for _ in 0..16 {
        next_rand(s); // discard initial values to "spread" seed
    }
}

/// Project `ran` uniformly into [0, n].
///
///
/// Uses rejection sampling with the smallest Mersenne number ≥ n as a mask.
/// Takes `&mut [u64; 4]` rather than `&mut RanState` to avoid nested borrows
/// at call sites.
fn project(mut ran: u64, n: u64, s: &mut [u64; 4]) -> u64 {
    if (n & n.wrapping_add(1)) == 0 {
        return ran & n;
    }
    // Compute the smallest (2^b - 1) not smaller than n.
    let mut lim = n;
    lim |= lim >> 1;
    lim |= lim >> 2;
    lim |= lim >> 4;
    lim |= lim >> 8;
    lim |= lim >> 16;
    lim |= lim >> 32; // u64 always has 64 bits; C guards this with #if
    debug_assert!((lim & lim.wrapping_add(1)) == 0); // lim+1 is a power of 2
    debug_assert!(lim >= n);
    debug_assert!((lim >> 1) < n);
    loop {
        ran &= lim;
        if ran <= n {
            break;
        }
        ran = next_rand(s);
    }
    ran
}

// ── Helpers ───────────────────────────────────────────────────────────────

/// Convert `d` to integer and push it; push the float unchanged if it doesn't
/// fit exactly in an i64.
///
fn push_num_int(state: &mut LuaState, d: f64) {
    //    else lua_pushnumber(L, d);
    //
    // lua_numbertointeger: d >= LUA_MININTEGER as float &&
    //                      d <  -(LUA_MININTEGER as float)
    let min_f = i64::MIN as f64; // -2^63
    let max_plus1_f = -(i64::MIN as f64); // 2^63 (one past i64::MAX as float)
    if d >= min_f && d < max_plus1_f {
        state.push(LuaValue::Int(d as i64));
    } else {
        state.push(LuaValue::Float(d));
    }
}

// ── Basic math functions ──────────────────────────────────────────────────

/// `math.abs(x)` — absolute value, preserving integer type when possible.
///
fn math_abs(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.value_at(1), LuaValue::Int(_)) {
        let n = state.to_integer(1).unwrap_or(0);
        let n = if n < 0 {
            (0u64.wrapping_sub(n as u64)) as i64
        } else {
            n
        };
        state.push(LuaValue::Int(n));
    } else {
        let x = state.check_number(1)?;
        state.push(LuaValue::Float(x.abs()));
    }
    Ok(1)
}

/// `math.sin(x)` — sine (radians).
///
fn math_sin(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.sin()));
    Ok(1)
}

/// `math.cos(x)` — cosine (radians).
///
fn math_cos(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.cos()));
    Ok(1)
}

/// `math.tan(x)` — tangent (radians).
///
fn math_tan(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.tan()));
    Ok(1)
}

/// `math.asin(x)` — arc-sine, result in radians.
///
fn math_asin(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.asin()));
    Ok(1)
}

/// `math.acos(x)` — arc-cosine, result in radians.
///
fn math_acos(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.acos()));
    Ok(1)
}

/// `math.atan(y [, x])` — arc-tangent of y/x (defaults x=1), result in
/// radians. Subsumes C's `atan2` when x is provided.
///
fn math_atan(state: &mut LuaState) -> Result<usize, LuaError> {
    let y = state.check_number(1)?;
    let x = state.opt_number(2, 1.0)?;
    state.push(LuaValue::Float(y.atan2(x)));
    Ok(1)
}

/// `math.cosh(x)` — hyperbolic cosine. Deprecated `LUA_COMPAT_MATHLIB`
/// function, registered only under the 5.3 backend.
///
fn math_cosh(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.cosh()));
    Ok(1)
}

/// `math.sinh(x)` — hyperbolic sine. Deprecated `LUA_COMPAT_MATHLIB`
/// function, registered only under the 5.3 backend.
///
fn math_sinh(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.sinh()));
    Ok(1)
}

/// `math.tanh(x)` — hyperbolic tangent. Deprecated `LUA_COMPAT_MATHLIB`
/// function, registered only under the 5.3 backend.
///
fn math_tanh(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.tanh()));
    Ok(1)
}

/// `math.pow(x, y)` — x raised to the power y, always returning a float.
/// Deprecated `LUA_COMPAT_MATHLIB` function, registered only under the 5.3
/// backend. Mirrors C `pow(luaL_checknumber, luaL_checknumber)`.
///
fn math_pow(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    let y = state.check_number(2)?;
    state.push(LuaValue::Float(x.powf(y)));
    Ok(1)
}

/// `math.log10(x)` — base-10 logarithm. Deprecated `LUA_COMPAT_MATHLIB`
/// function, registered only under the 5.3 backend.
///
fn math_log10(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.log10()));
    Ok(1)
}

/// `math.ldexp(x, e)` — `x * 2^e`. Deprecated `LUA_COMPAT_MATHLIB` function,
/// registered only under the 5.3 backend. The exponent is an integer argument
/// truncated to C `int` range, matching `ldexp(x, (int)luaL_checkinteger)`.
///
fn math_ldexp(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    let e = state.check_integer(2)? as i32;
    state.push(LuaValue::Float(ldexp(x, e)));
    Ok(1)
}

/// Pure `ldexp`: returns `x * 2^exp` with C `ldexp` semantics.
///
/// A naive `x * 2f64.powi(exp)` underflows (or overflows) the intermediate
/// `2^exp` for large-magnitude exponents, losing subnormal results such as
/// `ldexp(1.0, -1074) == 5e-324`. The scaling is therefore applied in bounded
/// steps so no intermediate factor under/overflows: each step multiplies by a
/// power of two whose magnitude stays inside the normal `f64` range.
fn ldexp(x: f64, exp: i32) -> f64 {
    if x == 0.0 || !x.is_finite() {
        return x;
    }
    let mut result = x;
    let mut e = exp;
    // 2^1023 is the largest power of two representable as a normal f64; chunk
    // the exponent so each `from_bits` factor is always finite and nonzero.
    while e > 1023 {
        result *= f64::from_bits(0x7feu64 << 52); // 2^1023
        e -= 1023;
    }
    while e < -1022 {
        result *= f64::from_bits(0x001u64 << 52); // 2^-1022 (smallest normal)
        e += 1022;
    }
    result * f64::from_bits(((e + 1023) as u64) << 52)
}

/// `math.frexp(x)` — split x into a normalized mantissa and an exponent such
/// that `x == mantissa * 2^exponent` with `0.5 <= |mantissa| < 1`. Returns the
/// float mantissa followed by the **integer** exponent, matching C
/// `frexp` + `lua_pushinteger`. Deprecated `LUA_COMPAT_MATHLIB` function,
/// registered only under the 5.3 backend.
///
/// Rust std has no `frexp`; this replicates C `frexp` via `f64` bit
/// manipulation, including the `frexp(0.0) == (0.0, 0)` special case (and the
/// matching `-0.0`, infinity, and NaN cases, which C leaves unchanged with a
/// zero exponent).
fn math_frexp(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    let (mantissa, exponent) = frexp(x);
    state.push(LuaValue::Float(mantissa));
    state.push(LuaValue::Int(exponent as i64));
    Ok(2)
}

/// Pure `frexp`: returns `(mantissa, exponent)` with `x == mantissa * 2^exp`.
///
/// Replicates C `frexp` semantics for f64. Zero, infinity, and NaN are
/// returned unchanged with a zero exponent.
fn frexp(x: f64) -> (f64, i32) {
    if x == 0.0 || !x.is_finite() {
        return (x, 0);
    }
    let bits = x.to_bits();
    let raw_exp = ((bits >> 52) & 0x7ff) as i32;
    if raw_exp == 0 {
        // Subnormal: scale up by 2^54 to normalize, then correct the exponent.
        let (m, e) = frexp(x * (1u64 << 54) as f64);
        return (m, e - 54);
    }
    // Bias the exponent so the mantissa lands in [0.5, 1): set the stored
    // exponent field to 0x3fe (unbiased -1).
    let exponent = raw_exp - 1022;
    let mantissa_bits = (bits & !(0x7ffu64 << 52)) | (0x3feu64 << 52);
    (f64::from_bits(mantissa_bits), exponent)
}

/// `math.tointeger(x)` — convert x to an integer or return false.
///
fn math_toint(state: &mut LuaState) -> Result<usize, LuaError> {
    // TODO(port): state.to_integer_opt(1) should return Option<i64>;
    // the method name/signature will be confirmed in Phase B.
    let maybe_n: Option<i64> = state.to_integer_opt(1);
    if let Some(n) = maybe_n {
        state.push(LuaValue::Int(n));
    } else {
        state.check_any(1)?;
        // luaL_pushfail expands to lua_pushnil in the default 5.3/5.4/5.5
        // builds; only a LUA_FAILISFALSE build pushes false, which the oracle
        // contract pins off.
        state.push(LuaValue::Nil);
    }
    Ok(1)
}

/// `math.floor(x)` — largest integer ≤ x.
///
fn math_floor(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.value_at(1), LuaValue::Int(_)) {
        // Must go through the public C-API set_top (relative to the call
        // frame); the inherent LuaState::set_top treats its argument as an
        // absolute StackIdx.
        lua_vm::api::set_top(state, 1)?;
    } else {
        let d = state.check_number(1)?.floor();
        push_num_int(state, d);
    }
    Ok(1)
}

/// `math.ceil(x)` — smallest integer ≥ x.
///
fn math_ceil(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.value_at(1), LuaValue::Int(_)) {
        // Public C-API set_top (relative); inherent LuaState::set_top is absolute.
        lua_vm::api::set_top(state, 1)?;
    } else {
        let d = state.check_number(1)?.ceil();
        push_num_int(state, d);
    }
    Ok(1)
}

/// `math.fmod(x, y)` — floating-point remainder (same sign as x).
///
fn math_fmod(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.value_at(1), LuaValue::Int(_))
        && matches!(state.value_at(2), LuaValue::Int(_))
    {
        let a = state.to_integer(1).unwrap_or(0);
        let d = state.to_integer(2).unwrap_or(0);
        if (d as u64).wrapping_add(1) <= 1 {
            if d == 0 {
                return Err(lua_vm::debug::arg_error_impl(state, 2, b"zero"));
            }
            state.push(LuaValue::Int(0));
        } else {
            state.push(LuaValue::Int(a % d));
        }
    } else {
        let x = state.check_number(1)?;
        let y = state.check_number(2)?;
        state.push(LuaValue::Float(x % y));
    }
    Ok(1)
}

/// `math.modf(x)` — split into integer and fractional parts; returns 2 values.
///
///
/// PORT NOTE: Does not use `modf` (avoids `double *` / `float *` ABI mismatch
/// for non-double `lua_Number`). Instead, uses ceil/floor + subtraction.
fn math_modf(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.value_at(1), LuaValue::Int(_)) {
        // Public C-API set_top (relative); inherent LuaState::set_top is absolute.
        lua_vm::api::set_top(state, 1)?; // integer part is the integer itself
        state.push(LuaValue::Float(0.0)); // no fractional part
    } else {
        let n = state.check_number(1)?;
        let ip = if n < 0.0 { n.ceil() } else { n.floor() };
        push_num_int(state, ip);
        let frac = if n == ip { 0.0 } else { n - ip };
        state.push(LuaValue::Float(frac));
    }
    Ok(2)
}

/// `math.sqrt(x)` — square root.
///
fn math_sqrt(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.sqrt()));
    Ok(1)
}

/// `math.ult(m, n)` — unsigned less-than on integers.
///
fn math_ult(state: &mut LuaState) -> Result<usize, LuaError> {
    let a = state.check_integer(1)?;
    let b = state.check_integer(2)?;
    state.push(LuaValue::Bool((a as u64) < (b as u64)));
    Ok(1)
}

/// `math.log(x [, base])` — logarithm; natural if base omitted.
///
fn math_log(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    // Lua 5.1's `math.log` takes a single argument and silently ignores any
    // second; the two-argument base form is a 5.2 addition. Verified against
    // lua5.1.5: `math.log(8,2) == math.log(8) == ln(8)`, and a second arg never
    // errors. See specs/followup/5.1-roster-syntax.md §1.
    if matches!(state.global().lua_version, lua_types::LuaVersion::V51) {
        state.push(LuaValue::Float(x.ln()));
        return Ok(1);
    }
    let res = if matches!(state.type_at(2), LuaType::None | LuaType::Nil) {
        x.ln()
    } else {
        let base = state.check_number(2)?;
        if base == 2.0 {
            x.log2()
        } else if base == 10.0 {
            x.log10()
        } else {
            x.ln() / base.ln()
        }
    };
    state.push(LuaValue::Float(res));
    Ok(1)
}

/// `math.exp(x)` — e raised to the power x.
///
fn math_exp(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x.exp()));
    Ok(1)
}

/// `math.deg(x)` — convert radians to degrees.
///
fn math_deg(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x * (180.0 / PI)));
    Ok(1)
}

/// `math.rad(x)` — convert degrees to radians.
///
fn math_rad(state: &mut LuaState) -> Result<usize, LuaError> {
    let x = state.check_number(1)?;
    state.push(LuaValue::Float(x * (PI / 180.0)));
    Ok(1)
}

/// `math.min(x, ...)` — minimum of all arguments (uses Lua `<` comparison).
///
fn math_min(state: &mut LuaState) -> Result<usize, LuaError> {
    let n = state.get_top();
    let mut imin: i32 = 1;
    if n < 1 {
        return Err(lua_vm::debug::arg_error_impl(state, 1, b"value expected"));
    }
    for i in 2..=n {
        if state.compare_lt(i, imin)? {
            imin = i;
        }
    }
    state.push_value(imin)?;
    Ok(1)
}

/// `math.max(x, ...)` — maximum of all arguments (uses Lua `<` comparison).
///
fn math_max(state: &mut LuaState) -> Result<usize, LuaError> {
    let n = state.get_top();
    let mut imax: i32 = 1;
    if n < 1 {
        return Err(lua_vm::debug::arg_error_impl(state, 1, b"value expected"));
    }
    for i in 2..=n {
        if state.compare_lt(imax, i)? {
            imax = i;
        }
    }
    state.push_value(imax)?;
    Ok(1)
}

/// `math.type(x)` — return `"integer"`, `"float"`, or nil for non-numbers.
///
fn math_type(state: &mut LuaState) -> Result<usize, LuaError> {
    if matches!(state.type_at(1), LuaType::Number) {
        if matches!(state.value_at(1), LuaValue::Int(_)) {
            state.push_string(b"integer")?;
        } else {
            state.push_string(b"float")?;
        }
    } else {
        state.check_any(1)?;
        // luaL_pushfail expands to lua_pushnil in the default 5.3/5.4/5.5
        // builds; only a LUA_FAILISFALSE build pushes false, which the oracle
        // contract pins off.
        state.push(LuaValue::Nil);
    }
    Ok(1)
}

// ── PRNG-backed Lua functions ─────────────────────────────────────────────

/// `math.random([m [, n]])` — pseudo-random number generation.
///
///
/// With no arguments: float in [0, 1).
/// With one argument n: integer in [1, n] (or full random u64 if n == 0).
/// With two arguments m, n: integer in [m, n].
fn math_random(state: &mut LuaState) -> Result<usize, LuaError> {
    // TODO(port): RanState is stored as typed userdata in closure upvalue 1.
    // Phase B must implement `state.upvalue_userdata_mut::<RanState>(1)` using
    // interior mutability (e.g. GcRef<RefCell<RanState>>) to avoid the borrow
    // conflict between &mut RanState and subsequent &mut LuaState push calls.
    //
    // For Phase A: advance PRNG and get args via separate borrows.
    let rv = advance_prng(state)?;
    let n_args = state.get_top();

    if n_args == 0 {
        state.push(LuaValue::Float(rand_to_float(rv)));
        return Ok(1);
    }

    let version = state.global().lua_version;
    let is_v53 = version == lua_types::LuaVersion::V53;
    // 5.1/5.2 are float-only and use the C `rand()` contract: there is no
    // `random(0)` full-range special case (that is a 5.4/5.5 addition), the
    // empty-interval error for `random(m, n)` reports argument index 2 (the
    // upper bound), and integer-valued results are pushed as `Float` to honour
    // the never-construct-`Int` invariant under `FloatOnly`. See
    // specs/followup/5.1-numbers-prng.md §"Impl seams".
    let float_only = version.number_model() == lua_types::NumberModel::FloatOnly;

    let (low, up, empty_arg) = match n_args {
        1 => {
            let up = state.check_integer(1)?;
            // 5.4/5.5 `random(0)` returns a full-range integer; 5.1/5.2/5.3 have
            // no such special case — it is `[1, 0]`, an empty interval.
            if up == 0 && !is_v53 && !float_only {
                // I2UInt(rv) = rv (trivial for u64)
                state.push(LuaValue::Int(rv as i64));
                return Ok(1);
            }
            (1i64, up, 1)
        }
        2 => {
            let low = state.check_integer(1)?;
            let up = state.check_integer(2)?;
            // 5.1's `luaL_checkint(L, 2)` for the upper bound means its
            // empty-interval `luaL_argerror` reports argument #2; the modern
            // bodies report #1.
            let empty_arg = if float_only { 2 } else { 1 };
            (low, up, empty_arg)
        }
        _ => {
            return Err(LuaError::runtime(format_args!(
                "wrong number of arguments"
            )));
        }
    };

    if low > up {
        return Err(lua_vm::debug::arg_error_impl(state, empty_arg, b"interval is empty"));
    }

    // 5.3 `math_random` rejects intervals whose width overflows a signed integer
    // (`low >= 0 || up <= LUA_MAXINTEGER + low`). 5.4/5.5 use the `project`
    // bit-mask algorithm, which handles the full range without erroring.
    if is_v53 && !(low >= 0 || up <= i64::MAX.wrapping_add(low)) {
        return Err(lua_vm::debug::arg_error_impl(state, 1, b"interval too large"));
    }

    let range = (up as u64).wrapping_sub(low as u64);
    let p = project_from_upvalue(state, rv, range)?;
    let result = (p as u64).wrapping_add(low as u64) as i64;
    if float_only {
        state.push(LuaValue::Float(result as f64));
    } else {
        state.push(LuaValue::Int(result));
    }
    Ok(1)
}

/// `math.randomseed([x [, y]])` — seed the PRNG; returns two seed values.
///
fn math_randomseed(state: &mut LuaState) -> Result<usize, LuaError> {
    // TODO(port): same upvalue userdata access issue as math_random.
    //
    // 5.1's `math.randomseed` is `l_srand((unsigned int)luaL_checknumber(L, 1))`:
    // the seed argument is REQUIRED (no auto-seed when absent — a missing arg
    // raises "number expected, got no value"), and the function returns **no**
    // values (the seed-word push is a 5.4/5.5 behavior). 5.2 also requires the
    // seed but its `luaL_checknumber` floors and likewise returns nothing; the
    // modern (5.3+) bodies auto-seed when absent and return the two seed words.
    // See specs/followup/5.1-numbers-prng.md.
    let float_only =
        state.global().lua_version.number_model() == lua_types::NumberModel::FloatOnly;

    if matches!(state.type_at(1), LuaType::None) {
        if float_only {
            // No auto-seed under 5.1/5.2; the missing arg is an error.
            let n1 = state.check_integer(1)? as u64;
            apply_set_seed_quiet(state, n1, 0);
            return Ok(0);
        }
        // randseed uses time(NULL) and address of L for entropy.
        apply_random_seed(state)?;
    } else {
        //    lua_Integer n2 = luaL_optinteger(L, 2, 0);
        let n1 = state.check_integer(1)? as u64;
        if float_only {
            // 5.1/5.2 take a single seed and return nothing.
            apply_set_seed_quiet(state, n1, 0);
            return Ok(0);
        }
        let n2 = state.opt_integer(2, 0)? as u64;
        apply_set_seed(state, n1, n2)?;
    }
    Ok(2)
}

/// Advance the PRNG stored in the thread-local `RAN_STATE` and return the
/// raw 64-bit output.
///
/// PORT NOTE: In C this draws from the userdata in closure upvalue 1. The
/// Rust port stores the PRNG state in a thread-local until typed-userdata
/// closure upvalues are wired up. Storage location is the only difference;
/// the algorithm is unchanged.
fn advance_prng(_state: &mut LuaState) -> Result<u64, LuaError> {
    Ok(RAN_STATE.with(|r| next_rand(&mut r.borrow_mut().s)))
}

/// Apply rejection sampling for `math.random` using the thread-local PRNG.
///
/// PORT NOTE: see `advance_prng` for the thread-local rationale.
fn project_from_upvalue(
    _state: &mut LuaState,
    ran: u64,
    n: u64,
) -> Result<u64, LuaError> {
    Ok(RAN_STATE.with(|r| project(ran, n, &mut r.borrow_mut().s)))
}

/// Seed the PRNG from wall-clock time (entropy source).
///
///
/// TODO(port): must write n1 and n2 back to the upvalue RanState.
fn apply_random_seed(state: &mut LuaState) -> Result<(), LuaError> {
    let entropy = state.global().entropy_hook.map(|hook| hook()).unwrap_or(0);
    let seed1 = entropy;
    // TODO(port): C also mixes address entropy; keep the second seed derived
    // deterministically unless a richer host entropy API is added.
    let seed2: u64 = entropy.rotate_left(17) ^ 0x9e37_79b9_7f4a_7c15;
    apply_set_seed(state, seed1, seed2)
}

/// Apply explicit seeds to the PRNG and push them onto the stack.
///
///
/// PORT NOTE: writes seeds into the thread-local RanState (see `advance_prng`).
fn apply_set_seed(state: &mut LuaState, n1: u64, n2: u64) -> Result<(), LuaError> {
    RAN_STATE.with(|r| set_seed_words(&mut r.borrow_mut().s, n1, n2));
    state.push(LuaValue::Int(n1 as i64));
    state.push(LuaValue::Int(n2 as i64));
    Ok(())
}

/// Seed the PRNG without pushing the seed words onto the stack.
///
/// 5.1/5.2 `math.randomseed` returns no values, so its seeding path must not
/// push (unlike the modern [`apply_set_seed`], which returns the two words).
fn apply_set_seed_quiet(_state: &mut LuaState, n1: u64, n2: u64) {
    RAN_STATE.with(|r| set_seed_words(&mut r.borrow_mut().s, n1, n2));
}

/// Register `math.random` and `math.randomseed` on the math library table at
/// stack top, after seeding the thread-local PRNG.
///
///
/// PORT NOTE: C stores the PRNG inside a userdata bound as upvalue 1 of both
/// closures. Until typed userdata closure upvalues are available, the Rust
/// port keeps the PRNG in a thread-local (see `RAN_STATE`) and registers the
/// functions as plain non-closure entries on the library table.
fn set_rand_func(state: &mut LuaState) -> Result<(), LuaError> {
    apply_random_seed(state)?;
    state.pop_n(2);

    state.push_c_function(math_random)?;
    state.set_field(-2, b"random")?;
    state.push_c_function(math_randomseed)?;
    state.set_field(-2, b"randomseed")?;
    Ok(())
}

// ── Library registration table ────────────────────────────────────────────

/// The `math` library function table.
///
///
/// Placeholder entries (`None`) are filled in manually by `luaopen_math`
/// (`pi`, `huge`, `maxinteger`, `mininteger`) or by `set_rand_func`
/// (`random`, `randomseed`).
#[expect(dead_code, reason = "ported stdlib helper; not yet wired into the runtime")]
static MATHLIB: &[LibReg] = &[
    LibReg { name: b"abs",        func: Some(math_abs)    },
    LibReg { name: b"acos",       func: Some(math_acos)   },
    LibReg { name: b"asin",       func: Some(math_asin)   },
    LibReg { name: b"atan",       func: Some(math_atan)   },
    LibReg { name: b"ceil",       func: Some(math_ceil)   },
    LibReg { name: b"cos",        func: Some(math_cos)    },
    LibReg { name: b"deg",        func: Some(math_deg)    },
    LibReg { name: b"exp",        func: Some(math_exp)    },
    LibReg { name: b"tointeger",  func: Some(math_toint)  },
    LibReg { name: b"floor",      func: Some(math_floor)  },
    LibReg { name: b"fmod",       func: Some(math_fmod)   },
    LibReg { name: b"ult",        func: Some(math_ult)    },
    LibReg { name: b"log",        func: Some(math_log)    },
    LibReg { name: b"max",        func: Some(math_max)    },
    LibReg { name: b"min",        func: Some(math_min)    },
    LibReg { name: b"modf",       func: Some(math_modf)   },
    LibReg { name: b"rad",        func: Some(math_rad)    },
    LibReg { name: b"sin",        func: Some(math_sin)    },
    LibReg { name: b"sqrt",       func: Some(math_sqrt)   },
    LibReg { name: b"tan",        func: Some(math_tan)    },
    LibReg { name: b"type",       func: Some(math_type)   },
    // Placeholders; values are set manually in luaopen_math / set_rand_func.
    LibReg { name: b"random",     func: None },
    LibReg { name: b"randomseed", func: None },
    LibReg { name: b"pi",         func: None },
    LibReg { name: b"huge",       func: None },
    LibReg { name: b"maxinteger", func: None },
    LibReg { name: b"mininteger", func: None },
];

static MATHLIB_FUNCS: &[(&[u8], LuaCFunction)] = &[
    (b"abs",        math_abs),
    (b"acos",       math_acos),
    (b"asin",       math_asin),
    (b"atan",       math_atan),
    (b"ceil",       math_ceil),
    (b"cos",        math_cos),
    (b"deg",        math_deg),
    (b"exp",        math_exp),
    (b"tointeger",  math_toint),
    (b"floor",      math_floor),
    (b"fmod",       math_fmod),
    (b"ult",        math_ult),
    (b"log",        math_log),
    (b"max",        math_max),
    (b"min",        math_min),
    (b"modf",       math_modf),
    (b"rad",        math_rad),
    (b"sin",        math_sin),
    (b"sqrt",       math_sqrt),
    (b"tan",        math_tan),
    (b"type",       math_type),
    // `frexp`/`ldexp` are registered unconditionally in lua5.4.7 and lua5.5.0
    // (their `lmathlib.c` places these two outside the `LUA_COMPAT_MATHLIB`
    // `#if`) and are part of the 5.3 compat roster too. Verified against all
    // three reference binaries: `type(math.frexp)`/`type(math.ldexp)` ==
    // "function" on 5.3.6, 5.4.7, and 5.5.0.
    (b"frexp",      math_frexp),
    (b"ldexp",      math_ldexp),
];

// ── Module entry point ────────────────────────────────────────────────────

/// Open the `math` library: create the table, populate constants, register
/// the PRNG functions with their shared `RanState` upvalue.
///
///
/// `LUAMOD_API` → `pub` (see macros.tsv).
pub fn luaopen_math(state: &mut LuaState) -> Result<usize, LuaError> {
    // Creates a new table and registers all non-None entries from MATHLIB.
    state.new_lib(MATHLIB_FUNCS)?;

    // Per-version roster delta: the `LUA_COMPAT_MATHLIB`-gated functions
    // (`atan2` as an alias of `math_atan`, plus cosh/sinh/tanh/pow/log10) ship
    // in the default lua5.3.6 build (`LUA_COMPAT_MATHLIB` on) AND the default
    // lua5.4.7 build (its `LUA_COMPAT_5_3` umbrella turns `LUA_COMPAT_MATHLIB`
    // on), but were dropped in lua5.5.0 (macro commented out). Verified by
    // probing all three reference binaries directly. `frexp`/`ldexp` are NOT in
    // this set — they survive into 5.5 and live in the agnostic roster above.
    // `new_lib` leaves the new table on the stack top, so we register into it
    // directly. See `specs/followup/5.3-math.md` (whose 5.4/5.5-absence claim
    // is corrected here against the binaries, the binding oracle).
    // The `LUA_COMPAT_MATHLIB` deprecated roster also ships in the default
    // lua5.2.4 build (verified against the reference binary: `type(math.atan2)`
    // etc. == "function" on 5.2.4). 5.5 drops them.
    if matches!(
        state.global().lua_version,
        lua_types::LuaVersion::V51
            | lua_types::LuaVersion::V52
            | lua_types::LuaVersion::V53
            | lua_types::LuaVersion::V54
    ) {
        const COMPAT_MATH_FUNCS: &[(&[u8], LuaCFunction)] = &[
            (b"atan2",  math_atan),
            (b"cosh",   math_cosh),
            (b"sinh",   math_sinh),
            (b"tanh",   math_tanh),
            (b"pow",    math_pow),
            (b"log10",  math_log10),
        ];
        state.set_funcs_with_upvalues(COMPAT_MATH_FUNCS, 0)?;
    }

    // Lua 5.1 carries `math.mod`, a compat alias of `fmod` predating the rename
    // (`math.mod(7,3) == 1`). It was removed in 5.2. Verified against
    // lua5.1.5: `type(math.mod)` == "function". See
    // specs/followup/5.1-roster-syntax.md §1.
    if matches!(state.global().lua_version, lua_types::LuaVersion::V51) {
        state.push_c_function(math_fmod)?;
        state.set_field(-2, b"mod")?;
    }

    state.push(LuaValue::Float(PI));
    state.set_field(-2, b"pi")?;

    state.push(LuaValue::Float(f64::INFINITY));
    state.set_field(-2, b"huge")?;

    // LUA_MAXINTEGER = i64::MAX (lua_Integer is int64_t in default config).
    state.push(LuaValue::Int(i64::MAX));
    state.set_field(-2, b"maxinteger")?;

    state.push(LuaValue::Int(i64::MIN));
    state.set_field(-2, b"mininteger")?;

    // Lua 5.1/5.2 are float-only: the integer-subtype helpers (`math.type`,
    // `math.tointeger`, `math.ult`) and the integer bounds
    // (`math.maxinteger`/`mininteger`) are 5.3 additions and are absent there.
    // Verified against lua5.2.4: each is `nil`.
    if matches!(
        state.global().lua_version,
        lua_types::LuaVersion::V51 | lua_types::LuaVersion::V52
    ) {
        for field in [
            &b"type"[..],
            &b"tointeger"[..],
            &b"ult"[..],
            &b"maxinteger"[..],
            &b"mininteger"[..],
        ] {
            state.push(LuaValue::Nil);
            state.set_field(-2, field)?;
        }
    }

    // Registers math.random and math.randomseed as upvalue-bearing closures.
    set_rand_func(state)?;

    Ok(1)
}

// ──────────────────────────────────────────────────────────────────────────
// PORT STATUS
//   source:        src/lmathlib.c  (782 lines, 28 functions)
//   target_crate:  lua-stdlib
//   confidence:    medium
//   todos:         16
//   port_notes:    8
//   unsafe_blocks: 0
//   notes:         All basic math functions are mechanically faithful. The
//                  PRNG xoshiro256** algorithm is correctly translated using
//                  native u64 (only the 64-bit code path; the 32-bit fallback
//                  is dropped). The main Phase-B work is wiring up the upvalue
//                  RanState userdata: advance_prng, project_from_upvalue,
//                  apply_random_seed, apply_set_seed, and set_rand_func all
//                  carry TODO(port) stubs where typed userdata + interior
//                  mutability (RefCell) is required to avoid borrow conflicts.
//                  Deprecated LUA_COMPAT_MATHLIB functions (cosh, sinh, tanh,
//                  pow, log10, ldexp, frexp, atan2) are registered only under
//                  the 5.3 backend per specs/followup/5.3-math.md; absent in
//                  5.4/5.5. atan2 reuses math_atan; frexp is implemented via
//                  f64 bit manipulation (no Rust std frexp).
//                  state.new_lib, state.set_field,
//                  state.compare_lt, state.push_value, state.opt_number,
//                  state.opt_integer, state.check_integer, state.check_number,
//                  state.check_any, state.to_integer_opt, state.get_top,
//                  state.set_top, state.pop_n API names assumed; Phase B
//                  will reconcile with the actual LuaState impl.
// ──────────────────────────────────────────────────────────────────────────