coremlit 0.1.0

//! Front-end gates.
//!
//! The CoreML graph starts at the mel, so a wrong parameter here is silently
//! wrong EMBEDDINGS with no shape error anywhere to catch it. That is the
//! highest-consequence claim in this module and it is the one thing that can be
//! checked with **no model present**, so it is checked hard, at three levels:
//!
//! 1. the two tables the front end is built from — the analysis window and the
//!    mel filterbank — against the checkpoint's OWN loaded buffers;
//! 2. structural properties that are true by construction and would stop being
//!    true under a specific mistake (where the 400 taps sit inside the 512-point
//!    frame; the first pre-emphasized sample; the axis the mean is taken over);
//! 3. the whole front end against committed per-clip goldens produced by the
//!    checkpoint's own `MelBanks`.
//!
//! Every fixture under `tests/identity/fixtures/mel/` comes from
//! `conversion/redimnet/scripts/write_mel_goldens.py`, whose `provenance.json`
//! records the checkpoint, the pinned model-source revision, the toolchain that
//! produced them, and the one residual a reader has to know about.
//!
//! # The residual, stated rather than tuned away
//!
//! The oracle computes the whole front end in **fp32** and uses the
//! checkpoint's *saved* fp32 hamming window, whose taps sit up to 2.3e-7 from
//! the exact analytic window (torch evaluates `0.54f − 0.46f·cos` in fp32, so
//! its `w[0]` is 0.08000001 rather than 0.08). This port computes the window
//! and the STFT in f64, which is more accurate than either. So exact agreement
//! is not available and would not be desirable; what these gates pin is the
//! MEASURED disagreement, with the mutation margins below it stated so the
//! headroom is visible rather than asserted.

use rustfft::num_complex::Complex;

use super::*;

/// Absolute path to a committed fixture under `tests/identity/fixtures/mel`.
/// Anchored at the manifest dir so the gates do not depend on which directory
/// `cargo test` was invoked from.
macro_rules! fixture {
  ($name:literal) => {
    concat!(
      env!("CARGO_MANIFEST_DIR"),
      "/tests/identity/fixtures/mel/",
      $name
    )
  };
}

/// Read a committed `.npy` of f32, asserting its declared header shape and that
/// every element is finite, into a flat row-major `Vec<f32>`.
///
/// The strictness is the point: a fixture whose declared shape drifted, or that
/// carries a NaN a downstream max-reduction would silently drop (see
/// [`nan_prop_max`]), must fail loudly here rather than sail through the
/// comparison it feeds.
fn read_npy_f32_shaped(path: &str, expected_shape: &[u64]) -> Vec<f32> {
  let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("read {path}: {e}"));
  let npy = npyz::NpyFile::new(&bytes[..]).unwrap_or_else(|e| panic!("parse npy {path}: {e}"));
  assert_eq!(
    npy.shape(),
    expected_shape,
    "{path}: declared NPY shape {:?} != expected {expected_shape:?}",
    npy.shape()
  );
  let data = npy
    .into_vec::<f32>()
    .unwrap_or_else(|e| panic!("decode npy {path}: {e}"));
  let expected_len = expected_shape.iter().product::<u64>() as usize;
  assert_eq!(
    data.len(),
    expected_len,
    "{path}: decoded {} elements, declared shape implies {expected_len}",
    data.len()
  );
  if let Some(i) = data.iter().position(|v| !v.is_finite()) {
    panic!("{path}: non-finite element at flat index {i}: {}", data[i]);
  }
  data
}

/// Read a committed golden clip, asserting its 16 kHz mono 16-bit header and
/// its exact length first — a fixture at the wrong rate or the wrong length
/// would still decode to numbers and would invalidate the golden it is paired
/// with. Scaled by `1/32768`, which is what the generator dequantized by.
fn read_golden_wav(path: &str) -> Vec<f32> {
  let mut reader = hound::WavReader::open(path).unwrap_or_else(|e| panic!("open {path}: {e}"));
  let spec = reader.spec();
  assert_eq!(spec.sample_rate, SAMPLE_RATE_HZ, "{path}: sample rate");
  assert_eq!(spec.channels, 1, "{path}: channel count");
  assert_eq!(spec.bits_per_sample, 16, "{path}: bit depth");
  assert_eq!(
    spec.sample_format,
    hound::SampleFormat::Int,
    "{path}: sample format"
  );
  let samples: Vec<f32> = reader
    .samples::<i16>()
    .map(|s| f32::from(s.expect("decode sample")) / 32_768.0)
    .collect();
  assert_eq!(samples.len(), WINDOW_SAMPLES, "{path}: sample count");
  samples
}

/// NaN-propagating max: any NaN operand poisons the result to NaN. `f32::max`
/// deliberately DROPS a NaN operand, so a corrupted fixture could otherwise
/// leave a `max_abs_diff` of 0 and pass a `<= budget` gate; with this reducer
/// the assertion goes false instead. Panics on an empty iterator.
fn nan_prop_max(xs: impl IntoIterator<Item = f32>) -> f32 {
  xs.into_iter()
    .reduce(|a, b| {
      if a.is_nan() || b.is_nan() {
        f32::NAN
      } else {
        a.max(b)
      }
    })
    .expect("nan_prop_max over an empty iterator")
}

/// The committed golden clips: `<id>.wav` and `<id>_mel.npy`.
const GOLDEN_CLIPS: [(&str, &str); 3] = [
  (fixture!("tone_220.wav"), fixture!("tone_220_mel.npy")),
  (fixture!("clipped.wav"), fixture!("clipped_mel.npy")),
  (fixture!("formant.wav"), fixture!("formant_mel.npy")),
];

// ── Geometry ───────────────────────────────────────────────────────────────

/// The frame grid must land exactly on the reflection-padded window: the last
/// frame's final sample is the padded signal's final sample, with nothing left
/// over and nothing read past the end. A wrong hop, a wrong `N_FFT`, or a
/// `center` pad of the wrong width breaks this equality before any numerics
/// run.
#[test]
fn frame_grid_covers_the_padded_window_exactly() {
  assert_eq!(N_FRAMES, 401);
  assert_eq!(N_FRAMES, 1 + WINDOW_SAMPLES / HOP);
  assert_eq!(CENTER_PAD, N_FFT / 2);
  assert_eq!(
    (N_FRAMES - 1) * HOP + N_FFT,
    WINDOW_SAMPLES + 2 * CENTER_PAD
  );
  assert_eq!(N_FREQ, N_FFT / 2 + 1);
}

// ── The analysis window ────────────────────────────────────────────────────

/// The 400 taps are `hamming_window(400, periodic=True)`, matched against the
/// checkpoint's own saved buffer.
///
/// This is the gate for two mutations at once, and both are one word wide:
///
/// - **hann instead of hamming** — same cosine shape, different coefficients.
///   `hann[0]` is 0, `hamming[0]` is 0.08, so the endpoints alone separate them
///   by 0.08.
/// - **symmetric instead of periodic** — the symmetric form divides by
///   `n − 1`, which moves every interior tap; the two differ by up to ~1.8e-3
///   near `k = 100`.
///
/// Both are ~3 orders above the 1e-6 budget, which is itself ~4× the 2.3e-7
/// fp32 rounding in the saved buffer this is compared against.
#[test]
fn window_taps_are_periodic_hamming() {
  const WINDOW_MAX_ABS_DIFF: f32 = 1e-6;

  let golden = read_npy_f32_shaped(fixture!("window.npy"), &[WIN_LENGTH as u64]);
  let taps = MelExtractor::periodic_hamming(WIN_LENGTH);
  assert_eq!(taps.len(), WIN_LENGTH);

  let max_diff = nan_prop_max(
    taps
      .iter()
      .zip(golden.iter())
      .map(|(a, b)| (*a as f32 - b).abs()),
  );
  eprintln!("[mel] window vs checkpoint buffer max_abs_diff = {max_diff:.3e}");
  assert!(
    max_diff <= WINDOW_MAX_ABS_DIFF,
    "analysis window diverged from the checkpoint's own: {max_diff:.3e} > {WINDOW_MAX_ABS_DIFF:.3e}"
  );

  // Stated in the clear as well as measured, because the two mutations this
  // catches are each one identifier wide.
  assert!(
    (taps[0] - 0.08).abs() < 1e-12,
    "hamming's first tap is 0.08; hann's is 0 — got {}",
    taps[0]
  );
  assert!(
    (taps[WIN_LENGTH / 2] - 1.0).abs() < 1e-12,
    "the periodic form peaks at EXACTLY 1.0 at k = n/2; the symmetric one \
     reaches only ~0.9999964 — got {}",
    taps[WIN_LENGTH / 2]
  );
}

/// The 400 taps sit **centred and zero-padded** inside the 512-point frame, at
/// offset `(512 − 400) / 2 = 56` — `torch.stft`'s own handling of
/// `win_length < n_fft`.
///
/// The mutation this catches is treating `win_length` and `n_fft` as one
/// number: a 512-tap window, or 400 taps written at offset 0, is a different
/// analysis and neither has a shape error to announce it.
#[test]
fn window_is_zero_padded_and_centred_in_the_fft_frame() {
  assert_eq!(WINDOW_OFFSET, 56);
  let window = MelExtractor::padded_window();
  assert_eq!(window.len(), N_FFT);
  assert!(
    window[..WINDOW_OFFSET].iter().all(|&v| v == 0.0),
    "the leading {WINDOW_OFFSET} samples must be exactly zero"
  );
  assert!(
    window[WINDOW_OFFSET + WIN_LENGTH..]
      .iter()
      .all(|&v| v == 0.0),
    "the trailing samples must be exactly zero"
  );
  assert!(
    (window[WINDOW_OFFSET] - 0.08).abs() < 1e-12,
    "the window's first tap belongs at index {WINDOW_OFFSET}"
  );
  assert!(
    (window[WINDOW_OFFSET + WIN_LENGTH / 2] - 1.0).abs() < 1e-12,
    "the window's peak belongs at index {}",
    WINDOW_OFFSET + WIN_LENGTH / 2
  );
}

// ── The mel filterbank ─────────────────────────────────────────────────────

/// The filterbank matches the checkpoint's own `mel_scale.fb` buffer.
///
/// One comparison, four mutations. Each of these is a plausible reading of
/// "72 mel filters" and each produces a filterbank that is wrong everywhere:
///
/// - **slaney instead of htk mel scale** — a different frequency warping, so
///   every filter moves;
/// - **`norm='slaney'` instead of `norm=None`** — the SAME scale with each
///   triangle scaled by `2/(right − left)`, which is a different knob with a
///   confusingly similar name and de-emphasizes the wide high-frequency filters;
/// - **`f_min = 0` instead of 20 Hz**, and **`f_max = 8000` (Nyquist) instead
///   of 7600** — both shift every filter edge.
///
/// Measured on the goldens, those move the mel by 13.1, 2.7, 3.6 and 1.4
/// natural-log units respectively.
///
/// The budget is MEASURED at 6.3e-6 and pinned just above it. That residual is
/// **torchaudio's**, not this port's: it builds the filterbank in fp32, and its
/// `f_pts` come from `700·(10^(m/2595) − 1)` evaluated there, so a ~1e-3 Hz
/// rounding of a filter edge divided by a 25 Hz-wide low-frequency triangle
/// lands exactly here. A numpy f64 rebuild of the same formula disagrees with
/// the checkpoint's buffer by the same 6.34e-6, which is what identifies the
/// residual as the buffer's rather than the port's.
#[test]
fn filterbank_matches_the_checkpoints_own_mel_scale() {
  const FILTERBANK_MAX_ABS_DIFF: f32 = 1e-5;

  let golden = read_npy_f32_shaped(fixture!("filterbank.npy"), &[N_MELS as u64, N_FREQ as u64]);
  let fb = MelExtractor::build_htk_filterbank(SAMPLE_RATE_HZ, N_FFT, N_MELS, F_MIN, F_MAX);
  assert_eq!(fb.len(), N_MELS * N_FREQ);

  let max_diff = nan_prop_max(
    fb.iter()
      .zip(golden.iter())
      .map(|(a, b)| (*a as f32 - b).abs()),
  );
  eprintln!("[mel] filterbank vs checkpoint buffer max_abs_diff = {max_diff:.3e}");
  assert!(
    max_diff <= FILTERBANK_MAX_ABS_DIFF,
    "mel filterbank diverged from the checkpoint's own: \
     {max_diff:.3e} > {FILTERBANK_MAX_ABS_DIFF:.3e}"
  );

  // `norm=None` in the clear: the triangles are unnormalized, so every one of
  // them peaks at 1.0 and none exceeds it. Slaney normalization scales each by
  // 2/(right − left), which for these filters is 1e-3..1e-2 — nowhere near 1.
  let peak = nan_prop_max(fb.iter().map(|v| *v as f32));
  assert!(
    (peak - 1.0).abs() < 1e-3,
    "unnormalized triangles peak at 1.0; got {peak}"
  );
}

// ── Pre-emphasis ───────────────────────────────────────────────────────────

/// Pre-emphasis is `y[n] = x[n] − 0.97·x[n−1]`, and its FIRST output uses the
/// **reflected** neighbour `x[1]`, not a repeat of `x[0]`.
///
/// `PreEmphasis` pads with `F.pad(x, (1, 0), 'reflect')` before correlating, so
/// `y[0] = x[0] − 0.97·x[1]`. Getting that one sample wrong — by replicating
/// the edge, or by starting the filter at `n = 1` — is invisible in a
/// spectrogram and no shape check would see it, so it is asserted directly.
/// The coefficient itself is asserted here too: it is the difference between
/// this and, say, 0.95, which moves the goldens by 1.3–2.3 log units.
#[test]
fn pre_emphasis_reflects_its_first_neighbour_and_filters_the_rest() {
  let x: [f32; 5] = [1.0, 2.0, 4.0, 8.0, 16.0];
  let y = MelExtractor::pre_emphasize(&x);
  assert_eq!(y.len(), x.len(), "pre-emphasis is length-preserving");

  // Reflected, so the first output looks FORWARD at x[1].
  assert!((y[0] - (1.0 - 0.97 * 2.0)).abs() < 1e-12, "got {}", y[0]);
  // A replicate pad would have produced x[0] - 0.97*x[0] = 0.03 here.
  assert!(
    (y[0] - 0.03).abs() > 0.9,
    "y[0] must not be the replicate-pad value"
  );
  for n in 1..x.len() {
    let want = f64::from(x[n]) - 0.97 * f64::from(x[n - 1]);
    assert!((y[n] - want).abs() < 1e-12, "n = {n}: got {}", y[n]);
  }
  assert!(
    (PRE_EMPHASIS - 0.97).abs() < 1e-12,
    "the coefficient is 0.97"
  );
}

// ── center=True reflection padding ─────────────────────────────────────────

/// `center=True` mirrors [`CENTER_PAD`] samples onto each end, EXCLUDING the
/// edge sample itself — `torch`'s `'reflect'`, not `'replicate'`.
#[test]
fn center_padding_reflects_without_repeating_the_edge() {
  let signal: Vec<f64> = (0..1000).map(|i| i as f64).collect();
  let padded = MelExtractor::center_pad(&signal);
  assert_eq!(padded.len(), signal.len() + 2 * CENTER_PAD);
  // Left pad counts DOWN from signal[CENTER_PAD] to signal[1]; signal[0] then
  // appears exactly once.
  assert_eq!(padded[0], signal[CENTER_PAD]);
  assert_eq!(padded[CENTER_PAD - 1], signal[1]);
  assert_eq!(padded[CENTER_PAD], signal[0]);
  // Right pad likewise skips the last sample and counts back from len - 2.
  let tail = CENTER_PAD + signal.len();
  assert_eq!(padded[tail - 1], signal[signal.len() - 1]);
  assert_eq!(padded[tail], signal[signal.len() - 2]);
  assert_eq!(
    padded[padded.len() - 1],
    signal[signal.len() - 1 - CENTER_PAD]
  );
}

// ── The STFT kernel ────────────────────────────────────────────────────────

/// `power_spectrum` is the exact `re² + im²` (3-4-5 triangle → 25). A
/// magnitude (`power = 1.0`) spectrogram instead of a power one moves the
/// goldens by 2.8–4.4 log units.
#[test]
fn power_spectrum_is_exact_magnitude_squared() {
  let mut input = vec![Complex::new(0.0f64, 0.0); N_FFT];
  input[0] = Complex::new(3.0, 4.0);
  let mut power = vec![0.0f64; N_FREQ];
  MelExtractor::power_spectrum(&input, &mut power);
  assert_eq!(power[0], 25.0);
}

/// The zero-padded 400-sample window inside a 512-point FFT still resolves a
/// tone at the bin its frequency implies: 1 kHz at 16 kHz with `n_fft = 512` is
/// `1000 / (16000/512) = 32`.
#[test]
fn stft_peaks_at_the_expected_bin() {
  let mel = MelExtractor::new();
  let sr = f64::from(SAMPLE_RATE_HZ);
  let frame: Vec<f64> = (0..N_FFT)
    .map(|k| (std::f64::consts::TAU * 1000.0 * (k as f64) / sr).sin())
    .collect();
  let mut power = vec![0.0f64; N_FREQ];
  let mut fft_input = vec![Complex::new(0.0f64, 0.0); N_FFT];
  let mut fft_scratch = vec![Complex::new(0.0f64, 0.0); mel.fft.get_inplace_scratch_len()];
  mel.stft_one_frame_power(&frame, &mut fft_input, &mut fft_scratch, &mut power);
  let (peak_bin, _) = power
    .iter()
    .enumerate()
    .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
    .unwrap();
  assert_eq!(peak_bin, 32, "1 kHz belongs in bin 32");
}

// ── The log guard and the mean normalization ───────────────────────────────

/// A silent window's mel is zero, everywhere.
///
/// Two things at once, and both are load-bearing. The guard is ADDITIVE and the
/// log is natural: `ln(0 + 1e-6)` is a finite −13.8155, not `−∞`, so a silent
/// clip produces numbers rather than poison. And the mean normalization then
/// removes that constant, which is what makes silence read as "no information"
/// rather than as a large negative bias the network has never seen. Drop the
/// mean subtraction and every element reads −13.8155 instead; use a
/// `max(power, ε)` floor with a smaller ε and the same clip reads `ln(0)`.
///
/// **Not bit-zero, and the bound says which kind of not-zero is acceptable.**
/// Every one of the 401 frames holds the identical f64 −13.815510557964274, but
/// summing 401 copies of it and dividing does not return it exactly, so `v −
/// mean` lands at ~1e-15 rather than at 0. (The fp32 oracle's own sum happens
/// to cancel to exact zero; that is luck at a coarser precision, not a property
/// to hold this port to.) The pin is 1e-12 — three orders above the measured
/// rounding and thirteen below anything a real defect produces here, since the
/// two mutations this test exists for read 13.8155 and −∞.
#[test]
fn a_silent_window_produces_a_zero_mel() {
  const SILENCE_MAX_ABS: f32 = 1e-12;

  let mel = MelExtractor::new();
  let mut out = vec![f32::NAN; N_MELS * N_FRAMES];
  mel
    .extract_into(&vec![0.0f32; WINDOW_SAMPLES], &mut out)
    .expect("extract silence");
  let worst = nan_prop_max(out.iter().map(|v| v.abs()));
  eprintln!("[mel] silence max|mel| = {worst:.3e}");
  assert!(
    worst <= SILENCE_MAX_ABS,
    "a mean-normalized log-mel of silence is zero to summation rounding; \
     worst was {worst:.3e}"
  );
}

/// The mean is taken **per mel bin, over time** — so after extraction every
/// bin's own mean across all [`N_FRAMES`] frames is zero.
///
/// The mutation this catches reads `dim=-1` as the mel axis instead of the time
/// axis: a per-frame mean over the 72 bins. That is a different function with
/// the same shape and no error anywhere, and on the goldens it moves the mel by
/// 6–13 log units. Under it, the per-bin time means below are emphatically not
/// zero.
#[test]
fn mean_normalization_is_per_mel_bin_over_time() {
  let mel = MelExtractor::new();
  let sr = f64::from(SAMPLE_RATE_HZ);
  // A tone with a slow envelope: non-stationary, so the per-bin means are
  // genuinely subtracted rather than trivially absent.
  let samples: Vec<f32> = (0..WINDOW_SAMPLES)
    .map(|i| {
      let t = i as f64 / sr;
      let env = 0.5 + 0.4 * (std::f64::consts::TAU * 0.7 * t).sin();
      (env * (std::f64::consts::TAU * 700.0 * t).sin()) as f32
    })
    .collect();
  let mut out = vec![0.0f32; N_MELS * N_FRAMES];
  mel.extract_into(&samples, &mut out).expect("extract tone");

  let mut worst_bin_mean = 0.0f64;
  for bin in 0..N_MELS {
    let row = &out[bin * N_FRAMES..(bin + 1) * N_FRAMES];
    let mean = row.iter().map(|v| f64::from(*v)).sum::<f64>() / (N_FRAMES as f64);
    worst_bin_mean = worst_bin_mean.max(mean.abs());
  }
  assert!(
    worst_bin_mean < 1e-4,
    "every mel bin's mean over time must be ~0; worst was {worst_bin_mean:.3e}"
  );

  // And the signal is not trivially flat, so the assertion above had something
  // to remove: the extracted values span a real range.
  let span = nan_prop_max(out.iter().copied()) - (-nan_prop_max(out.iter().map(|v| -v)));
  assert!(
    span > 1.0,
    "the test signal must exercise the mel; span {span}"
  );
}

// ── The whole front end, against the recipe's own oracle ───────────────────

/// **The front-end parity gate.** The committed `<clip>_mel.npy` files are the
/// checkpoint's own `MelBanks` output — `model.spec`, the very module
/// `conversion/redimnet/.../assert_front_end` validated against `MEL_FRONT_END`
/// — computed for the dequantized contents of the committed `<clip>.wav`. So
/// this compares the Rust port against the function the graph was converted
/// behind, with no CoreML model and no Python present.
///
/// # The budget is measured, and on two clips of three the residual is the ORACLE's
///
/// The two cannot agree exactly: the oracle runs the whole front end in fp32
/// with the checkpoint's saved fp32 tables, and this port runs it in f64 from
/// analytic ones. The pin below is the measured worst over the three clips,
/// with margin — and the decomposition says which side owns it, which is what
/// makes it a residual rather than an unexplained gap. Re-running the same f64
/// algorithm in numpy, once with the checkpoint's own tables and once with
/// analytic ones, gives (max|Δ| against the golden, natural-log units):
///
/// | clip | f64 with the checkpoint's tables | f64 with analytic tables |
/// |---|---|---|
/// | `tone_220` | 8.48e-5 | 8.15e-5 |
/// | `clipped` | 2.03e-5 | 8.54e-5 |
/// | `formant` | 6.10e-6 | 7.58e-6 |
///
/// The left column is **pure fp32-versus-f64 arithmetic** — identical tables,
/// so nothing but precision separates the two — and on `tone_220` it is larger
/// than the right one. The tables' own contributions are small and separately
/// pinned above (window 2.3e-7, filterbank 6.3e-6).
///
/// **The claim holds on `tone_220` and `formant`, and is over-stated on
/// `clipped`.** An INDEPENDENT f64 reference — the same recipe rebuilt from
/// torchaudio's own primitives at `dtype=torch.float64`, rather than a re-run
/// of this port's algorithm — disagrees with the golden by 8.16e-5 on
/// `tone_220`, essentially the whole of this port's 8.15e-5: nothing there is
/// the port's. On `clipped` the same reference disagrees by only 3.66e-5
/// against this port's 8.54e-5, so **roughly half of that clip's gap is not
/// explained by the oracle's rounding** and is the port's own. So the sentence
/// is narrowed to the clips it was measured on rather than dropped or left
/// standing over all three. (Measured in the audit recorded as coremlit #138;
/// the reference is not committed, and an end-to-end f64 oracle with a tight
/// pin is the follow-up it names.)
///
/// The gate is deliberately NOT moved for this. 1.5e-4 is ~1.8× the measured
/// worst and every front-end mutation below clears it by orders of magnitude,
/// so the pin's job — separating a defect from precision — is unaffected by
/// which side owns 5e-5 on one clip.
///
/// **Every front-end mutation clears it by orders of magnitude.** Measured on
/// these same clips, in natural-log units, worst case across them: window
/// symmetric-instead-of-periodic 0.60, hann-instead-of-hamming 10.9, slaney mel
/// scale 13.1, `norm='slaney'` 3.8, pre-emphasis 0.95 instead of 0.97 2.5,
/// pre-emphasis absent 9.2, log epsilon 1e-10 instead of 1e-6 1.6, the mean
/// taken over mels instead of time 13.1, the mean absent 10.9, `win_length` 512
/// instead of 400 7.7, `n_fft` 400 instead of 512 7.9, `power` 1.0 instead of
/// 2.0 9.0, `f_min` 0 instead of 20 11.8, `f_max` 8000 instead of 7600 9.8. The
/// smallest of those, on the single least sensitive clip, is 3.5e-2 — four
/// orders above this pin.
#[test]
fn mel_matches_the_committed_goldens() {
  // MEASURED worst max-abs-diff of this port against the checkpoint's own
  // MelBanks over the three committed clips: 8.5e-5, pinned at ~1.8x that. See
  // the doc above for what the residual IS and whose it is; it is not a
  // tolerance for a defect to hide in — the smallest mutation in the table
  // above clears it by a factor of 400 on the least sensitive clip.
  const PARITY_MAX_ABS_DIFF: f32 = 1.5e-4;

  let mel = MelExtractor::new();
  let mut worst = 0.0f32;
  for (wav_path, mel_path) in GOLDEN_CLIPS {
    let samples = read_golden_wav(wav_path);
    let golden = read_npy_f32_shaped(mel_path, &[N_MELS as u64, N_FRAMES as u64]);

    let mut out = vec![0.0f32; N_MELS * N_FRAMES];
    mel.extract_into(&samples, &mut out).expect("extract_into");

    let max_diff = nan_prop_max(out.iter().zip(golden.iter()).map(|(a, b)| (a - b).abs()));
    eprintln!("[mel] {mel_path}: max_abs_diff = {max_diff:.6e}");
    assert!(
      max_diff <= PARITY_MAX_ABS_DIFF,
      "front-end parity regressed on {mel_path}: \
       max_abs_diff = {max_diff:.3e} > {PARITY_MAX_ABS_DIFF:.3e}"
    );
    worst = worst.max(max_diff);
  }
  eprintln!("[mel] worst over the committed corpus = {worst:.6e}");
}

// ── Input validation ───────────────────────────────────────────────────────

/// The front end takes exactly one window and refuses everything else — no
/// padding, no truncation. `WindowLength`'s docs carry why: the per-bin mean
/// makes this front end non-local, so a padded clip is a different function of
/// the speech rather than a truncated one.
#[test]
fn extract_into_refuses_anything_but_one_exact_window() {
  let mel = MelExtractor::new();
  let mut out = vec![0.0f32; N_MELS * N_FRAMES];
  for len in [0usize, 1, WINDOW_SAMPLES - 1, WINDOW_SAMPLES + 1] {
    let err = mel
      .extract_into(&vec![0.0f32; len], &mut out)
      .expect_err("must refuse a clip that is not one window");
    assert!(
      matches!(err, Error::WindowLength(w) if w.got() == len && w.expected() == WINDOW_SAMPLES),
      "len {len}: got {err:?}"
    );
  }
  assert!(
    mel
      .extract_into(&vec![0.0f32; WINDOW_SAMPLES], &mut out)
      .is_ok()
  );
}