///|
pub(all) struct DecayPoint {
  frame_from_onset : Int32
  energy_db : Double
}

///|
/// A null time in the JSON API is accompanied by the reason for withholding it.
pub(all) struct DecayFit {
  status : String
  seconds_for_60db : Double?
  slope_db_per_second : Double?
  r_squared : Double?
  samples_used : Int32
  start_frame : Int32?
  end_frame : Int32?
}

///|
pub(all) struct ChannelDecay {
  onset_frame : Int32?
  window_end_exclusive : Int32
  peak : Double
  power_sum : Double
  d50 : Double?
  c50_db : Double?
  c80_db : Double?
  center_time_ms : Double?
  edt : DecayFit
  t20 : DecayFit
  t30 : DecayFit
  curve : Array[DecayPoint]
}

///|
pub(all) struct DecayAnalysis {
  sample_rate : Int32
  frames : Int32
  onset_mode : String
  channels : Array[ChannelDecay]
}

///|
// Use one pass for validation; bound frame arithmetic before allocation.
fn checked_audio_frames(
  channels : Array[Array[Double]],
  sample_rate : Int32,
  max_frames : Int32,
  max_samples : Int32,
  max_amplitude : Double,
) -> Result[Int32, String] {
  if !valid_audio_rate(sample_rate) ||
    channels.is_empty() ||
    channels.length() > 8 {
    return Err("audio requires 1..8 channels and a sample rate of 8000..96000")
  }
  let frames = channels[0].length()
  if frames == 0 ||
    frames > max_frames ||
    frames.to_int64() * channels.length().to_int64() > max_samples.to_int64() {
    return Err("audio frame or aggregate sample budget exceeded")
  }
  for channel in channels {
    if channel.length() != frames {
      return Err("audio channel lengths differ")
    }
    if !channel.all(value => value >= -max_amplitude && value <= max_amplitude) {
      return Err("audio contains nonfinite or out-of-range samples")
    }
  }
  Ok(frames)
}

///|
fn decline_decay_fit(status : String) -> DecayFit {
  {
    status,
    seconds_for_60db: None,
    slope_db_per_second: None,
    r_squared: None,
    samples_used: 0,
    start_frame: None,
    end_frame: None,
  }
}

///|
/// Integrate squared samples in reverse after scaling to keep the range
/// finite even for very quiet inputs. Curve ref is the energy at onset.
fn reverse_energy(
  samples : Array[Double],
  onset : Int32,
  end : Int32,
  scale : Double,
) -> Array[Double] {
  let integrated = Array::make(end - onset, 0.0)
  let mut sum = 0.0
  let mut correction = 0.0
  for i = end - 1; i >= onset; i = i - 1 {
    let normalized = samples[i] / scale
    let term = normalized * normalized - correction
    let total = sum + term
    correction = total - sum - term
    sum = total
    // The exact series is monotonic. Suppress at most a round-off reversal.
    integrated[i - onset] = if i + 1 < end {
      sum.max(integrated[i + 1 - onset])
    } else {
      sum
    }
  }
  integrated
}

///|
fn decay_energy_db(value : Double, total : Double) -> Double {
  10.0 /
  // Subtraction of logs avoids an underflowing ratio for extremely small tails.
  @math.ln(10.0) *
  (@math.ln(value) - @math.ln(total))
}

///|
fn decay_fit(
  integrated : Array[Double],
  rate : Int32,
  start_db : Double,
  stop_db : Double,
) -> DecayFit {
  let total = integrated[0]
  let mut count = 0
  let mut first = -1
  let mut last = -1
  let mut covers_stop = false
  let mut mean_x = 0.0
  let mut mean_y = 0.0
  let mut variance_x = 0.0
  let mut variance_y = 0.0
  let mut covariance = 0.0
  for i, energy in integrated {
    if energy <= 0.0 {
      break
    }
    let db = decay_energy_db(energy, total)
    if db > start_db {
      continue
    }
    if db <= stop_db {
      covers_stop = true
    }
    if db < stop_db {
      break
    }
    if first < 0 {
      first = i
    }
    last = i
    let x = i.to_double() / rate.to_double()
    count += 1
    let dx = x - mean_x
    let dy = db - mean_y
    mean_x += dx / count.to_double()
    mean_y += dy / count.to_double()
    variance_x += dx * (x - mean_x)
    variance_y += dy * (db - mean_y)
    covariance += dx * (db - mean_y)
  }
  if !covers_stop {
    return decline_decay_fit("insufficient_decay_range")
  }
  let window_frames = last - first
  if count < 8 ||
    window_frames.to_double() < 0.005 * rate.to_double() ||
    variance_x <= 0.0 ||
    variance_y <= 0.0 {
    return {
      ..decline_decay_fit("insufficient_fit_samples"),
      samples_used: count,
    }
  }
  let slope = covariance / variance_x
  let fit = (covariance / variance_x * (covariance / variance_y))
    .max(0.0)
    .min(1.0)
  let status = if slope >= 0.0 || fit < 0.9 { "weak_fit" } else { "estimated" }
  {
    status,
    seconds_for_60db: if status == "estimated" {
      Some(-60.0 / slope)
    } else {
      None
    },
    slope_db_per_second: Some(slope),
    r_squared: Some(fit),
    samples_used: count,
    start_frame: Some(first),
    end_frame: Some(last),
  }
}

///|
fn decay_preview(
  integrated : Array[Double],
  max_points : Int32,
) -> Array[DecayPoint] {
  let curve : Array[DecayPoint] = []
  if max_points == 0 {
    return curve
  }
  let mut last_positive = integrated.length() - 1
  while integrated[last_positive] == 0.0 {
    last_positive -= 1
  }
  let count = max_points.min(last_positive + 1)
  for i in 0.. Int32 {
  (rate * ms + 999) / 1000
}

///|
fn clarity(early : Double, late : Double) -> Double? {
  if early <= 0.0 || late <= 0.0 {
    None
  } else {
    Some(decay_energy_db(early, late))
  }
}

///|
fn channel_decay(
  samples : Array[Double],
  rate : Int32,
  specified_onset : Int32?,
  window_end : Int32,
  max_points : Int32,
) -> ChannelDecay {
  let mut peak = 0.0
  for i in specified_onset.unwrap_or(0).. frame
    None => {
      let mut first = 0
      while samples[first].abs() / peak < 0.01 {
        first += 1
      }
      first
    }
  }
  let integrated = reverse_energy(samples, onset, window_end, peak)
  let total = integrated[0]
  let threshold_50 = late_start(rate, 50)
  let threshold_80 = late_start(rate, 80)
  let mut early_50 = 0.0
  let mut early_80 = 0.0
  let mut time_weighted = 0.0
  for i in onset.. threshold_50
  let covers_80 = integrated.length() > threshold_80
  {
    onset_frame: Some(onset),
    window_end_exclusive: window_end,
    peak,
    power_sum: total * peak * peak,
    d50: if covers_50 {
      Some((early_50 / total).min(1.0))
    } else {
      None
    },
    c50_db: if covers_50 {
      clarity(early_50, integrated[threshold_50])
    } else {
      None
    },
    c80_db: if covers_80 {
      clarity(early_80, integrated[threshold_80])
    } else {
      None
    },
    center_time_ms: Some(time_weighted * 1000.0 / (total * rate.to_double())),
    edt: decay_fit(integrated, rate, 0.0, -10.0),
    t20: decay_fit(integrated, rate, -5.0, -25.0),
    t30: decay_fit(integrated, rate, -5.0, -35.0),
    curve: decay_preview(integrated, max_points),
  }
}

///|
/// Finite-window, wideband Schroeder analysis. By default the onset is the
/// first sample within -40 dB of each channel's peak. An explicit per-channel
/// onset is appropriate for known simulation arrivals or aligned measurements.
pub fn analyze_decay(
  channels : Array[Array[Double]],
  sample_rate : Int32,
  onset_frames~ : Array[Int32] = [],
  end_exclusive~ : Int32? = None,
  curve_points~ : Int32 = 161,
) -> Result[DecayAnalysis, String] {
  let frames = match
    checked_audio_frames(channels, sample_rate, 262144, 2000000, 1.0e20) {
    Err(reason) => return Err(reason)
    Ok(count) => count
  }
  let end = end_exclusive.unwrap_or(frames)
  if end <= 0 || end > frames || curve_points < 0 || curve_points > 256 {
    return Err("invalid analysis end frame or curve point budget")
  }
  let automatic = onset_frames.is_empty()
  if !automatic &&
    (
      onset_frames.length() != channels.length() ||
      !onset_frames.all(frame => frame >= 0 && frame < end)
    ) {
    return Err("explicit onsets must contain one in-window frame per channel")
  }
  Ok({
    sample_rate,
    frames,
    onset_mode: if automatic {
      "threshold_minus_40db"
    } else {
      "explicit"
    },
    channels: Array::makei(channels.length(), fn(channel) {
      let onset = if automatic { None } else { Some(onset_frames[channel]) }
      channel_decay(channels[channel], sample_rate, onset, end, curve_points)
    }),
  })
}