///|
/// A mono dry signal placed at an integer sample offset on a shared scene timeline.
/// Every scene has the same room, receivers, rate and rendering settings.
/// Source positions may differ. Gain is a signed linear multiplier.
pub(all) struct RecordingTrack {
  scene : Scene
  dry : Array[Double]
  sample_rate : Int32
  start_frame : Int32
  gain : Double
}

///|
/// Shared six-band materials and air attenuation for a multitrack render.
pub(all) struct RecordingOctaves {
  band_absorption : Array[Array[Double]]
  air_db_per_m : Array[Double]
  filter_half_width : Int32
}

///|
/// `end_frame` is the exclusive end of the complete shifted convolution.
/// Timing includes the model's common FIR latency but no resampling or padding
/// beyond the full convolution lengths and requested track start offsets.
pub struct RecordingTrackReport {
  start_frame : Int32
  gain : Double
  dry_frames : Int32
  rir_frames : Int32
  wet_frames : Int32
  end_frame : Int32
  latency_samples : Int32
  contributing_paths : Array[Int32]
  omitted_late_paths : Array[Int32]
  zero_gain_paths : Array[Int32]
}

///|
pub struct RecordingMix {
  audio : Audio
  tracks : Array[RecordingTrackReport]
}

///|
fn same_xyz(a : Vec3, b : Vec3) -> Bool {
  a.x == b.x && a.y == b.y && a.z == b.z
}

///|
fn same_recording_geometry(a : Scene, b : Scene) -> Bool {
  if !same_xyz(a.room, b.room) || a.receivers.length() != b.receivers.length() {
    return false
  }
  for i in 0.. true
    (Some(left), Some(right)) => {
      if left.length() != right.length() {
        return false
      }
      for i in 0.. false
  }
}

///|
fn same_recording_scene(a : Scene, b : Scene) -> Bool {
  a.sample_rate == b.sample_rate &&
  a.speed == b.speed &&
  a.half_width == b.half_width &&
  a.frames == b.frames &&
  a.max_order == b.max_order &&
  a.absorption == b.absorption &&
  same_recording_geometry(a, b)
}

///|
fn mix_filter_width(
  s : Scene,
  octaves : RecordingOctaves?,
) -> Result[Int32, String] {
  match octaves {
    None => Ok(0)
    Some(p) => {
      if p.band_absorption.length() != s.absorption.length() ||
        !p.band_absorption.all(fn(wall) {
          wall.length() == 6 && wall.all(fn(a) { a >= 0.0 && a <= 1.0 })
        }) {
        return Err(
          "recording octave materials need one six-band row per wall, values 0..1",
        )
      }
      if p.air_db_per_m.length() != 6 ||
        !p.air_db_per_m.all(fn(loss) { loss >= 0.0 && loss <= 10.0 }) {
        return Err("recording octave air loss needs six values in 0..10 dB/m")
      }
      spectral_width(s.sample_rate, p.filter_half_width)
    }
  }
}

///|
priv struct MixSizing {
  frames : Int32
  rir_frames : Int32
  latency : Int32
  filter_half_width : Int32
}

///|
/// Check all tracks and aggregate work before tracing or allocating output.
fn preflight_mix(
  tracks : Array[RecordingTrack],
  octaves : RecordingOctaves?,
) -> Result[MixSizing, String] {
  if tracks.is_empty() || tracks.length() > 4 {
    return Err("recording requires 1..4 tracks")
  }
  let shared = tracks[0].scene
  let count = shared.receivers.length()
  let half = match mix_filter_width(shared, octaves) {
    Err(e) => return Err(e)
    Ok(v) => v
  }
  let rir_frames = shared.output_frames() + 2 * half
  let band_count = if half > 0 { 6 } else { 1 }
  let band_samples = rir_frames * count * band_count
  if half > 0 && band_samples > 1000000 {
    return Err("recording octave intermediate sample budget per track: 1000000")
  }
  if band_samples.to_int64() * tracks.length().to_int64() > 3000000L {
    return Err("recording intermediate RIR sample budget: 3000000")
  }
  let path_count = shared.candidate_image_count().to_int64() *
    count.to_int64() *
    tracks.length().to_int64()
  let tap_budget = path_count *
    (2 * shared.half_width + 1).to_int64() *
    band_count.to_int64()
  if path_count > 200000L || tap_budget > 64000000L {
    return Err("recording geometry or interpolation work budget exceeded")
  }
  let mut total_dry = 0
  let mut total_wet = 0L
  let mut frames = 0L
  for i in 0.. 262144 {
      return Err("recording track \{i + 1} needs 1..262144 dry frames")
    }
    total_dry = total_dry + t.dry.length()
    if total_dry > 262144 {
      return Err("recording total dry frame budget: 262144")
    }
    if !t.dry.all(fn(v) { v >= -1.0e6 && v <= 1.0e6 }) {
      return Err(
        "recording track \{i + 1} dry samples must be finite and abs <= 1000000",
      )
    }
    if t.start_frame < 0 || !(t.gain >= -100.0 && t.gain <= 100.0) {
      return Err(
        "recording track \{i + 1} requires a nonnegative offset and gain in -100..100",
      )
    }
    let wet_frames = (t.dry.length() + rir_frames - 1).to_int64()
    let end_frame = t.start_frame.to_int64() + wet_frames
    total_wet = total_wet + wet_frames * count.to_int64()
    frames = Int64::max(frames, end_frame)
    if end_frame > 262144L || frames * count.to_int64() > 2000000L {
      return Err(
        "recording output budget exceeded: 262144 frames or 2000000 samples",
      )
    }
    if total_wet > 4000000L {
      return Err("recording total convolution sample budget: 4000000")
    }
  }
  Ok({
    frames: frames.to_int(),
    rir_frames,
    latency: shared.half_width + half,
    filter_half_width: half,
  })
}

///|
priv struct TrackRender {
  wet : Audio
  contributing : Array[Int32]
  late : Array[Int32]
  zero : Array[Int32]
}

///|
fn render_recording_track(
  track : RecordingTrack,
  octaves : RecordingOctaves?,
  half_width : Int32,
) -> Result[TrackRender, String] {
  match octaves {
    None => {
      let r = render(track.scene)
      match convolve(r, track.dry) {
        Err(e) => Err(e)
        Ok(wet) =>
          Ok({ wet, contributing: r.contributing, late: r.late, zero: r.zero, })
      }
    }
    Some(p) => {
      let r = match
        spectral_rir(
          track.scene,
          p.band_absorption,
          air_db_per_m=p.air_db_per_m,
          filter_half_width=half_width,
        ) {
        Err(e) => return Err(e)
        Ok(v) => v
      }
      match r.audio.convolve(track.dry) {
        Err(e) => Err(e)
        Ok(wet) =>
          Ok({ wet, contributing: r.contributing, late: r.late, zero: r.zero, })
      }
    }
  }
}

///|
/// Render static sources in the same room and sum their fully convolved tracks.
/// All channels preserve the original receiver ordering, signed amplitudes and
/// the common kernel delay. This is an offline render with no clipping,
/// normalization, hidden sample-rate conversion or per-source alignment.
pub fn mix_recordings(
  tracks : Array[RecordingTrack],
  octaves~ : RecordingOctaves? = None,
) -> Result[RecordingMix, String] {
  let sizes = match preflight_mix(tracks, octaves) {
    Err(e) => return Err(e)
    Ok(v) => v
  }
  let shared = tracks[0].scene
  let samples = Array::makei(shared.receivers.length(), fn(_) {
    Array::make(sizes.frames, 0.0)
  })
  let reports : Array[RecordingTrackReport] = []
  for i in 0.. return Err("recording track \{i + 1}: " + e)
      Ok(v) => v
    }
    let frames = rendered.wet.frames()
    for ch in 0..