horologium 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65e0d322bb82639c79c818b3c8473f507ecfcb25215c522f20d41c5ef7f5be25
-  data.tar.gz: 1d2d822d56768a6d9383cc29a700208e03ef3e6f639460d1a99b4eb18e01e1de
+  metadata.gz: 36835b6c549b41c5f598c2ed04052c7ef7ee21c6cc9265f21fadedce465ecfe5
+  data.tar.gz: 012c847982be87b762829bc0634a9c363847da2e57f7c6c12e3a5496202da517
 SHA512:
-  metadata.gz: b4c87cfb9449bb41e362d2596c03ff44e2907ab593c332eb37155fb833b7d8a366911eece54a0759fff1e72410599c244c82d6757d49df66edf904783115f811
-  data.tar.gz: 3fda2d236fb3c9afaa33e921a0a3e3738518df46cefc9e10146acf590f144cdd67f4c162448fef7c2a002ba62cd74efbd45f500b069c91e8a8020341ec082f22
+  metadata.gz: be4aa86367a43374d70fced595fca0726abda0f6ee55ef781bb94bb2caef9b3203a537ba2c5282b89cca260f682fe7742cc55f14bdce231703b4146f904f2d63
+  data.tar.gz: 549ae0c37882e78f29f566634b46b57e529e3aab38f9f11aa1d0b1a00b003716340c69baad274217380c93b2933847435d0c5a07a8b6f239219c973fe956ce1e

data/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.0.5 - 2026-09-08
+
+All eight scales are in, so an instant reads in any of them, and the domain
+model is complete: the point, the quantity, and the span between two points.
+A `Time` bridges in from the standard library, a duration scales and reads
+ISO 8601, and everything the library cannot compute with is refused by name
+rather than by whatever Ruby happened to raise.
+
+### Breaking changes
+
+- A value the library cannot read raises `InvalidValueError` instead of
+  `ArgumentError`. `Error`'s promise is that a caller can rescue Horologium as
+  a unit, and it did not hold: a Float that was not finite came back as
+  `FloatDomainError` and a Symbol given to a `Duration` constructor as
+  `NoMethodError`. Dividing by zero is the one error left as Ruby's own
+- The civil calendar is bounded above as well as below, from -4799 to 2733193,
+  the range ERFA documents for its calendar routines. Julian Date 5e9 used to
+  read back as the year 13684822 rather than being refused
+
+### Features
+
+- Add `TCG` and `TCB`, the coordinate times of the Earth-centred and
+  barycentric frames, each running ahead of the scale it is defined on at a
+  rate fixed by definition and counted from 1977-01-01 00:00:00 TAI. TCG
+  inverts exactly at `:exact`; TCB's own edge does too, but the way to TAI
+  goes through TDB's floating-point model
+- Add `GPS`, a fixed 19 SI seconds behind TAI, which is where it stays because
+  it counts SI seconds and never takes a leap second
+- Add `UT1`, the scale the rotation of the Earth keeps and the only one here
+  that is measured rather than defined. It converts as TT minus delta T, which
+  is what lets it reach back to 1800: UTC is undefined before 1961 and refuses
+  the date, so a pre-1961 instant has a UT1 name where it can never have a UTC
+  one. A reading says whether the value was observed, predicted, or fitted
+- Add `Configuration#eop_source`, the Earth orientation data UT1 reads, and
+  `#ut1_horizon`, which chooses between reading past the end of the published
+  data with the last known delta T and refusing to
+- Add `Instant.now`, `.from_time`, `.from_unix` and `.from_offset`. A `Time`
+  is read in UTC and every field it carries is used, so nothing is rounded on
+  the way in. Unix time is read the way POSIX reads it, which is not a count
+  of elapsed seconds: it has no leap seconds, so reaching a UTC date costs an
+  extra SI second for each one inserted along the way
+- Add `Duration#*` and `#/`, which scale a duration by a plain number, and
+  `Duration.mean`, which averages a list of them in the split
+- Add `Duration.parse` and `Duration#to_iso8601`, reading and writing the
+  subset of ISO 8601 that is a quantity of time. Years and months are refused
+  because a duration cannot say how long they are; weeks are seven days
+  exactly but sit outside the subset all the same
+- Add `Interval`, a span between two instants, with `duration`, `cover?`,
+  `overlap?`, `intersection` and ISO 8601 either way. It holds its start and
+  excludes its end, so one window runs into the next without the two
+  overlapping on the moment they share. Its length is elapsed SI seconds, so a
+  two-hour window across the 2016 leap second is 7,201 seconds long
+- Add `InvalidValueError` and `InvalidIntervalError`
+
+### Fixes
+
+- Refuse a number that does not fit a Float where it has to become one, rather
+  than carrying on with an Infinity or a zero. Building a `:standard` value
+  from an Integer too large for a Float used to fail later, when the Infinity
+  had no rational form, and scaling a duration by a number too small used to
+  answer with no duration at all
+- Read every part of a two-part Julian Date. A NaN in either part used to
+  build an instant and surface later, in a reading, in a civil time, or in a
+  comparison
+- Read UT1 back into TAI within delta T of the earliest date the data covers.
+  Converting out subtracts delta T, so an instant that close to the edge
+  landed on a UT1 coordinate just before it, and reading that back refused
+- Report no overlap between a span of no time and anything, including a span
+  that surrounds it. It covers no instant, so there is no instant for the two
+  of them to share
+- Stop writing warnings to stderr. `Integer#to_f` warns on its way out of
+  range, so the guard that refuses such a number announced it first
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.4...v0.0.5
+
 ## 0.0.4 - 2026-09-05
 
 The epochs astronomy counts from arrive as instants, a duration reads back in

data/README.md

@@ -3,9 +3,9 @@
 [![Tests](https://github.com/rhannequin/horologium/workflows/CI/badge.svg)](https://github.com/rhannequin/horologium/actions?query=workflow%3ACI)
 
 Horologium is a Ruby library dedicated to **scientific time**: the time scales
-(TAI, TT, TDB, and UTC so far), high-precision instants, Julian Dates,
-intervals, and rigorous conversions between scales that astronomy and physics
-require.
+(TAI, TT, TDB, TCG, TCB, GPS, UTC and UT1), high-precision instants, Julian
+Dates, intervals, and rigorous conversions between scales that astronomy and
+physics require.
 
 Ruby already has `Time`, `Date`, `DateTime`, and `ActiveSupport` for civil time:
 time zones, calendars, human formatting. None of them knows the difference
@@ -17,6 +17,7 @@ Horologium fills.
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Intervals](#intervals)
 - [Precision](#precision)
 - [Status](#status)
 - [Development](#development)
@@ -85,6 +86,33 @@ Horologium::Instant.from_civil(2025, 5, 1, 12, 0, 0, scale: :tt)
 Horologium::Instant.from_civil(2025, 5, 1, 12, 0, Rational(1, 4), scale: :tt)
 ```
 
+Ruby's own `Time` is a bridge in, and the system clock is one line. A `Time`
+is read in UTC and every field it carries is used, so nothing is rounded on
+the way: `subsec` is a `Rational`, not a count of nanoseconds.
+
+```rb
+Horologium::Instant.now
+Horologium::Instant.from_time(Time.utc(2025, 5, 1, 12))
+Horologium::Instant.from_unix(1_370_351_716.32)
+
+Horologium::Instant.from_offset(
+  Horologium::Epochs::J2000,
+  Horologium::Duration.julian_centuries(0.25)
+)
+```
+
+Unix time is not a count of elapsed seconds. It has no leap seconds, so it is
+a way of writing a UTC date, and reaching a UTC date takes one more SI second
+for every leap second inserted along the way. `from_unix(1_700_000_000)` and
+`Epochs::UNIX + Duration.seconds(1_700_000_000)` are about 29 seconds apart,
+and the first one is the later.
+
+A `Time` cannot hold a leap second either. `Time.utc(2016, 12, 31, 23, 59, 60)`
+is silently the first moment of 2017, because POSIX time has no leap seconds
+and every day in it is 86,400 seconds long. `from_time` is exact for
+everything a `Time` can carry, but a timestamp that held a second 60 lost it
+before Horologium saw it; read that one with `from_utc` or `from_iso8601`.
+
 Each scale has its own shortcut, so the scale is in the name instead of a
 keyword.
 
@@ -92,12 +120,68 @@ keyword.
 Horologium::Instant.from_tt(2025, 5, 1, 12, 0, 0)
 Horologium::Instant.from_tai(2025, 5, 1, 12, 0, 0)
 Horologium::Instant.from_tdb(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tcg(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tcb(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_gps(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_ut1(2025, 5, 1, 12, 0, 0)
 ```
 
 TDB is the one scale that rests on a model rather than a definition. Horologium
 runs the full 787-term Fairhead and Bretagnon series, the one [ERFA] evaluates
 in `dtdb`, rather than a truncation of it.
 
+TCG and TCB are the coordinate times of the Earth-centred and barycentric
+frames. Each runs ahead of the scale it is defined on at a fixed rate set by
+definition, TCG on TT by about 22 milliseconds a year and TCB on TDB by about
+half a second, both counted from 1977-01-01 00:00:00 TAI. GPS time is a fixed
+19 SI seconds behind TAI and stays there, because it counts SI seconds and
+never takes a leap second.
+
+```rb
+instant = Horologium::Instant.from_julian_date(2_451_545.0, scale: :tt)
+
+instant.to(:tcg).as(:julian_date)  # => 2451545.0000058548
+instant.to(:tcb).as(:julian_date)  # => 2451545.000130251
+instant.to(:gps).as(:julian_date)  # => 2451544.9994075927
+```
+
+UT1 follows the actual rotation of the Earth, which is irregular, so it is the
+one scale here that is measured rather than defined. Horologium reads the
+difference from the [iers] gem and converts as `UT1 = TT - delta T`, not as
+`UTC + delta UT1`. That is what lets it reach back past 1961: UTC is not
+defined before then and refuses the date, while delta T is estimated from a
+polynomial fit as far back as 1800, so the instant still has a UT1 name.
+
+```rb
+instant = Horologium::Instant.from_ut1(1955, 1, 1, 12)
+
+instant.as(:iso8601, scale: :tt)   # => "1955-01-01T12:00:31.047050952"
+instant.as(:iso8601, scale: :utc)  # => raises OutOfRangeError
+```
+
+A UT1 reading says where its number came from, so you can tell an observation
+from a prediction from a fit. It is `:measured` where the published series
+observed it, `:extrapolated` where the series predicts it, and `:estimated`
+where the series does not reach and the polynomial answered instead.
+
+```rb
+Horologium::Instant.from_utc(2020, 1, 1).to(:ut1).provenance  # => :measured
+Horologium::Instant.from_ut1(1900, 1, 1).to(:ut1).provenance  # => :estimated
+```
+
+Past the end of the published data the last known delta T is held rather than
+refused, and the reading says `:extrapolated`. Holding it is a projection, not
+a bounded value: delta T follows the Earth's rotation, which drifts, and every
+leap second nobody has announced yet adds a second of its own. Over the months
+the data usually runs ahead it is worth milliseconds, but the error grows the
+further out you go, and over years it reaches seconds. The recent drift has
+been about 0.04 seconds a year, the last half century about 0.47. A pipeline
+that must not compute on it turns the reading into a refusal.
+
+```rb
+Horologium.configure { |c| c.ut1_horizon = :raise }
+```
+
 A date that does not exist is refused rather than rolled over, and the message
 says which field is wrong.
 
@@ -238,18 +322,48 @@ Horologium::Duration.julian_years(1) ==
 Horologium::Duration.julian_centuries(0.25)
 ```
 
-Durations add, subtract, and negate among themselves, and read back out in SI
-seconds.
+Durations add, subtract, and negate among themselves, scale by a plain number,
+and read back out in SI seconds.
 
 ```rb
 Horologium::Duration.seconds(30) + Horologium::Duration.seconds(12)
 Horologium::Duration.seconds(30) - Horologium::Duration.seconds(42)  # negative
 -Horologium::Duration.seconds(3)
 
+Horologium::Duration.hours(1) * 1.5  # => 90 minutes
+Horologium::Duration.hours(1) / 2    # => 30 minutes
+
+Horologium::Duration.mean(
+  [Horologium::Duration.seconds(1), Horologium::Duration.seconds(3)]
+)  # => 2 seconds
+
 Horologium::Duration.days(1).to_r  # => (86400/1), the whole value
 Horologium::Duration.days(1).to_f  # => 86400.0
 ```
 
+Scaling matters more than it looks. A quantity you can only add to another of
+its kind sends you back to raw seconds the moment you need half of one, and
+the precision the type exists to protect goes with you.
+
+A duration reads and writes ISO 8601, in the subset that is a quantity of time
+rather than a walk through a calendar. Years, months and weeks are refused: a
+year is 365 days or 366 and a month is anywhere from 28 to 31, so `P1Y` names
+a span the calendar resolves and a duration cannot.
+
+```rb
+Horologium::Duration.parse("PT4H5M6S").in_seconds  # => 14706.0
+Horologium::Duration.parse("P3D").in_seconds       # => 259200.0
+Horologium::Duration.seconds(14_706).to_iso8601    # => "PT4H5M6S"
+
+Horologium::Duration.parse("P1Y")  # => raises ParseError
+```
+
+The string holds nanoseconds, so a duration on that grid reads back into
+itself and one finer than it does not: an exact third of a second writes as
+`PT0.333333333S`, and a quarter of a nanosecond writes as `PT0S`. A third of a
+second has no finite decimal form at any resolution, so that is the format
+rather than the grid. Use `to_r` where the whole value has to survive.
+
 A duration also reads in a unit. The division happens inside the precision the
 duration is held in, so a `:standard` duration keeps the digits a collapsed
 `Float` would lose, and an `:exact` one reads as a `Rational`.
@@ -304,6 +418,51 @@ near = a + Horologium::Duration.nanoseconds(1)
 a.equal_within?(near, Horologium::Duration.nanoseconds(2))  # => true
 ```
 
+## Intervals
+
+An interval is a span between two instants: an observation campaign, an
+eclipse window, a satellite pass. It holds its start and excludes its end, so
+one window runs into the next without the two overlapping on the moment they
+share, and two windows that merely touch intersect in nothing.
+
+```rb
+window = Horologium::Interval.new(
+  Horologium::Instant.from_utc(2025, 5, 1),
+  Horologium::Instant.from_utc(2025, 5, 1, 2)
+)
+
+Horologium::Interval.from(
+  Horologium::Instant.from_utc(2025, 5, 1),
+  Horologium::Duration.hours(2)
+)
+
+window.start
+window.end
+window.duration
+window.cover?(Horologium::Instant.from_utc(2025, 5, 1, 1))
+window.overlap?(other)
+window.intersection(other)   # => an Interval, or nil
+window.to_iso8601(scale: :utc)
+```
+
+Its duration is elapsed SI seconds, and that is not the difference the clock
+shows. A two-hour window across the 2016 leap second is 7,201 seconds long,
+and this is the one place in the library where leap seconds show up without
+anyone having asked about them.
+
+```rb
+window = Horologium::Interval.parse(
+  "2016-12-31T23:00Z/2017-01-01T01:00Z",
+  scale: :utc,
+  precision: :exact
+)
+
+window.duration.in_seconds  # => (7201/1)
+```
+
+Repeating intervals (`R5/…`) are not read. Repetition is scheduling, and
+scheduling is [ice_cube]'s problem, not this library's.
+
 ## Precision
 
 A modern Julian Date is around 2.46 million. A single `Float` spends most of its
@@ -420,6 +579,8 @@ rooms and mailing lists is expected to follow the [code of conduct].
 
 [Bundler]: https://bundler.io
 [ERFA]: https://github.com/liberfa/erfa
+[ice_cube]: https://github.com/ice-cube-ruby/ice_cube
+[iers]: https://github.com/rhannequin/iers
 [CHANGELOG]: https://github.com/rhannequin/horologium/blob/main/CHANGELOG.md
 [rubygems.org]: https://rubygems.org
 [MIT License]: https://opensource.org/licenses/MIT

data/Rakefile

@@ -17,7 +17,7 @@ task :steep do
   sh "steep check"
 end
 
-desc "Verify YARD documentation coverage is 100%"
+desc "Verify YARD documentation coverage is 100% and parses without warning"
 task :yard_coverage do
   require "open3"
   output, status = Open3.capture2e("yard", "stats", "--list-undoc")
@@ -25,6 +25,18 @@ task :yard_coverage do
   unless status.success? && output.include?("100.00% documented")
     abort "YARD documentation coverage is below 100%"
   end
+
+  # Coverage counts a comment block, not the method it belongs to, so a block
+  # that landed above the wrong method still reads as documented while the
+  # method it was written for reads as documented too. The warnings are what
+  # notice: a @param naming a parameter the method does not have is a block
+  # that has come adrift.
+  warnings, = Open3.capture2e("yard", "--no-output")
+  lines = warnings.lines.grep(/\[warn\]/)
+  next if lines.empty?
+
+  puts lines
+  abort "YARD parsed #{lines.length} warning(s)"
 end
 
 task default: %i[test rubocop]

data/lib/horologium/configuration.rb

@@ -13,7 +13,11 @@ module Horologium
       tai: Scales::TAI,
       tt: Scales::TT,
       tdb: Scales::TDB,
-      utc: Scales::UTC
+      tcg: Scales::TCG,
+      tcb: Scales::TCB,
+      gps: Scales::GPS,
+      utc: Scales::UTC,
+      ut1: Scales::UT1
     }.freeze
 
     # @return [Symbol] the default precision, +:standard+ until configured
@@ -22,6 +26,9 @@ module Horologium
     # The recognised ways to handle a leap second past the data's horizon.
     LEAP_SECOND_HORIZONS = %i[extrapolate raise].freeze
 
+    # The recognised ways to handle a UT1 reading past the data's horizon.
+    UT1_HORIZONS = %i[extrapolate raise].freeze
+
     # The source UTC reads its leap seconds from. It answers +tai_utc_at+ with
     # TAI - UTC at a point in UTC, given a Julian Day Number: a day's 0h for a
     # whole number, or part way through a day where a fraction is added, which
@@ -33,6 +40,23 @@ module Horologium
     # @return [#tai_utc_at]
     attr_reader :leap_second_source
 
+    # The source UT1 reads delta T, TT - UT1, from. It answers +delta_t_at+
+    # with the seconds at a Julian Date, and +provenance_at+ with how that
+    # value was arrived at. {Data::Eop}, over the iers gem, is the default; a
+    # caller with its own Earth orientation data can set another here.
+    #
+    # @return [#delta_t_at]
+    attr_reader :eop_source
+
+    # What UT1 does with a date past the point the Earth orientation data
+    # reaches. +:extrapolate+, the default, reads it with the last published
+    # delta T and marks the reading +:extrapolated+. +:raise+ refuses it with
+    # {OutOfDataRangeError}, for a pipeline that must not lean on a value the
+    # next bulletin could revise.
+    #
+    # @return [Symbol] +:extrapolate+ or +:raise+
+    attr_reader :ut1_horizon
+
     # What UTC does with a date past the point the leap second data vouches
     # for. +:extrapolate+, the default, reads it in UTC with the last known
     # offset and marks the reading +:extrapolated+. +:raise+ refuses it with
@@ -45,6 +69,8 @@ module Horologium
     def initialize
       @default_precision = :standard
       @scales = BUILT_IN_SCALES.dup
+      @eop_source = Data::Eop
+      @ut1_horizon = :extrapolate
       @leap_second_source = Data::LeapSeconds
       @leap_second_horizon = :extrapolate
     end
@@ -93,6 +119,32 @@ module Horologium
       @leap_second_source = source
     end
 
+    # Sets the source UT1 reads delta T from. A source that does not answer
+    # both +delta_t_at+ and +provenance_at+ is refused here, at configuration
+    # time, rather than when an instant is first read in UT1.
+    #
+    # @param source [#delta_t_at] the source to read from
+    # @return [#delta_t_at] the source that was set
+    # @raise [ConfigurationError] once the configuration is frozen, or when
+    #   the source does not answer both methods
+    def eop_source=(source)
+      if frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      missing = %i[delta_t_at provenance_at].reject do |method|
+        source.respond_to?(method)
+      end
+
+      unless missing.empty?
+        raise ConfigurationError,
+          "an Earth orientation source must respond to " \
+          "#{missing.join(" and ")}, got #{source.inspect}"
+      end
+
+      @eop_source = source
+    end
+
     # Sets how UTC handles a date past the leap second data's horizon.
     #
     # @param horizon [Symbol] +:extrapolate+ or +:raise+
@@ -113,6 +165,26 @@ module Horologium
       @leap_second_horizon = horizon
     end
 
+    # Sets how UT1 handles a date past the Earth orientation data's horizon.
+    #
+    # @param horizon [Symbol] +:extrapolate+ or +:raise+
+    # @return [Symbol] the horizon that was set
+    # @raise [ConfigurationError] once the configuration is frozen, or when
+    #   the horizon is not recognised
+    def ut1_horizon=(horizon)
+      if frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      unless UT1_HORIZONS.include?(horizon)
+        raise ConfigurationError,
+          "ut1_horizon must be one of #{UT1_HORIZONS.join(", ")}, " \
+          "got #{horizon.inspect}"
+      end
+
+      @ut1_horizon = horizon
+    end
+
     # Registers a time scale under a name, so an instant can be read in it
     # with {Instant#to}. The scale is a class implementing {Scales::Base}: it
     # says how to read TAI in the scale, and how to read the scale back in

data/lib/horologium/data/eop.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "iers"
+
+module Horologium
+  module Data
+    # The Earth orientation data, from the iers gem. {Scales::UT1} reads this
+    # to convert between UT1 and the continuous scales, and it is the default
+    # source. A caller with its own data, a frozen bulletin or an alternative
+    # feed, can put another source in its place through
+    # {Configuration#eop_source}, as long as it answers {delta_t_at} and
+    # {provenance_at}.
+    #
+    # The quantity is delta T, TT - UT1, in SI seconds. It is not a constant
+    # and not a model: the Earth's rotation is irregular, so delta T is
+    # measured and published, and where the measurements do not reach it is
+    # estimated from a polynomial fit to eclipse records and old observations.
+    module Eop
+      # The days between a Julian Date and a Modified Julian Date, the shape
+      # iers reads. Unlike {LeapSeconds}, which asks for a day and gets a
+      # value that steps at its 0h, delta T is interpolated, so the fraction
+      # of the day is kept and this is the plain offset rather than one that
+      # also lands on midnight.
+      #
+      # @api private
+      MJD_OFFSET = 2_400_000.5
+
+      class << self
+        # TT - UT1 in SI seconds at a point in time, given as a Julian Date.
+        #
+        # The Julian Date is read in UTC where UTC is defined, because that is
+        # what the published series is tabulated against; {Scales::UT1} is
+        # what decides that and passes the right one. The value is
+        # interpolated between daily entries, so a fraction of a day counts.
+        #
+        # @param julian_date [Float] the Julian Date to read at
+        # @return [Float] TT - UT1 in seconds
+        # @raise [IERS::OutOfRangeError] where neither source reaches the
+        #   date: before the polynomial starts in 1800, and after the
+        #   published series ends, the two together covering everything in
+        #   between
+        def delta_t_at(julian_date)
+          IERS::DeltaT.at(mjd: julian_date - MJD_OFFSET).delta_t
+        end
+
+        # The Julian Date the published series vouches through, its last
+        # entry. Past it there is no delta T to read, and {Scales::UT1} holds
+        # the last one rather than refusing, the way UTC holds the last leap
+        # second offset. It is nil when the series is empty and there is no
+        # horizon to speak of.
+        #
+        # Written to be total rather than guarded: iers treats a finals file
+        # that parses to no rows as a series covering nothing, and +last(1)+
+        # carries that through as nil without a branch no bundled data can
+        # reach.
+        #
+        # @return [Float, nil] the Julian Date of the last entry, or nil where
+        #   the series has no entries and there is no horizon to report
+        def covers_until
+          IERS::Data.finals_entries
+            .last(1)
+            .map { |entry| entry.mjd + MJD_OFFSET }
+            .first
+        end
+
+        # How the delta T at a point was arrived at. +:measured+ where the
+        # published series observed it, +:extrapolated+ where the series
+        # predicts it, and +:estimated+ where the series does not reach and
+        # the polynomial fit answers instead.
+        #
+        # Which of the two answered is asked of iers rather than worked out
+        # from a date here, because the seam sits wherever the loaded series
+        # happens to start and moves when that data is replaced.
+        #
+        # It is read only when it is asked for, not on every reading, so the
+        # conversion pays for one lookup rather than two.
+        #
+        # @param julian_date [Float] the Julian Date to read at
+        # @return [Symbol] +:measured+, +:extrapolated+ or +:estimated+
+        # @raise [IERS::OutOfRangeError] where delta T is not available
+        def provenance_at(julian_date)
+          mjd = julian_date - MJD_OFFSET
+          return :estimated unless IERS::DeltaT.at(mjd: mjd).measured?
+
+          case IERS::UT1.at(mjd: mjd).data_quality
+          when :predicted then :extrapolated
+          else :measured
+          end
+        end
+      end
+    end
+  end
+end