NPER

4 nper_fn "NPER" (3, 5) [V "rate", V "pmt", V "pv", V "fv", V "type"] |s, a, sv| {
    let t = timing(s, a, 4)?;
    tv_out(s, tv::nper(num(s, a, 0)?, num(s, a, 1)?, num(s, a, 2)?, opt(s, a, 3, 0.0)?, t))
}

/// Worksheet `NPER` — bit-exact to 64-bit Excel on `x86_64` (W109 Phase 2,
/// identified by calculation-graph search; 1,729/1,729 live main-path
/// witnesses bit-exact, max ULP 0, build 20131). The body is the legacy x87
/// spill loop — every arithmetic assignment is double-rounded
/// (`RN53(RN64(op))`) and both logarithms are the x87 worksheet `ln`:
///
/// ```text
/// rate == 0 (either sign, EXACT — no epsilon band):
///     nper = RN53(RN64( -(RN53(RN64(fv+pv))) / pmt ))     (#DIV/0! on pmt=0)
/// else:
///     tf    = RN53(RN64(1 + rate·type))
///     tfp   = RN53(RN64(tf·pmt))
///     num   = RN53(RN64(tfp - RN53(RN64(fv·rate))))
///     den   = RN53(RN64(tfp + RN53(RN64(pv·rate))))
///     ratio = RN53(RN64(num/den))                          (ratio<=0 -> #NUM!)
///     nper  = RN53(RN64( ln_x87(ratio) / ln_x87(RN53(RN64(1+rate))) ))
///             (1+rate rounding to 1 -> ln=0 -> #DIV/0!, live-probed;
///              1+rate <= 0 -> #NUM!)
/// ```
///
/// Live-probed lanes: tiny nonzero rates take the MAIN path (degrading
/// numerically exactly like Excel, then #DIV/0! once `1+rate == 1`);
/// `NPER(0, 0, ..)` is `#DIV/0!`; `rate <= -1` is `#NUM!`. This replaces the
/// former portable-CR-log path and its `EPSILON` small-rate band (both ruled
/// out by the oracle bits — see DISCREPANCY_RULED_OUT_LEDGER.csv G6-08).
pub fn nper(
    periodic_rate: f64,
    payment_value: f64,
    present_value: f64,
    future_value: f64,
    timing: PaymentTiming,
) -> Result<f64, FinancialError> {
    use crate::ported::excel_numeric::{
        excel_log, excel_x87_add, excel_x87_div, excel_x87_mul, excel_x87_sub,
    };

    validate_finite(&[periodic_rate, payment_value, present_value, future_value])?;
    if periodic_rate == 0.0 {
        if payment_value == 0.0 {
            return Err(FinancialError::Div0); // live-probed: #DIV/0!
        }
        let sum = excel_x87_add(future_value, present_value);
        let result = excel_x87_div(-sum, payment_value);
        return if result.is_finite() {
            Ok(result)
        } else {
            Err(FinancialError::Num)
        };
    }
    let tf = match timing {
        PaymentTiming::EndOfPeriod => 1.0,
        PaymentTiming::BeginningOfPeriod => excel_x87_add(1.0, periodic_rate),
    };
    let tf_pmt = excel_x87_mul(tf, payment_value);
    let numerator = excel_x87_sub(tf_pmt, excel_x87_mul(future_value, periodic_rate));
    let denominator = excel_x87_add(tf_pmt, excel_x87_mul(present_value, periodic_rate));
    let ratio = excel_x87_div(numerator, denominator);
    if ratio <= 0.0 || !ratio.is_finite() {
        return Err(FinancialError::Num);
    }
    let base = excel_x87_add(1.0, periodic_rate);
    if base <= 0.0 {
        return Err(FinancialError::Num);
    }
    let ln_den = excel_log(base);
    if ln_den == 0.0 {
        return Err(FinancialError::Div0); // 1+rate rounded to 1 (live-probed)
    }
    let result = excel_x87_div(excel_log(ratio), ln_den);
    if result.is_finite() {
        Ok(result)
    } else {
        Err(FinancialError::Num)
    }
}