///|
pub(all) enum DeltaError {
  UnitChanged
  SourceChanged
  SequenceDidNotIncrease
  TimestampWentBackward
  BucketDecreased(Int32)
}

///|
/// Compute the increment between two cumulative snapshots of the same series.
/// The first decreasing bucket is returned so callers can detect resets.
pub fn Histogram::delta(
  self : Histogram,
  baseline : Histogram,
) -> Result[Histogram, DeltaError] {
  let difference = Histogram::new()
  for i in 0.. Result[Shard, DeltaError] {
  if self.source != baseline.source {
    return Err(SourceChanged)
  }
  if self.unit.tag() != baseline.unit.tag() {
    return Err(UnitChanged)
  }
  if self.sequence <= baseline.sequence {
    return Err(SequenceDidNotIncrease)
  }
  if self.timestamp < baseline.timestamp {
    return Err(TimestampWentBackward)
  }
  // Shards can only contain validated canonical histogram payloads.
  let current = Histogram::from_snapshot(self.payload).unwrap()
  let previous = Histogram::from_snapshot(baseline.payload).unwrap()
  current
  .delta(previous)
  .map(delta => { ..self, payload: delta.snapshot(), decoded: None, })
}