siderust-js 0.1.0

package/tempoch-js/tempoch/tempoch-core/src/period.rs

@@ -0,0 +1,1168 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Vallés Puig, Ramon
+
+//! Time period / interval implementation.
+//!
+//! This module provides:
+//! - [`Interval<T>`]: generic interval over any [`TimeInstant`]
+//! - [`Period<S>`]: scale-based alias for `Interval<Time<S>>`
+
+use super::{Time, TimeInstant, TimeScale};
+use chrono::{DateTime, Utc};
+use qtty::Days;
+use std::fmt;
+
+#[cfg(feature = "serde")]
+use serde::{ser::SerializeStruct, Deserialize, Deserializer, Serialize, Serializer};
+
+/// Error returned when a period time-scale conversion fails.
+///
+/// Currently the only failure mode is an out-of-range chrono conversion
+/// (e.g. a Julian Date too far in the past/future for `DateTime<Utc>`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConversionError {
+    /// The time instant is outside the representable range of the target type.
+    OutOfRange,
+}
+
+impl fmt::Display for ConversionError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ConversionError::OutOfRange => {
+                write!(f, "time instant out of representable range for target type")
+            }
+        }
+    }
+}
+
+impl std::error::Error for ConversionError {}
+
+/// Error returned when constructing an [`Interval`] with invalid bounds.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InvalidIntervalError {
+    /// The start instant is after the end instant (`!(start <= end)`).
+    ///
+    /// This also triggers for `NaN` endpoints, since `NaN` comparisons
+    /// always return `false`.
+    StartAfterEnd,
+}
+
+impl fmt::Display for InvalidIntervalError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InvalidIntervalError::StartAfterEnd => {
+                write!(f, "interval start must not be after end")
+            }
+        }
+    }
+}
+
+impl std::error::Error for InvalidIntervalError {}
+
+/// Error indicating a period list violates sorted/non-overlapping invariants.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PeriodListError {
+    /// An interval at the given index has `start > end`.
+    InvalidInterval {
+        /// Index of the malformed interval.
+        index: usize,
+    },
+    /// The interval at the given index has a start time earlier than its predecessor.
+    Unsorted {
+        /// Index of the out-of-order interval.
+        index: usize,
+    },
+    /// The interval at the given index overlaps with its predecessor.
+    Overlapping {
+        /// Index of the overlapping interval.
+        index: usize,
+    },
+}
+
+impl fmt::Display for PeriodListError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            PeriodListError::InvalidInterval { index } => {
+                write!(f, "interval at index {index} has start > end")
+            }
+            PeriodListError::Unsorted { index } => {
+                write!(f, "interval at index {index} is not sorted by start time")
+            }
+            PeriodListError::Overlapping { index } => {
+                write!(f, "interval at index {index} overlaps with its predecessor")
+            }
+        }
+    }
+}
+
+impl std::error::Error for PeriodListError {}
+
+/// Target type adapter for [`Interval<Time<S>>::to`].
+///
+/// This allows converting a period of `Time<S>` either to another time scale
+/// marker (`MJD`, `JD`, `UT`, ...) or directly to `chrono::DateTime<Utc>`.
+pub trait PeriodTimeTarget<S: TimeScale> {
+    type Instant: TimeInstant;
+
+    fn convert(value: Time<S>) -> Result<Self::Instant, ConversionError>;
+}
+
+impl<S: TimeScale, T: TimeScale> PeriodTimeTarget<S> for T {
+    type Instant = Time<T>;
+
+    #[inline]
+    fn convert(value: Time<S>) -> Result<Self::Instant, ConversionError> {
+        Ok(value.to::<T>())
+    }
+}
+
+impl<S: TimeScale, T: TimeScale> PeriodTimeTarget<S> for Time<T> {
+    type Instant = Time<T>;
+
+    #[inline]
+    fn convert(value: Time<S>) -> Result<Self::Instant, ConversionError> {
+        Ok(value.to::<T>())
+    }
+}
+
+impl<S: TimeScale> PeriodTimeTarget<S> for DateTime<Utc> {
+    type Instant = DateTime<Utc>;
+
+    #[inline]
+    fn convert(value: Time<S>) -> Result<Self::Instant, ConversionError> {
+        value.to_utc().ok_or(ConversionError::OutOfRange)
+    }
+}
+
+/// Target type adapter for [`Interval<DateTime<Utc>>::to`].
+pub trait PeriodUtcTarget {
+    type Instant: TimeInstant;
+
+    fn convert(value: DateTime<Utc>) -> Self::Instant;
+}
+
+impl<S: TimeScale> PeriodUtcTarget for S {
+    type Instant = Time<S>;
+
+    #[inline]
+    fn convert(value: DateTime<Utc>) -> Self::Instant {
+        Time::<S>::from_utc(value)
+    }
+}
+
+impl<S: TimeScale> PeriodUtcTarget for Time<S> {
+    type Instant = Time<S>;
+
+    #[inline]
+    fn convert(value: DateTime<Utc>) -> Self::Instant {
+        Time::<S>::from_utc(value)
+    }
+}
+
+impl PeriodUtcTarget for DateTime<Utc> {
+    type Instant = DateTime<Utc>;
+
+    #[inline]
+    fn convert(value: DateTime<Utc>) -> Self::Instant {
+        value
+    }
+}
+
+/// Represents an interval between two instants.
+///
+/// An `Interval` is defined by a start and end time instant of type `T`,
+/// where `T` implements the `TimeInstant` trait. This allows for periods
+/// defined in different time systems (Julian Date, Modified Julian Date, UTC, etc.).
+///
+/// # Examples
+///
+/// ```
+/// # use tempoch_core as tempoch;
+/// use tempoch::{Interval, ModifiedJulianDate};
+///
+/// let start = ModifiedJulianDate::new(59000.0);
+/// let end = ModifiedJulianDate::new(59001.0);
+/// let period = Interval::new(start, end);
+///
+/// // Duration in days
+/// let duration = period.duration();
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Interval<T: TimeInstant> {
+    pub start: T,
+    pub end: T,
+}
+
+/// Time-scale period alias.
+///
+/// This follows the same marker pattern as [`Time<S>`], so callers can write:
+/// `Period<MJD>`, `Period<JD>`, etc.
+pub type Period<S> = Interval<Time<S>>;
+
+/// UTC interval alias.
+pub type UtcPeriod = Interval<DateTime<Utc>>;
+
+impl<T: TimeInstant> Interval<T> {
+    /// Creates a new period between two time instants.
+    ///
+    /// **Note:** this constructor does not validate that `start <= end`.
+    /// Prefer [`try_new`](Self::try_new) when endpoints come from untrusted
+    /// or computed input.
+    ///
+    /// # Arguments
+    ///
+    /// * `start` - The start time instant
+    /// * `end` - The end time instant
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use tempoch_core as tempoch;
+    /// use tempoch::{Interval, JulianDate};
+    ///
+    /// let start = JulianDate::new(2451545.0);
+    /// let end = JulianDate::new(2451546.0);
+    /// let period = Interval::new(start, end);
+    /// ```
+    pub fn new(start: T, end: T) -> Self {
+        Interval { start, end }
+    }
+
+    /// Creates a new interval, validating that `start <= end`.
+    ///
+    /// Returns [`InvalidIntervalError::StartAfterEnd`] if the start instant
+    /// is after the end instant.  This also rejects `NaN`-based instants,
+    /// since `NaN` comparisons always return `false`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use tempoch_core as tempoch;
+    /// use tempoch::{Interval, JulianDate};
+    ///
+    /// let ok = Interval::try_new(JulianDate::new(100.0), JulianDate::new(200.0));
+    /// assert!(ok.is_ok());
+    ///
+    /// let err = Interval::try_new(JulianDate::new(200.0), JulianDate::new(100.0));
+    /// assert!(err.is_err());
+    /// ```
+    pub fn try_new(start: T, end: T) -> Result<Self, InvalidIntervalError> {
+        if start <= end {
+            Ok(Interval { start, end })
+        } else {
+            Err(InvalidIntervalError::StartAfterEnd)
+        }
+    }
+
+    /// Returns the duration of the period as the difference between end and start.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use tempoch_core as tempoch;
+    /// use tempoch::{Interval, JulianDate};
+    /// use qtty::Days;
+    ///
+    /// let start = JulianDate::new(2451545.0);
+    /// let end = JulianDate::new(2451546.5);
+    /// let period = Interval::new(start, end);
+    ///
+    /// let duration = period.duration();
+    /// assert_eq!(duration, Days::new(1.5));
+    /// ```
+    pub fn duration(&self) -> T::Duration {
+        self.end.difference(&self.start)
+    }
+
+    /// Returns the overlapping sub-period between `self` and `other`.
+    ///
+    /// Periods are treated as half-open ranges `[start, end)`: if one period
+    /// ends exactly when the other starts, the intersection is empty and `None`
+    /// is returned.
+    pub fn intersection(&self, other: &Self) -> Option<Self> {
+        let start = if self.start >= other.start {
+            self.start
+        } else {
+            other.start
+        };
+        let end = if self.end <= other.end {
+            self.end
+        } else {
+            other.end
+        };
+
+        if start < end {
+            Some(Self::new(start, end))
+        } else {
+            None
+        }
+    }
+}
+
+// Display implementation
+impl<T: TimeInstant + fmt::Display> fmt::Display for Interval<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} to {}", self.start, self.end)
+    }
+}
+
+impl<S: TimeScale> Interval<Time<S>> {
+    /// Convert this period to another time scale.
+    ///
+    /// Each endpoint is converted preserving the represented absolute interval.
+    ///
+    /// Supported targets:
+    /// - Any time-scale marker (`JD`, `MJD`, `UT`, ...)
+    /// - `chrono::DateTime<Utc>`
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ConversionError::OutOfRange`] if the endpoints fall outside
+    /// the representable range of the target type (only possible when
+    /// converting to `DateTime<Utc>`).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use chrono::{DateTime, Utc};
+    /// # use tempoch_core as tempoch;
+    /// use tempoch::{Interval, JD, MJD, Period, Time};
+    ///
+    /// let period_jd = Period::new(Time::<JD>::new(2451545.0), Time::<JD>::new(2451546.0));
+    /// let period_mjd = period_jd.to::<MJD>().unwrap();
+    /// let _period_utc: Interval<DateTime<Utc>> = period_jd.to::<DateTime<Utc>>().unwrap();
+    ///
+    /// assert!((period_mjd.start.value() - 51544.5).abs() < 1e-12);
+    /// assert!((period_mjd.end.value() - 51545.5).abs() < 1e-12);
+    /// ```
+    #[inline]
+    pub fn to<Target>(
+        &self,
+    ) -> Result<Interval<<Target as PeriodTimeTarget<S>>::Instant>, ConversionError>
+    where
+        Target: PeriodTimeTarget<S>,
+    {
+        Ok(Interval::new(
+            Target::convert(self.start)?,
+            Target::convert(self.end)?,
+        ))
+    }
+}
+
+// Specific implementation for periods with Days duration (JD and MJD)
+impl<T: TimeInstant<Duration = Days>> Interval<T> {
+    /// Returns the duration of the period in days as a floating-point value.
+    ///
+    /// This method is available for time instants with `Days` as their duration type
+    /// (e.g., `JulianDate` and `ModifiedJulianDate`).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use tempoch_core as tempoch;
+    /// use tempoch::{Interval, ModifiedJulianDate};
+    /// use qtty::Days;
+    ///
+    /// let start = ModifiedJulianDate::new(59000.0);
+    /// let end = ModifiedJulianDate::new(59001.5);
+    /// let period = Interval::new(start, end);
+    ///
+    /// assert_eq!(period.duration_days(), Days::new(1.5));
+    /// ```
+    pub fn duration_days(&self) -> Days {
+        self.duration()
+    }
+}
+
+// Specific implementation for UTC periods
+impl Interval<DateTime<Utc>> {
+    /// Convert this UTC interval to another target.
+    ///
+    /// Supported targets:
+    /// - Any time-scale marker (`JD`, `MJD`, `UT`, ...)
+    /// - Any `Time<...>` alias (`JulianDate`, `ModifiedJulianDate`, ...)
+    /// - `chrono::DateTime<Utc>`
+    #[inline]
+    pub fn to<Target>(&self) -> Interval<<Target as PeriodUtcTarget>::Instant>
+    where
+        Target: PeriodUtcTarget,
+    {
+        Interval::new(Target::convert(self.start), Target::convert(self.end))
+    }
+
+    /// Returns the duration in days as a floating-point value.
+    ///
+    /// This converts the chrono::Duration to days.
+    pub fn duration_days(&self) -> f64 {
+        const NANOS_PER_DAY: f64 = 86_400_000_000_000.0;
+        const SECONDS_PER_DAY: f64 = 86_400.0;
+
+        let duration = self.duration();
+        match duration.num_nanoseconds() {
+            Some(ns) => ns as f64 / NANOS_PER_DAY,
+            // Fallback for exceptionally large durations that do not fit in i64 nanoseconds.
+            None => duration.num_seconds() as f64 / SECONDS_PER_DAY,
+        }
+    }
+
+    /// Returns the duration in seconds.
+    pub fn duration_seconds(&self) -> i64 {
+        self.duration().num_seconds()
+    }
+}
+
+// Serde support for Period<MJD> (= Interval<Time<MJD>>)
+//
+// Uses the historical field names `start_mjd` / `end_mjd` for backward
+// compatibility with existing JSON reference data.
+#[cfg(feature = "serde")]
+impl Serialize for Interval<crate::ModifiedJulianDate> {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        let mut s = serializer.serialize_struct("Period", 2)?;
+        s.serialize_field("start_mjd", &self.start.value())?;
+        s.serialize_field("end_mjd", &self.end.value())?;
+        s.end()
+    }
+}
+
+#[cfg(feature = "serde")]
+impl<'de> Deserialize<'de> for Interval<crate::ModifiedJulianDate> {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct Raw {
+            start_mjd: f64,
+            end_mjd: f64,
+        }
+
+        let raw = Raw::deserialize(deserializer)?;
+        if !raw.start_mjd.is_finite() || !raw.end_mjd.is_finite() {
+            return Err(serde::de::Error::custom(
+                "period MJD values must be finite (not NaN or infinity)",
+            ));
+        }
+        if raw.start_mjd > raw.end_mjd {
+            return Err(serde::de::Error::custom(
+                "period start must not be after end",
+            ));
+        }
+        Ok(Interval::new(
+            crate::ModifiedJulianDate::new(raw.start_mjd),
+            crate::ModifiedJulianDate::new(raw.end_mjd),
+        ))
+    }
+}
+
+// Serde support for Period<JD> (= Interval<Time<JD>>)
+#[cfg(feature = "serde")]
+impl Serialize for Interval<crate::JulianDate> {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        let mut s = serializer.serialize_struct("Period", 2)?;
+        s.serialize_field("start_jd", &self.start.value())?;
+        s.serialize_field("end_jd", &self.end.value())?;
+        s.end()
+    }
+}
+
+#[cfg(feature = "serde")]
+impl<'de> Deserialize<'de> for Interval<crate::JulianDate> {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        struct Raw {
+            start_jd: f64,
+            end_jd: f64,
+        }
+
+        let raw = Raw::deserialize(deserializer)?;
+        if !raw.start_jd.is_finite() || !raw.end_jd.is_finite() {
+            return Err(serde::de::Error::custom(
+                "period JD values must be finite (not NaN or infinity)",
+            ));
+        }
+        if raw.start_jd > raw.end_jd {
+            return Err(serde::de::Error::custom(
+                "period start must not be after end",
+            ));
+        }
+        Ok(Interval::new(
+            crate::JulianDate::new(raw.start_jd),
+            crate::JulianDate::new(raw.end_jd),
+        ))
+    }
+}
+
+/// Returns the gaps (complement) of `periods` within the bounding `outer` period.
+///
+/// Given a sorted, non-overlapping list of sub-periods and a bounding period,
+/// this returns the time intervals NOT covered by any sub-period.
+///
+/// Both `outer` and every element of `periods` must have `start <= end`.
+/// The function runs in O(n) time with a single pass.
+///
+/// # Arguments
+/// * `outer` - The bounding period
+/// * `periods` - Sorted, non-overlapping sub-periods within `outer`
+///
+/// # Returns
+/// The complement periods (gaps) in chronological order.
+pub fn complement_within<T: TimeInstant>(
+    outer: Interval<T>,
+    periods: &[Interval<T>],
+) -> Vec<Interval<T>> {
+    let mut gaps = Vec::new();
+    let mut cursor = outer.start;
+    for p in periods {
+        if p.start > cursor {
+            gaps.push(Interval::new(cursor, p.start));
+        }
+        if p.end > cursor {
+            cursor = p.end;
+        }
+    }
+    if cursor < outer.end {
+        gaps.push(Interval::new(cursor, outer.end));
+    }
+    gaps
+}
+
+/// Returns the intersection of two sorted, non-overlapping period lists.
+///
+/// Uses an O(n+m) merge algorithm to find all overlapping spans.
+///
+/// # Arguments
+/// * `a` - First sorted, non-overlapping period list
+/// * `b` - Second sorted, non-overlapping period list
+///
+/// # Returns
+/// Periods where both `a` and `b` overlap, in chronological order.
+pub fn intersect_periods<T: TimeInstant>(a: &[Interval<T>], b: &[Interval<T>]) -> Vec<Interval<T>> {
+    let mut result = Vec::new();
+    let (mut i, mut j) = (0, 0);
+    while i < a.len() && j < b.len() {
+        let start = if a[i].start >= b[j].start {
+            a[i].start
+        } else {
+            b[j].start
+        };
+        let end = if a[i].end <= b[j].end {
+            a[i].end
+        } else {
+            b[j].end
+        };
+        if start < end {
+            result.push(Interval::new(start, end));
+        }
+        if a[i].end <= b[j].end {
+            i += 1;
+        } else {
+            j += 1;
+        }
+    }
+    result
+}
+
+/// Validate that a period list is sorted by start time and non-overlapping.
+///
+/// Checks three invariants on every element:
+/// 1. Each interval has `start <= end`.
+/// 2. Intervals are sorted by start time (monotonically non-decreasing).
+/// 3. Adjacent intervals do not overlap (previous `end <= next start`).
+///
+/// Returns `Ok(())` if all invariants hold, or the first violation found.
+///
+/// # Examples
+///
+/// ```
+/// # use tempoch_core as tempoch;
+/// use tempoch::{validate_period_list, Interval, ModifiedJulianDate};
+///
+/// let sorted = vec![
+///     Interval::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0)),
+///     Interval::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0)),
+/// ];
+/// assert!(validate_period_list(&sorted).is_ok());
+/// ```
+pub fn validate_period_list<T: TimeInstant>(
+    periods: &[Interval<T>],
+) -> Result<(), PeriodListError> {
+    for (i, p) in periods.iter().enumerate() {
+        if p.start
+            .partial_cmp(&p.end)
+            .is_none_or(|o| o == std::cmp::Ordering::Greater)
+        {
+            return Err(PeriodListError::InvalidInterval { index: i });
+        }
+    }
+    for i in 1..periods.len() {
+        if periods[i - 1]
+            .start
+            .partial_cmp(&periods[i].start)
+            .is_none_or(|o| o == std::cmp::Ordering::Greater)
+        {
+            return Err(PeriodListError::Unsorted { index: i });
+        }
+        if periods[i - 1].end > periods[i].start {
+            return Err(PeriodListError::Overlapping { index: i });
+        }
+    }
+    Ok(())
+}
+
+/// Sort periods by start time and merge overlapping/adjacent intervals.
+///
+/// Produces a sorted, non-overlapping list suitable for [`complement_within`]
+/// and [`intersect_periods`].
+///
+/// # Examples
+///
+/// ```
+/// # use tempoch_core as tempoch;
+/// use tempoch::{normalize_periods, Interval, ModifiedJulianDate};
+///
+/// let periods = vec![
+///     Interval::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0)),
+///     Interval::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0)),
+///     Interval::new(ModifiedJulianDate::new(2.0), ModifiedJulianDate::new(6.0)),
+/// ];
+/// let merged = normalize_periods(&periods);
+/// assert_eq!(merged.len(), 1); // [0, 8)
+/// ```
+pub fn normalize_periods<T: TimeInstant>(periods: &[Interval<T>]) -> Vec<Interval<T>> {
+    if periods.is_empty() {
+        return Vec::new();
+    }
+    let mut sorted: Vec<_> = periods.to_vec();
+    sorted.sort_by(|a, b| {
+        a.start
+            .partial_cmp(&b.start)
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+    let mut merged = vec![sorted[0]];
+    for p in &sorted[1..] {
+        let last = merged.last_mut().unwrap();
+        if p.start <= last.end {
+            // Overlapping or adjacent — extend
+            if p.end > last.end {
+                last.end = p.end;
+            }
+        } else {
+            merged.push(*p);
+        }
+    }
+    merged
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{JulianDate, ModifiedJulianDate, JD, MJD};
+
+    #[test]
+    fn test_try_new_valid() {
+        let p = Interval::try_new(
+            ModifiedJulianDate::new(59000.0),
+            ModifiedJulianDate::new(59001.0),
+        );
+        assert!(p.is_ok());
+    }
+
+    #[test]
+    fn test_try_new_equal_bounds() {
+        let p = Interval::try_new(
+            ModifiedJulianDate::new(59000.0),
+            ModifiedJulianDate::new(59000.0),
+        );
+        assert!(p.is_ok()); // zero-length interval is valid
+    }
+
+    #[test]
+    fn test_try_new_invalid() {
+        let p = Interval::try_new(
+            ModifiedJulianDate::new(59001.0),
+            ModifiedJulianDate::new(59000.0),
+        );
+        assert_eq!(p, Err(InvalidIntervalError::StartAfterEnd));
+    }
+
+    #[test]
+    fn test_try_new_nan_rejected() {
+        let p = Interval::try_new(
+            ModifiedJulianDate::new(f64::NAN),
+            ModifiedJulianDate::new(59000.0),
+        );
+        assert!(p.is_err());
+    }
+
+    #[test]
+    fn test_validate_period_list_ok() {
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0)),
+            Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0)),
+        ];
+        assert!(validate_period_list(&periods).is_ok());
+    }
+
+    #[test]
+    fn test_validate_period_list_unsorted() {
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0)),
+            Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0)),
+        ];
+        assert_eq!(
+            validate_period_list(&periods),
+            Err(PeriodListError::Unsorted { index: 1 })
+        );
+    }
+
+    #[test]
+    fn test_validate_period_list_overlapping() {
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(5.0)),
+            Period::new(ModifiedJulianDate::new(3.0), ModifiedJulianDate::new(8.0)),
+        ];
+        assert_eq!(
+            validate_period_list(&periods),
+            Err(PeriodListError::Overlapping { index: 1 })
+        );
+    }
+
+    #[test]
+    fn test_validate_period_list_invalid_interval() {
+        let periods = vec![Period::new(
+            ModifiedJulianDate::new(5.0),
+            ModifiedJulianDate::new(3.0),
+        )];
+        assert_eq!(
+            validate_period_list(&periods),
+            Err(PeriodListError::InvalidInterval { index: 0 })
+        );
+    }
+
+    #[test]
+    fn test_normalize_periods_empty() {
+        let periods: Vec<Period<MJD>> = vec![];
+        assert!(normalize_periods(&periods).is_empty());
+    }
+
+    #[test]
+    fn test_normalize_periods_unsorted_and_overlapping() {
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0)),
+            Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0)),
+            Period::new(ModifiedJulianDate::new(2.0), ModifiedJulianDate::new(6.0)),
+        ];
+        let merged = normalize_periods(&periods);
+        assert_eq!(merged.len(), 1);
+        assert_eq!(merged[0].start.quantity(), Days::new(0.0));
+        assert_eq!(merged[0].end.quantity(), Days::new(8.0));
+    }
+
+    #[test]
+    fn test_normalize_periods_disjoint() {
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(6.0)),
+            Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(2.0)),
+        ];
+        let merged = normalize_periods(&periods);
+        assert_eq!(merged.len(), 2);
+        assert_eq!(merged[0].start.quantity(), Days::new(0.0));
+        assert_eq!(merged[1].start.quantity(), Days::new(5.0));
+    }
+
+    #[test]
+    fn test_period_creation_jd() {
+        let start = JulianDate::new(2451545.0);
+        let end = JulianDate::new(2451546.0);
+        let period = Period::new(start, end);
+
+        assert_eq!(period.start, start);
+        assert_eq!(period.end, end);
+    }
+
+    #[test]
+    fn test_period_scale_conversion_jd_to_mjd() {
+        let period_jd = Period::new(Time::<JD>::new(2_451_545.0), Time::<JD>::new(2_451_546.0));
+        let period_mjd = period_jd.to::<MJD>().unwrap();
+
+        assert!((period_mjd.start.value() - 51_544.5).abs() < 1e-12);
+        assert!((period_mjd.end.value() - 51_545.5).abs() < 1e-12);
+    }
+
+    #[test]
+    fn test_period_scale_conversion_roundtrip() {
+        let original = Period::new(Time::<MJD>::new(59_000.125), Time::<MJD>::new(59_001.75));
+        let roundtrip = original.to::<JD>().unwrap().to::<MJD>().unwrap();
+
+        assert!((roundtrip.start.value() - original.start.value()).abs() < 1e-12);
+        assert!((roundtrip.end.value() - original.end.value()).abs() < 1e-12);
+    }
+
+    #[test]
+    fn test_period_scale_conversion_to_utc() {
+        let start_utc = DateTime::from_timestamp(1_700_000_000, 0).unwrap();
+        let end_utc = DateTime::from_timestamp(1_700_000_600, 0).unwrap();
+        let period_jd = Period::new(
+            Time::<JD>::from_utc(start_utc),
+            Time::<JD>::from_utc(end_utc),
+        );
+
+        let period_utc = period_jd.to::<DateTime<Utc>>().unwrap();
+        let start_delta_ns = period_utc.start.timestamp_nanos_opt().unwrap()
+            - start_utc.timestamp_nanos_opt().unwrap();
+        let end_delta_ns =
+            period_utc.end.timestamp_nanos_opt().unwrap() - end_utc.timestamp_nanos_opt().unwrap();
+        assert!(start_delta_ns.abs() < 10_000);
+        assert!(end_delta_ns.abs() < 10_000);
+    }
+
+    #[test]
+    fn test_period_creation_mjd() {
+        let start = ModifiedJulianDate::new(59000.0);
+        let end = ModifiedJulianDate::new(59001.0);
+        let period = Period::new(start, end);
+
+        assert_eq!(period.start, start);
+        assert_eq!(period.end, end);
+    }
+
+    #[test]
+    fn test_period_duration_jd() {
+        let start = JulianDate::new(2451545.0);
+        let end = JulianDate::new(2451546.5);
+        let period = Period::new(start, end);
+
+        assert_eq!(period.duration_days(), Days::new(1.5));
+    }
+
+    #[test]
+    fn test_period_duration_mjd() {
+        let start = ModifiedJulianDate::new(59000.0);
+        let end = ModifiedJulianDate::new(59001.5);
+        let period = Period::new(start, end);
+
+        assert_eq!(period.duration_days(), Days::new(1.5));
+    }
+
+    #[test]
+    fn test_period_duration_utc() {
+        let start = DateTime::from_timestamp(0, 0).unwrap();
+        let end = DateTime::from_timestamp(86400, 0).unwrap(); // 1 day later
+        let period = Interval::new(start, end);
+
+        assert_eq!(period.duration_days(), 1.0);
+        assert_eq!(period.duration_seconds(), 86400);
+    }
+
+    #[test]
+    fn test_period_duration_utc_subsecond_precision() {
+        let start = DateTime::from_timestamp(0, 0).unwrap();
+        let end = DateTime::from_timestamp(0, 500_000_000).unwrap();
+        let period = Interval::new(start, end);
+
+        let expected_days = 0.5 / 86_400.0;
+        assert!((period.duration_days() - expected_days).abs() < 1e-15);
+        assert_eq!(period.duration_seconds(), 0);
+    }
+
+    #[test]
+    fn test_period_to_conversion() {
+        let mjd_start = ModifiedJulianDate::new(59000.0);
+        let mjd_end = ModifiedJulianDate::new(59001.0);
+        let mjd_period = Period::new(mjd_start, mjd_end);
+
+        let utc_period = mjd_period.to::<DateTime<Utc>>().unwrap();
+
+        // The converted period should have approximately the same duration (within 1 second due to ΔT)
+        let duration_secs = utc_period.duration().num_seconds();
+        assert!(
+            (duration_secs - 86400).abs() <= 1,
+            "Duration was {} seconds",
+            duration_secs
+        );
+
+        // Convert back and check that it's close (within small tolerance due to floating point)
+        let back_to_mjd = utc_period.to::<ModifiedJulianDate>();
+        let start_diff = (back_to_mjd.start.quantity() - mjd_start.quantity())
+            .value()
+            .abs();
+        let end_diff = (back_to_mjd.end.quantity() - mjd_end.quantity())
+            .value()
+            .abs();
+        assert!(start_diff < 1e-6, "Start difference: {}", start_diff);
+        assert!(end_diff < 1e-6, "End difference: {}", end_diff);
+    }
+
+    #[test]
+    fn test_period_display() {
+        let start = ModifiedJulianDate::new(59000.0);
+        let end = ModifiedJulianDate::new(59001.0);
+        let period = Period::new(start, end);
+
+        let display = format!("{}", period);
+        assert!(display.contains("MJD 59000"));
+        assert!(display.contains("MJD 59001"));
+        assert!(display.contains("to"));
+    }
+
+    #[test]
+    fn test_period_intersection_overlap() {
+        let a = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(5.0));
+        let b = Period::new(ModifiedJulianDate::new(3.0), ModifiedJulianDate::new(8.0));
+
+        let overlap = a.intersection(&b).expect("expected overlap");
+        assert_eq!(overlap.start.quantity(), Days::new(3.0));
+        assert_eq!(overlap.end.quantity(), Days::new(5.0));
+    }
+
+    #[test]
+    fn test_period_intersection_disjoint() {
+        let a = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0));
+        let b = Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(8.0));
+
+        assert_eq!(a.intersection(&b), None);
+    }
+
+    #[test]
+    fn test_period_intersection_touching_edges() {
+        let a = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(3.0));
+        let b = Period::new(ModifiedJulianDate::new(3.0), ModifiedJulianDate::new(8.0));
+
+        assert_eq!(a.intersection(&b), None);
+    }
+
+    #[test]
+    fn test_complement_within_gaps() {
+        let outer = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(10.0));
+        let periods = vec![
+            Period::new(ModifiedJulianDate::new(2.0), ModifiedJulianDate::new(4.0)),
+            Period::new(ModifiedJulianDate::new(6.0), ModifiedJulianDate::new(8.0)),
+        ];
+        let gaps = complement_within(outer, &periods);
+        assert_eq!(gaps.len(), 3);
+        assert_eq!(gaps[0].start.quantity(), Days::new(0.0));
+        assert_eq!(gaps[0].end.quantity(), Days::new(2.0));
+        assert_eq!(gaps[1].start.quantity(), Days::new(4.0));
+        assert_eq!(gaps[1].end.quantity(), Days::new(6.0));
+        assert_eq!(gaps[2].start.quantity(), Days::new(8.0));
+        assert_eq!(gaps[2].end.quantity(), Days::new(10.0));
+    }
+
+    #[test]
+    fn test_complement_within_empty() {
+        let outer = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(10.0));
+        let gaps = complement_within(outer, &[]);
+        assert_eq!(gaps.len(), 1);
+        assert_eq!(gaps[0].start.quantity(), Days::new(0.0));
+        assert_eq!(gaps[0].end.quantity(), Days::new(10.0));
+    }
+
+    #[test]
+    fn test_complement_within_full() {
+        let outer = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(10.0));
+        let periods = vec![Period::new(
+            ModifiedJulianDate::new(0.0),
+            ModifiedJulianDate::new(10.0),
+        )];
+        let gaps = complement_within(outer, &periods);
+        assert!(gaps.is_empty());
+    }
+
+    #[test]
+    fn test_intersect_periods_overlap() {
+        let a = vec![Period::new(
+            ModifiedJulianDate::new(0.0),
+            ModifiedJulianDate::new(5.0),
+        )];
+        let b = vec![Period::new(
+            ModifiedJulianDate::new(3.0),
+            ModifiedJulianDate::new(8.0),
+        )];
+        let overlap = intersect_periods(&a, &b);
+        assert_eq!(overlap.len(), 1);
+        assert_eq!(overlap[0].start.quantity(), Days::new(3.0));
+        assert_eq!(overlap[0].end.quantity(), Days::new(5.0));
+    }
+
+    #[test]
+    fn test_intersect_periods_no_overlap() {
+        let a = vec![Period::new(
+            ModifiedJulianDate::new(0.0),
+            ModifiedJulianDate::new(3.0),
+        )];
+        let b = vec![Period::new(
+            ModifiedJulianDate::new(5.0),
+            ModifiedJulianDate::new(8.0),
+        )];
+        let overlap = intersect_periods(&a, &b);
+        assert!(overlap.is_empty());
+    }
+
+    #[test]
+    fn test_complement_intersect_roundtrip() {
+        // above(min) ∩ complement(above(max)) = between(min, max)
+        let outer = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(10.0));
+        let above_min = vec![
+            Period::new(ModifiedJulianDate::new(1.0), ModifiedJulianDate::new(3.0)),
+            Period::new(ModifiedJulianDate::new(5.0), ModifiedJulianDate::new(9.0)),
+        ];
+        let above_max = vec![
+            Period::new(ModifiedJulianDate::new(2.0), ModifiedJulianDate::new(4.0)),
+            Period::new(ModifiedJulianDate::new(7.0), ModifiedJulianDate::new(8.0)),
+        ];
+        let below_max = complement_within(outer, &above_max);
+        let between = intersect_periods(&above_min, &below_max);
+        // above_min: [1,3), [5,9)
+        // above_max: [2,4), [7,8)
+        // below_max (complement): [0,2), [4,7), [8,10)
+        // intersection: [1,2), [5,7), [8,9)
+        assert_eq!(between.len(), 3);
+        assert_eq!(between[0].start.quantity(), Days::new(1.0));
+        assert_eq!(between[0].end.quantity(), Days::new(2.0));
+        assert_eq!(between[1].start.quantity(), Days::new(5.0));
+        assert_eq!(between[1].end.quantity(), Days::new(7.0));
+        assert_eq!(between[2].start.quantity(), Days::new(8.0));
+        assert_eq!(between[2].end.quantity(), Days::new(9.0));
+    }
+
+    // ── New coverage tests ────────────────────────────────────────────
+
+    #[test]
+    fn test_conversion_error_display() {
+        let err = ConversionError::OutOfRange;
+        let msg = format!("{err}");
+        assert!(msg.contains("out of representable range"), "got: {msg}");
+    }
+
+    #[test]
+    fn test_conversion_error_is_error() {
+        let err = ConversionError::OutOfRange;
+        // Verify it satisfies std::error::Error
+        let _: &dyn std::error::Error = &err;
+    }
+
+    #[test]
+    fn test_invalid_interval_error_display() {
+        let err = InvalidIntervalError::StartAfterEnd;
+        let msg = format!("{err}");
+        assert!(msg.contains("start must not be after end"), "got: {msg}");
+    }
+
+    #[test]
+    fn test_invalid_interval_error_is_error() {
+        let err = InvalidIntervalError::StartAfterEnd;
+        let _: &dyn std::error::Error = &err;
+    }
+
+    #[test]
+    fn test_period_list_error_invalid_interval_display() {
+        let e = PeriodListError::InvalidInterval { index: 0 };
+        let msg = format!("{e}");
+        assert!(msg.contains("index 0"), "got: {msg}");
+    }
+
+    #[test]
+    fn test_period_list_error_unsorted_display() {
+        let e = PeriodListError::Unsorted { index: 2 };
+        let msg = format!("{e}");
+        assert!(msg.contains("index 2"), "got: {msg}");
+    }
+
+    #[test]
+    fn test_period_list_error_overlapping_display() {
+        let e = PeriodListError::Overlapping { index: 3 };
+        let msg = format!("{e}");
+        assert!(msg.contains("index 3"), "got: {msg}");
+    }
+
+    #[test]
+    fn test_period_list_error_is_error() {
+        let e = PeriodListError::InvalidInterval { index: 0 };
+        let _: &dyn std::error::Error = &e;
+    }
+
+    #[test]
+    fn test_intersection_self_larger_than_other() {
+        // a.start > b.start  AND  a.end > b.end  → intersection picks a.start and b.end.
+        // Exercises the `self.start` branch (line 284) and the `other.end` branch (line 291).
+        let a = Period::new(ModifiedJulianDate::new(2.0), ModifiedJulianDate::new(8.0));
+        let b = Period::new(ModifiedJulianDate::new(0.0), ModifiedJulianDate::new(5.0));
+        let overlap = a.intersection(&b).expect("should overlap");
+        assert_eq!(overlap.start.quantity(), Days::new(2.0));
+        assert_eq!(overlap.end.quantity(), Days::new(5.0));
+    }
+
+    #[test]
+    fn test_period_time_target_for_time_type() {
+        // Use `ModifiedJulianDate` (= Time<MJD>) as the Target type parameter,
+        // not the bare `MJD` marker, to exercise the PeriodTimeTarget impl for Time<T>.
+        let period_jd = Period::new(Time::<JD>::new(2_451_545.0), Time::<JD>::new(2_451_546.0));
+        let period_mjd: Interval<ModifiedJulianDate> =
+            period_jd.to::<ModifiedJulianDate>().unwrap();
+        assert!((period_mjd.start.value() - 51_544.5).abs() < 1e-12);
+        assert!((period_mjd.end.value() - 51_545.5).abs() < 1e-12);
+    }
+
+    #[test]
+    fn test_utc_period_to_datetime_utc_identity() {
+        // Converting an Interval<DateTime<Utc>> to DateTime<Utc> again is a
+        // no-op; exercises PeriodUtcTarget for DateTime<Utc>.
+        let start = DateTime::from_timestamp(0, 0).unwrap();
+        let end = DateTime::from_timestamp(86400, 0).unwrap();
+        let utc_period = Interval::new(start, end);
+        let same: Interval<DateTime<Utc>> = utc_period.to::<DateTime<Utc>>();
+        assert_eq!(same.start, start);
+        assert_eq!(same.end, end);
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn test_period_mjd_serde_roundtrip() {
+        let p = Period::new(
+            ModifiedJulianDate::new(59000.0),
+            ModifiedJulianDate::new(59001.0),
+        );
+        let json = serde_json::to_string(&p).unwrap();
+        assert!(json.contains("start_mjd"), "serialized: {json}");
+        let back: Period<MJD> = serde_json::from_str(&json).unwrap();
+        assert!((back.start.value() - 59000.0).abs() < 1e-12);
+        assert!((back.end.value() - 59001.0).abs() < 1e-12);
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn test_period_mjd_deserialize_start_after_end_rejected() {
+        let json = r#"{"start_mjd": 59001.0, "end_mjd": 59000.0}"#;
+        let result: Result<Period<MJD>, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn test_period_jd_serde_roundtrip() {
+        let p = Period::new(JulianDate::new(2_451_545.0), JulianDate::new(2_451_546.0));
+        let json = serde_json::to_string(&p).unwrap();
+        assert!(json.contains("start_jd"), "serialized: {json}");
+        let back: Period<JD> = serde_json::from_str(&json).unwrap();
+        assert!((back.start.value() - 2_451_545.0).abs() < 1e-12);
+        assert!((back.end.value() - 2_451_546.0).abs() < 1e-12);
+    }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn test_period_jd_deserialize_start_after_end_rejected() {
+        let json = r#"{"start_jd": 2451546.0, "end_jd": 2451545.0}"#;
+        let result: Result<Period<JD>, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+}