carray 3.0.0 → 3.0.2

data/lib/carray/time.rb

@@ -22,6 +22,60 @@
 # Within a group any pair is an exact integer ratio (coarse = fine * N), so a
 # coarse->fine cast is lossless (multiply), and a fine->coarse cast is lossless
 # only when every value is divisible by the divisor.
+# Civil-date arithmetic on int64 CArrays: the calendar kernel every time
+# grid is built on (Howard Hinnant's days<->civil algorithms, vectorized).
+# Internal to the time surface: nothing here is part of the public API.
+module CATimeCivil
+  module_function
+
+  # Vectorized Howard Hinnant civil-date algebra (proleptic Gregorian,
+  # negative days supported).  days since the Unix epoch -> [year, month,
+  # day] int64 CArrays.  The algorithm needs the era to floor toward the
+  # past, which CArray `/` does; Hinnant's published form pre-biases the
+  # negative operand instead because C truncates.
+  def civil_from_days(z)
+    z   = z + 719468
+    era = z / 146097
+    doe = z - era * 146097
+    yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365
+    y   = yoe + era * 400
+    doy = doe - (365 * yoe + yoe / 4 - yoe / 100)
+    mp  = (5 * doy + 2) / 153
+    d   = doy - (153 * mp + 2) / 5 + 1       # day of month, 1..31
+    m   = mp + (3 - 12 * mp.ge(10))          # mp<10 ? +3 : -9
+    [y + m.le(2), m, d]
+  end
+
+  # [year, month, day] int64 CArrays -> days since the Unix epoch.
+  def days_from_civil(y, m, d)
+    y   = y - m.le(2)
+    era = y / 400
+    yoe = y - era * 400
+    doy = (153 * (m + (9 - 12 * m.gt(2))) + 2) / 5 + (d - 1)  # m>2 ? -3 : +9
+    doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
+    era * 146097 + doe - 719468
+  end
+
+  # Same algebra for one date, on plain Integers.  A literal is parsed one
+  # at a time, and routing each one through the vectorized form costs a
+  # one-cell CArray and a kernel call per literal -- which is where nearly
+  # all the time in a bulk column parse used to go (170k rows: 3.5 s, of
+  # which 3.1 s was this).  Ruby's Integer `/` floors, as CArray's does,
+  # so the two forms read alike and agree everywhere.
+  def days_from_civil_1 (y, m, d)
+    y  -= 1 if m <= 2
+    era = y / 400
+    yoe = y - era * 400
+    doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + (d - 1)
+    doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
+    era * 146097 + doe - 719468
+  end
+end
+
+# Unit algebra for the time surface: how two units relate (same group, which
+# is finer, what a difference is measured in) and how a tick count moves
+# between them -- by scaling for a duration, on the calendar for an instant.
+# Internal to the time surface: nothing here is part of the public API.
 module CATimeUnitAlgebra
   # seconds per base unit (Rational)
   FIXED = {
@@ -71,6 +125,8 @@ module CATimeUnitAlgebra
     g  = rgcd(a.tick_ratio, b.tick_ratio)
     CATime::Resolution.new(Integer(g / base_ratio(fb)), fb)
   end
+  # Alias of {#common}, used where the caller reads the result as "the finer
+  # of the two grids" rather than "the grid they share".
   alias_method :finer, :common
   module_function :finer
 
@@ -78,7 +134,10 @@ module CATimeUnitAlgebra
   # grid; cross-group -> the fixed-group resolution (a :M/:Y difference only
   # arises from two calendar operands), coarsened to `(1,:D)` when the fixed
   # side is a week (a week is not calendar-alignable, but both sides convert
-  # into days exactly).
+  # into days exactly).  :W is the only such coarsening: a fixed resolution
+  # whose tick does not tile a day (e.g. "7 hours") is returned as-is, and
+  # the calendar side then fails to convert into it, so the subtraction
+  # raises downstream rather than being silently coarsened.
   def diff_unit(u1, u2)
     a = res(u1); b = res(u2)
     return common(a, b) if same_group?(a, b)
@@ -124,19 +183,21 @@ module CATimeUnitAlgebra
   # instant / duration.  Checks the extremes (they bound every element), then
   # multiplies.  Shared by every coarse->fine conversion (arithmetic,
   # comparison, search).
+  #
+  # min / max skip masked cells, so a masked cell does not decide the range:
+  # it carries no value to convert, and whatever bits sit under the mask are
+  # not a time.  They answer UNDEF when there is nothing to bound (empty, or
+  # every cell masked), and then there is nothing to guard either.
   def widen(storage, factor)
     return storage if factor == 1
-    if storage.elements > 0
-      raw = storage.has_mask? ? storage.value : storage
-      lo  = raw.min
-      unless lo == UNDEF
-        lim = 2**63 - 1
-        [lo, raw.max].each do |x|
-          next if (Integer(x) * factor).abs <= lim
-          raise RangeError,
-                "time unit conversion overflows int64: the time range is " \
-                "too wide to widen into this resolution (x#{factor})"
-        end
+    lo = storage.min
+    unless lo == UNDEF
+      lim = 2**63 - 1
+      [lo, storage.max].each do |x|
+        next if (Integer(x) * factor).abs <= lim
+        raise RangeError,
+              "time unit conversion overflows int64: the time range is " \
+              "too wide to widen into this resolution (x#{factor})"
       end
     end
     storage * factor
@@ -157,25 +218,24 @@ module CATimeUnitAlgebra
             "(:Y/:M) and fixed-length units (:W/:D/:h/:s/...) have no fixed " \
             "ratio (a month / year is calendar-variable)"
     end
-    if r.denominator == 1
-      widen(storage, r.numerator)           # coarse -> fine: lossless multiply
-    else
-      divisor = r.denominator               # fine -> coarse: exact only
-      unless (storage % divisor).eq(0).all
-        raise ArgumentError,
-              "cannot scale duration #{a} to #{b} without loss: " \
-              "some values are not a whole multiple of #{b} " \
-              "(finer resolution would be truncated)"
-      end
-      storage / divisor
+    scaled = widen(storage, r.numerator)    # coarse -> fine: lossless multiply
+    return scaled if r.denominator == 1
+    unless (scaled % r.denominator).eq(0).all
+      raise ArgumentError,
+            "cannot scale duration #{a} to #{b} without loss: " \
+            "some values are not a whole multiple of #{b} " \
+            "(finer resolution would be truncated)"
     end
+    scaled / r.denominator
   end
 
   # SCALE conversion with truncation: like convert_scale! but a fine->coarse
   # conversion drops the sub-`to` remainder (truncating toward zero) instead of
-  # raising.  Used for dt +/- td, where the result keeps the time's unit
-  # and a finer duration is truncated to it (a :D time + a 5 h duration is
-  # + 0 days; + 30 h is + 1 day).  Cross-group still raises (a calendar
+  # raising.  A duration is a magnitude, so it shrinks toward zero rather than
+  # flooring toward the past the way an instant does.  Used by
+  # CATimedelta#to_unit and by dt +/- td, where the result keeps the time's
+  # unit and a finer duration is truncated to it (a :D time + a 5 h duration
+  # is + 0 days; + 30 h is + 1 day).  Cross-group still raises (a calendar
   # duration has no fixed ratio to a fixed unit).
   def convert_scale_trunc(storage, from, to)
     a = res(from); b = res(to)
@@ -183,10 +243,20 @@ module CATimeUnitAlgebra
     r = ratio(a, b)
     if r.nil?
       raise ArgumentError,
-            "cannot combine a #{a} duration with a #{b} time across the " \
-            "calendar/fixed boundary (a calendar duration has no fixed ratio)"
+            "cannot scale duration #{a} to #{b}: calendar units " \
+            "(:Y/:M) and fixed-length units (:W/:D/:h/:s/...) have no fixed " \
+            "ratio (a month / year is calendar-variable)"
     end
-    r.denominator == 1 ? widen(storage, r.numerator) : storage / r.denominator
+    scaled = widen(storage, r.numerator)
+    r.denominator == 1 ? scaled : trunc_divide(scaled, r.denominator)
+  end
+
+  # Truncating integer division of an int64 CArray (toward zero).  CArray
+  # `/` floors toward the past, which is what an instant wants; a duration
+  # is a magnitude and shrinks toward zero instead.
+  def trunc_divide(a, b)
+    q = a / b
+    q + (q.lt(0) & (a - q * b).ne(0))
   end
 
   # INSTANT conversion (absolute datetimes): unlike a duration, a time :M
@@ -203,23 +273,23 @@ module CATimeUnitAlgebra
     return storage if a == b
     return convert_scale!(storage, a, b) if ratio(a, b)   # same group
     if CALENDAR.key?(a.base)
-      _instant_cal_to_fixed(storage, a, b)                # widen
+      convert_instant_calendar_to_fixed(storage, a, b)   # widen
     else
-      _instant_fixed_to_cal(storage, a, b)                # coarsen (exact-or-raise)
+      convert_instant_fixed_to_calendar(storage, a, b)   # coarsen (exact-or-raise)
     end
   end
 
   # calendar time (Resolution `from`) -> days since the epoch (int64
   # CArray).  Folds the resolution count (value = count-Y/M buckets).
-  def _cal_days(storage, from)
+  def calendar_days_since_epoch(storage, from)
     ones = CArray.int64(*storage.shape) { 1 }
     if from.base == :M
       abs = storage * from.count + 1970 * 12           # absolute month ordinal
-      y   = CATime.send(:_floordiv_i, abs, 12)
+      y   = abs / 12
       m   = abs - y * 12 + 1
-      CATime.send(:_days_from_civil, y, m, ones)
+      CATimeCivil.days_from_civil(y, m, ones)
     else                                               # :Y
-      CATime.send(:_days_from_civil, storage * from.count + 1970, ones, ones)
+      CATimeCivil.days_from_civil(storage * from.count + 1970, ones, ones)
     end
   end
 
@@ -227,21 +297,21 @@ module CATimeUnitAlgebra
   # convert_instant!.  Goes through the day count, so the target grid has
   # to tile a day exactly (:W is rejected -- month starts are not
   # week-aligned).  Always exact once that holds.
-  def _instant_cal_to_fixed(storage, from, to)
+  def convert_instant_calendar_to_fixed(storage, from, to)
     r = ratio(CATime::Resolution.new(1, :D), to)   # ticks of `to` per day
     unless r.denominator == 1
       raise ArgumentError,
             "cannot convert calendar time #{from} to #{to} " \
             "(a day boundary is not aligned to the #{to} grid)"
     end
-    widen(_cal_days(storage, from), r.numerator)
+    widen(calendar_days_since_epoch(storage, from), r.numerator)
   end
 
   # fixed-length grid -> calendar time: the coarsening half of
   # convert_instant!, exact-or-raise.  Every instant must land on a day
   # boundary and then on the calendar boundary itself (the 1st, and
   # January too for :Y), since a mid-month instant has no :M value.
-  def _instant_fixed_to_cal(storage, from, to)
+  def convert_instant_fixed_to_calendar(storage, from, to)
     rd = ratio(CATime::Resolution.new(1, :D), from)  # `from` ticks per day
     days =
       if rd.denominator == 1
@@ -255,7 +325,7 @@ module CATimeUnitAlgebra
       else                                             # coarser than a day (:W)
         storage * (from.tick_ratio / 86400r).to_i
       end
-    y, m, d = CATime.send(:_civil_from_days, days)
+    y, m, d = CATimeCivil.civil_from_days(days)
     on_boundary = d.eq(1)
     on_boundary &= m.eq(1) if to.base == :Y
     unless on_boundary.all
@@ -270,10 +340,49 @@ module CATimeUnitAlgebra
               "cannot convert time #{from} to #{to} without loss " \
               "(instant is not on a #{to} boundary)"
       end
-      ord = CATime.send(:_floordiv_i, ord, to.count)
+      ord = ord / to.count
     end
     ord
   end
+
+  # INSTANT conversion that floors instead of raising: the storage-resolution
+  # change behind CATime#to_unit.  A coarser target keeps the bucket the
+  # instant falls in (floor toward the past, the direction construction and
+  # `floor` already use), so no element is rejected for sitting off the
+  # target grid -- a resolution change is a cast, not an assertion.  The
+  # widening half is untouched and stays exact, and :Y/:M -> :W still raises
+  # (a month head is not week-aligned, so widening there would move the
+  # instant).
+  def convert_instant_floor(storage, from, to)
+    a = res(from); b = res(to)
+    return storage if a == b
+    r = ratio(a, b)
+    if r                                                # same group
+      scaled = widen(storage, r.numerator)
+      r.denominator == 1 ? scaled
+                         : scaled / r.denominator
+    elsif CALENDAR.key?(a.base)
+      convert_instant_calendar_to_fixed(storage, a, b)   # widen, always exact
+    else
+      convert_instant_fixed_to_calendar_floor(storage, a, b)
+    end
+  end
+
+  # fixed-length grid -> calendar time, flooring: the instant's own year /
+  # month, whatever day and time it carries.  The flooring counterpart of
+  # convert_instant_fixed_to_calendar.
+  def convert_instant_fixed_to_calendar_floor(storage, from, to)
+    rd   = ratio(CATime::Resolution.new(1, :D), from)   # `from` ticks per day
+    days =
+      if rd.denominator == 1
+        storage / rd.numerator
+      else                                             # coarser than a day (:W)
+        storage * (from.tick_ratio / 86400r).to_i
+      end
+    y, m, = CATimeCivil.civil_from_days(days)
+    ord = to.base == :M ? (y * 12 + (m - 1) - 1970 * 12) : (y - 1970)
+    to.count > 1 ? ord / to.count : ord
+  end
 end
 
 class CATime
@@ -332,8 +441,8 @@ class CATime
       require 'time'
       require 'date'
       case unit.base
-      when :Y then d = _epoch_date.next_year(value * unit.count);  Time.utc(d.year, d.month, d.day)
-      when :M then d = _epoch_date.next_month(value * unit.count); Time.utc(d.year, d.month, d.day)
+      when :Y then d = epoch_date.next_year(value * unit.count);  Time.utc(d.year, d.month, d.day)
+      when :M then d = epoch_date.next_month(value * unit.count); Time.utc(d.year, d.month, d.day)
       else
         Time.at(Rational(value) * unit.tick_ratio, in: 'UTC')  # exact seconds
       end
@@ -344,11 +453,11 @@ class CATime
     def to_date
       require 'date'
       case unit.base
-      when :Y then _epoch_date.next_year(value * unit.count)
-      when :M then _epoch_date.next_month(value * unit.count)
+      when :Y then epoch_date.next_year(value * unit.count)
+      when :M then epoch_date.next_month(value * unit.count)
       when :W then Date.jd(EPOCH_JD + value * unit.count * 7, Date::GREGORIAN)
       when :D then Date.jd(EPOCH_JD + value * unit.count, Date::GREGORIAN)
-      else         Date.jd(EPOCH_JD + _floor_days, Date::GREGORIAN)  # sub-day: floor to day
+      else         Date.jd(EPOCH_JD + floor_to_days_since_epoch, Date::GREGORIAN)  # sub-day: floor to day
       end
     end
 
@@ -366,7 +475,7 @@ class CATime
       when :Y      then format("%04d", to_date.year)
       when :M      then to_date.strftime("%Y-%m")
       when :W, :D  then to_date.strftime("%Y-%m-%d")
-      else              to_time.iso8601(_precision_digits)  # :h .. :as (time shown)
+      else              to_time.iso8601(fractional_second_digits)  # :h .. :as (time shown)
       end
     end
 
@@ -386,7 +495,7 @@ class CATime
       case other
       when Element
         u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
-        _instant_in(u) <=> other._instant_in(u)
+        instant_in(u) <=> other.instant_in(u)
       when Time
         to_time <=> other.getutc
       when (defined?(DateTime) ? DateTime : nil)
@@ -409,16 +518,19 @@ class CATime
     end
 
     # @overload +(td)
-    #   Returns this instant advanced by a {CATimedelta::Element}.  The unit
-    #   promotes to the finer of the two (numpy-style: :D + :h -> :h).  Only a
-    #   duration in the SAME group (both calendar or both fixed) is accepted --
-    #   a cross-group step (a :s time + a :M duration) is calendar
-    #   arithmetic; use `to_date` + `Date#next_month` / `#next_year` for that.
+    #   Returns this instant advanced by a {CATimedelta::Element}.  The time
+    #   is the anchor: the result keeps `self`'s unit and the duration is
+    #   converted into it, truncated toward zero when finer (a :D time + a
+    #   5 h duration is + 0 days; + 30 h is + 1 day) -- the same rule as the
+    #   array {CATime#+}.  Only a duration in the SAME group (both calendar
+    #   or both fixed) is accepted -- a cross-group step (a :s time + a :M
+    #   duration) is calendar arithmetic; use `to_date` +
+    #   `Date#next_month` / `#next_year` for that.
     #   @param td [CATimedelta::Element]
     #   @return [CATime::Element]
     #   @raise [TypeError, ArgumentError] on a non-timedelta / cross-group operand.
     def +(td)
-      _combine(td, 1)
+      shifted_by_duration(td, 1)
     end
 
     # @overload -(other)
@@ -432,9 +544,9 @@ class CATime
       case other
       when Element
         u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
-        CATimedelta::Element.new(_instant_in(u) - other.send(:_instant_in, u), u)
+        CATimedelta::Element.new(instant_in(u) - other.instant_in(u), u)
       when CATimedelta::Element
-        _combine(other, -1)
+        shifted_by_duration(other, -1)
       else
         raise TypeError, "CATime::Element - #{other.class} is not allowed"
       end
@@ -444,7 +556,7 @@ class CATime
 
     # This instant's storage value expressed in `to` unit (exact; raises if the
     # instant does not land on `to`'s grid).
-    def _instant_in(to)
+    def instant_in(to)
       return value if to == unit
       CATimeUnitAlgebra.convert_instant!(CA_INT64([value]), unit, to)[0]
     end
@@ -454,7 +566,7 @@ class CATime
     # s +/- td: the time is the anchor, so the result keeps self's unit and
     # the duration is converted into it (truncated toward zero when finer; a
     # cross-group calendar duration raises).  Mirrors the array CATime +/-.
-    def _combine(td, sign)
+    def shifted_by_duration(td, sign)
       unless td.is_a?(CATimedelta::Element)
         raise TypeError,
               "CATime::Element #{sign > 0 ? '+' : '-'} #{td.class} is not " \
@@ -467,18 +579,18 @@ class CATime
     # Base epoch as a Date.  next_month / next_year clamp end-of-month
     # (Jan 31 -> Feb 28), but the base is day 1, so no clamping ever occurs --
     # do not move the base off the first of the month without revisiting.
-    def _epoch_date
+    def epoch_date
       require 'date'
       Date.new(1970, 1, 1, Date::GREGORIAN)  # proleptic Gregorian, matching to_time
     end
 
     # Days since the epoch for a fixed sub-day unit (floored toward the past).
-    def _floor_days
+    def floor_to_days_since_epoch
       sec = Rational(value) * unit.tick_ratio             # exact seconds
       (sec / 86400).floor
     end
 
-    def _precision_digits
+    def fractional_second_digits
       case unit.base
       when :ms                then 3
       when :us                then 6
@@ -560,7 +672,7 @@ class CATimedelta
       return nil unless other.is_a?(Element)
       return nil unless CATimeUnitAlgebra.same_group?(unit, other.unit)
       u = CATimeUnitAlgebra.finer(unit, other.unit)
-      _scale_in(u) <=> other._scale_in(u)
+      duration_in(u) <=> other.duration_in(u)
     rescue ArgumentError
       nil
     end
@@ -580,13 +692,13 @@ class CATimedelta
     #   raises.
     #   @param other [CATimedelta::Element]
     #   @return [CATimedelta::Element]
-    def +(other) = _combine(other, 1)
+    def +(other) = combined_with_duration(other, 1)
 
     # @overload -(other)
     #   Returns the difference of two durations (finer unit; cross-group raises).
     #   @param other [CATimedelta::Element]
     #   @return [CATimedelta::Element]
-    def -(other) = _combine(other, -1)
+    def -(other) = combined_with_duration(other, -1)
 
     # @overload *(n)
     #   Returns this duration scaled by an Integer.
@@ -598,17 +710,20 @@ class CATimedelta
     end
 
     # @overload /(other)
-    #   By an Integer -> a scaled {CATimedelta::Element}; by another
+    #   By an Integer -> a scaled {CATimedelta::Element}, the quotient
+    #   truncated toward zero (a duration is a magnitude, so it shrinks
+    #   toward zero -- the same direction {CATimedelta#/} and #to_unit
+    #   take, not Ruby Integer division's floor); by another
     #   {CATimedelta::Element} -> their dimensionless ratio as a `Rational`
     #   (both brought to the finer unit; cross-group raises).
     #   @param other [Integer, CATimedelta::Element]
     #   @return [CATimedelta::Element, Rational]
     def /(other)
       case other
-      when Integer then Element.new(value / other, unit)
+      when Integer then Element.new(Rational(value, other).truncate, unit)
       when Element
         u = CATimeUnitAlgebra.finer(unit, other.unit)
-        Rational(_scale_in(u), other.send(:_scale_in, u))
+        Rational(duration_in(u), other.duration_in(u))
       else
         raise TypeError, "CATimedelta::Element / #{other.class} is not allowed"
       end
@@ -618,20 +733,20 @@ class CATimedelta
 
     # This duration's value expressed in `to` unit (exact scale; raises on a
     # cross-group or non-whole conversion).
-    def _scale_in(to)
+    def duration_in(to)
       return value if to == unit
       CATimeUnitAlgebra.convert_scale!(CA_INT64([value]), unit, to)[0]
     end
 
     private
 
-    def _combine(other, sign)
+    def combined_with_duration(other, sign)
       unless other.is_a?(Element)
         raise TypeError,
               "CATimedelta::Element #{sign > 0 ? '+' : '-'} #{other.class} is not allowed"
       end
       u = CATimeUnitAlgebra.finer(unit, other.unit)
-      Element.new(_scale_in(u) + sign * other.send(:_scale_in, u), u)
+      Element.new(duration_in(u) + sign * other.duration_in(u), u)
     end
   end
 end
@@ -665,23 +780,33 @@ class CATime
   end
 
   # @overload to_unit(unit)
-  #   Returns the same instants re-expressed on a finer grid: a new
-  #   {CATime} whose storage is `self`'s ticks widened into `unit`.
-  #   Accepted only when `self`'s tick is a whole multiple of `unit`'s, so
-  #   every element lands exactly on the new grid and no instant moves
-  #   (`:D` -> `:h`, `"1 hour"` -> `"10 minutes"`, `:Y` -> `:M`).  A coarser
-  #   or partially-overlapping target raises rather than rounding silently;
-  #   use {#floor} / {#ceil} / {#round} to move to a coarser grid explicitly.
+  #   Returns the same instants re-expressed on the `unit` grid: a new
+  #   {CATime} whose storage resolution is `unit`.  Changing the resolution
+  #   is a cast, not an assertion -- the same relation `CArray.time` has to
+  #   its input:
+  #
+  #   - **Finer target** (`:D` -> `:h`, `:Y` -> `:M`, `:M` -> `:s`): exact.
+  #     Every instant lands on the new grid unchanged.
+  #   - **Coarser target** (`:h` -> `:D`, `:D` -> `:M`): each instant floors
+  #     to the head of the `unit` tick it falls in -- toward the past, so a
+  #     pre-epoch instant floors the same way a post-epoch one does.  Use
+  #     {#ceil} / {#round} first to land on a different boundary.
+  #
+  #   The calendar / fixed-length boundary is crossed by civil-date algebra,
+  #   not by a ratio: a `:M` value is a real instant (the month's first
+  #   midnight), so `:M` -> `:D` widens exactly and `:D` -> `:M` floors to
+  #   the containing month.  `:Y` / `:M` -> `:W` is the one refusal, since a
+  #   month head is not week-aligned and widening would move the instant.
+  #
+  #   A *duration* has no such conversion ({CATimedelta#to_unit} truncates
+  #   toward zero and refuses to cross the boundary at all).
   #   @param unit [Resolution, Symbol, String] target resolution.
   #   @return [CATime]
-  #   @raise [ArgumentError] when `self`'s tick is not a whole multiple of
-  #     `unit`'s (including any calendar / fixed-length pair, where no fixed
-  #     ratio exists).
+  #   @raise [ArgumentError] on `:Y` / `:M` -> `:W`.
   #   @raise [RangeError] when the widened ticks overflow int64.
   def to_unit(unit)
     to = CATime::Resolution.parse(unit)
-    CATimeUnitAlgebra.widen(parent,
-                            CATimeUnitAlgebra.multiple_factor(self.unit, to)).time(unit: to)
+    CATimeUnitAlgebra.convert_instant_floor(parent, self.unit, to).time(unit: to)
   end
 
   # @overload +(other)
@@ -754,17 +879,17 @@ class CATime
   #   @return [Array(Element, Element), Array(CATime, CATime)]
   def minmax(*args, **opts)
     lo, hi = parent.minmax(*args, **opts)
-    [_lift_extremum(lo), _lift_extremum(hi)]
+    [relift_extremum(lo), relift_extremum(hi)]
   end
 
-  def _lift_extremum(r)
+  def relift_extremum(r)
     case r
     when Integer then Element.new(r, unit)
     when CArray  then r.time(unit: unit)
     else r
     end
   end
-  private :_lift_extremum
+  private :relift_extremum
 
   # The centroid / spread / order reductions report on the array's own grid:
   # they run on the storage ticks and round the result back to the nearest
@@ -778,7 +903,7 @@ class CATime
   #   nearest tick.
   #   @return [Element, CATime]
   def mean(*args, **opts)
-    _reduce_dt(:mean, :time, args, opts)
+    reduce_on_own_grid(:mean, :time, args, opts)
   end
 
   # @overload median(axis: nil, **opts)
@@ -787,7 +912,7 @@ class CATime
   #   cases interpolate and round to the nearest tick.
   #   @return [Element, CATime]
   def median(*args, **opts)
-    _reduce_dt(:median, :time, args, opts)
+    reduce_on_own_grid(:median, :time, args, opts)
   end
 
   # @overload percentile(*p, axis: nil, **opts)
@@ -797,7 +922,7 @@ class CATime
   #   Array of those.
   #   @return [Element, CATime, Array<Element>, Array<CATime>]
   def percentile(*args, **opts)
-    _reduce_dt(:percentile, :time, args, opts)
+    reduce_on_own_grid(:percentile, :time, args, opts)
   end
 
   # @overload quantile(axis: nil, **opts)
@@ -805,7 +930,7 @@ class CATime
   #   `self`'s unit (shorthand for `percentile(0, 25, 50, 75, 100)`).
   #   @return [Array<Element>, Array<CATime>]
   def quantile(*args, **opts)
-    _reduce_dt(:quantile, :time, args, opts)
+    reduce_on_own_grid(:quantile, :time, args, opts)
   end
 
   # @overload stddev(axis: nil, **opts)
@@ -815,7 +940,7 @@ class CATime
   #   `t.to_unit(:h).stddev` when the precision matters (§8).
   #   @return [CATimedelta::Element, CATimedelta]
   def stddev(*args, **opts)
-    _reduce_dt(:stddev, :timedelta, args, opts)
+    reduce_on_own_grid(:stddev, :timedelta, args, opts)
   end
 
   # @overload stddevp(axis: nil, **opts)
@@ -823,7 +948,7 @@ class CATime
   #   as {#stddev}.
   #   @return [CATimedelta::Element, CATimedelta]
   def stddevp(*args, **opts)
-    _reduce_dt(:stddevp, :timedelta, args, opts)
+    reduce_on_own_grid(:stddevp, :timedelta, args, opts)
   end
 
   # @overload sum(*)
@@ -989,7 +1114,7 @@ class CATime
       f = unit.tick_ratio                        # exact seconds / tick (Rational)
       parent.convert(:object) {|v| Time.at(v * f, in: 'UTC')}
     else                                         # calendar: exact granule midnight
-      (_field_days * 86400).convert(:object) {|v| Time.at(v, in: 'UTC')}
+      (days_since_epoch * 86400).convert(:object) {|v| Time.at(v, in: 'UTC')}
     end
   end
 
@@ -1001,7 +1126,7 @@ class CATime
   def to_date
     require 'date'
     # 2440588 = JD of 1970-01-01; proleptic Gregorian to match to_time and the field accessors.
-    _field_days.convert(:object) {|d| Date.jd(2440588 + d, Date::GREGORIAN)}
+    days_since_epoch.convert(:object) {|d| Date.jd(2440588 + d, Date::GREGORIAN)}
   end
 
   # @overload to_datetime
@@ -1024,8 +1149,8 @@ class CATime
   def year
     case unit.base
     when :Y then parent * unit.count + 1970
-    when :M then self.class.send(:_floordiv_i, parent * unit.count + 1970 * 12, 12)
-    else self.class.send(:_civil_from_days, _field_days)[0]
+    when :M then (parent * unit.count + 1970 * 12) / 12
+    else CATimeCivil.civil_from_days(days_since_epoch)[0]
     end
   end
 
@@ -1037,8 +1162,8 @@ class CATime
     when :Y then parent * 0 + 1
     when :M
       mo = parent * unit.count + 1970 * 12
-      mo - self.class.send(:_floordiv_i, mo, 12) * 12 + 1
-    else self.class.send(:_civil_from_days, _field_days)[1]
+      mo % 12 + 1
+    else CATimeCivil.civil_from_days(days_since_epoch)[1]
     end
   end
 
@@ -1048,35 +1173,35 @@ class CATime
   def day
     case unit.base
     when :Y, :M then parent * 0 + 1
-    else self.class.send(:_civil_from_days, _field_days)[2]
+    else CATimeCivil.civil_from_days(days_since_epoch)[2]
     end
   end
 
   # Hour of the day, 0..23; 0 when the storage unit is coarser than an hour.
   # @return [CArray] integer.
-  def hour;   _clock_field(:h); end
+  def hour;   clock_field(:h); end
   # Minute of the hour, 0..59; 0 when the storage unit is coarser than a minute.
   # @return [CArray] integer.
-  def minute; _clock_field(:m); end
+  def minute; clock_field(:m); end
   # Second of the minute, 0..59; 0 when the storage unit is coarser than a second.
   # @return [CArray] integer.
-  def second; _clock_field(:s); end
+  def second; clock_field(:s); end
 
   # Day of the week, Sunday = 0 .. Saturday = 6.
   # @return [CArray] integer.
   def weekday
     # 1970-01-01 is a Thursday (wday 4); Sun=0..Sat=6.
-    n = _field_days + 4
-    n - self.class.send(:_floordiv_i, n, 7) * 7          # floor-mod 7
+    n = days_since_epoch + 4
+    n % 7
   end
 
   # Day of the year, 1..366.
   # @return [CArray] integer.
   def yday
-    d    = _field_days
-    y    = self.class.send(:_civil_from_days, d)[0]
+    d    = days_since_epoch
+    y    = CATimeCivil.civil_from_days(d)[0]
     ones = CArray.int64(*shape) { 1 }
-    d - self.class.send(:_days_from_civil, y, ones, ones) + 1
+    d - CATimeCivil.days_from_civil(y, ones, ones) + 1
   end
   # @!endgroup
 
@@ -1122,14 +1247,14 @@ class CATime
   # calendar unit that means the month / year ordinal, so a :M centroid is
   # the centroid of month numbers (a caller wanting the day-space answer
   # writes to_unit(:D) first) -- and the result is rounded back to a tick.
-  def _reduce_dt(op, kind, args, opts)
-    _lift_reduced(parent.send(op, *args, **opts), kind)
+  def reduce_on_own_grid(op, kind, args, opts)
+    round_and_relift(parent.public_send(op, *args, **opts), kind)
   end
 
   # Round-to-nearest onto the storage grid, then wear the Face again.  An
   # Array arrives from the multi-p percentile / quantile shapes; UNDEF and
   # nil (empty or all-masked) pass through untouched.
-  def _lift_reduced(r, kind)
+  def round_and_relift(r, kind)
     case r
     when Numeric
       v = r.round
@@ -1142,7 +1267,7 @@ class CATime
       iv = r.round.mask_invalid.int64
       kind == :timedelta ? iv.timedelta(unit: unit) : iv.time(unit: unit)
     when Array
-      r.map {|x| _lift_reduced(x, kind)}
+      r.map {|x| round_and_relift(x, kind)}
     else
       r    # UNDEF / nil passthrough (empty or all-masked reduction)
     end
@@ -1168,21 +1293,25 @@ class CATimedelta
   end
 
   # @overload to_unit(unit)
-  #   Returns the same durations re-expressed on a finer grid: a new
-  #   {CATimedelta} whose storage is `self`'s ticks widened into `unit`.
-  #   Accepted only when `self`'s tick is a whole multiple of `unit`'s
-  #   (`:D` -> `:h`, `"1 hour"` -> `"10 minutes"`), so no duration changes.
-  #   A coarser target raises rather than truncating silently; a calendar /
-  #   fixed-length pair raises because a month has no fixed length.
+  #   Returns the same durations re-expressed on the `unit` grid: a new
+  #   {CATimedelta} whose storage resolution is `unit`.  A finer target is
+  #   exact (`:D` -> `:h`); a coarser one drops the sub-`unit` remainder
+  #   **toward zero** (`+30 h` -> `+1 D`, `-30 h` -> `-1 D`), the same
+  #   truncation `dt + td` already applies.
+  #
+  #   The direction differs from {CATime#to_unit} on purpose: a time is a
+  #   point on an axis, so it floors toward the past; a duration is a
+  #   magnitude, so it shrinks toward zero.
+  #
+  #   A calendar / fixed-length pair always raises -- unlike an instant, a
+  #   duration of one month has no length in days.
   #   @param unit [Resolution, Symbol, String] target resolution.
   #   @return [CATimedelta]
-  #   @raise [ArgumentError] when `self`'s tick is not a whole multiple of
-  #     `unit`'s.
+  #   @raise [ArgumentError] on a calendar / fixed-length pair.
   #   @raise [RangeError] when the widened ticks overflow int64.
   def to_unit(unit)
     to = CATime::Resolution.parse(unit)
-    CATimeUnitAlgebra.widen(parent,
-                            CATimeUnitAlgebra.multiple_factor(self.unit, to)).timedelta(unit: to)
+    CATimeUnitAlgebra.convert_scale_trunc(parent, self.unit, to).timedelta(unit: to)
   end
 
   # @overload +(other)
@@ -1195,7 +1324,7 @@ class CATimedelta
   def +(other)
     case other
     when CATimedelta
-      u = _finer_duration(other.unit)
+      u = common_duration_unit(other.unit)
       a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
       (a + b).timedelta(unit: u)
@@ -1215,7 +1344,7 @@ class CATimedelta
   def -(other)
     case other
     when CATimedelta
-      u = _finer_duration(other.unit)
+      u = common_duration_unit(other.unit)
       a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
       (a - b).timedelta(unit: u)
@@ -1260,11 +1389,13 @@ class CATimedelta
   #   @raise [TypeError] on incompatible operands.
   def /(other)
     case other
-    when Integer then (parent / other).timedelta(unit: unit)
+    when Integer
+      CATimeUnitAlgebra.trunc_divide(parent, other).timedelta(unit: unit)
     when CATimedelta
-      u = _finer_duration(other.unit)
-      CATimeUnitAlgebra.convert_scale!(parent, unit, u) /
-        CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
+      u = common_duration_unit(other.unit)
+      CATimeUnitAlgebra.trunc_divide(
+        CATimeUnitAlgebra.convert_scale!(parent, unit, u),
+        CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u))
     else raise TypeError, "CATimedelta / #{other.class} is not allowed"
     end
   end
@@ -1281,14 +1412,14 @@ class CATimedelta
   #   or as a {CATimedelta} view for per-axis reduction.
   #   @return [Element, CATimedelta]
   def sum(*args, **opts)
-    _lift_reduced(parent.sum(*args, **opts))
+    round_and_relift(parent.sum(*args, **opts))
   end
 
   # @overload mean(axis: nil, **opts)
   #   Returns the mean duration rounded to the nearest unit count.
   #   @return [Element, CATimedelta]
   def mean(*args, **opts)
-    _lift_reduced(parent.mean(*args, **opts))
+    round_and_relift(parent.mean(*args, **opts))
   end
 
   # median / percentile / quantile / stddev / stddevp report on this array's
@@ -1300,7 +1431,7 @@ class CATimedelta
   #   Returns the median duration on `self`'s unit.
   #   @return [Element, CATimedelta]
   def median(*args, **opts)
-    _lift_reduced(parent.median(*args, **opts))
+    round_and_relift(parent.median(*args, **opts))
   end
 
   # @overload percentile(*p, axis: nil, **opts)
@@ -1309,7 +1440,7 @@ class CATimedelta
   #   two or more give an Array).
   #   @return [Element, CATimedelta, Array<Element>, Array<CATimedelta>]
   def percentile(*args, **opts)
-    _lift_reduced(parent.percentile(*args, **opts))
+    round_and_relift(parent.percentile(*args, **opts))
   end
 
   # @overload quantile(axis: nil, **opts)
@@ -1317,7 +1448,7 @@ class CATimedelta
   #   `self`'s unit.
   #   @return [Array<Element>, Array<CATimedelta>]
   def quantile(*args, **opts)
-    _lift_reduced(parent.quantile(*args, **opts))
+    round_and_relift(parent.quantile(*args, **opts))
   end
 
   # @overload stddev(axis: nil, **opts)
@@ -1326,7 +1457,7 @@ class CATimedelta
   #   the precision matters.
   #   @return [Element, CATimedelta]
   def stddev(*args, **opts)
-    _lift_reduced(parent.stddev(*args, **opts))
+    round_and_relift(parent.stddev(*args, **opts))
   end
 
   # @overload stddevp(axis: nil, **opts)
@@ -1334,29 +1465,19 @@ class CATimedelta
   #   {#stddev}.
   #   @return [Element, CATimedelta]
   def stddevp(*args, **opts)
-    _lift_reduced(parent.stddevp(*args, **opts))
+    round_and_relift(parent.stddevp(*args, **opts))
   end
 
-  # variance / variancep are the one pair in this family that cannot carry a
-  # unit: their value is in squared ticks, and no Face represents squared
-  # time.  They are left as the inherited plain Float (unlike
-  # {CATime#variance}, which raises -- a squared instant is meaningless,
-  # while a squared duration is a real quantity, s^2).  Read the result as
-  # "in units of `self.unit` squared", or take {#stddev} for a typed answer.
-
-  def _lift_reduced(r)
+  def round_and_relift(r)
     case r
     when Numeric then Element.new(r.round, unit)
     when CArray  then r.round.mask_invalid.int64.timedelta(unit: unit)
-    when Array   then r.map {|x| _lift_reduced(x)}
+    when Array   then r.map {|x| round_and_relift(x)}
     else r
     end
   end
-  private :_lift_reduced
+  private :round_and_relift
 
-  # min / max ride the core reduce Face gate (ORDERABLE storage descent +
-  # output re-lift, see ext/mkkernel.rb face_gate: :relift); the inherited
-  # CArray#min / #max return the Element / CATimedelta shapes directly.
   # @overload variance(*)
   #   Not supported: the variance of durations has squared-time units, which
   #   no type represents -- the same reason {CATime#variance} refuses.  Use
@@ -1373,6 +1494,9 @@ class CATimedelta
     raise TypeError, "CATimedelta#variancep is ill-defined (squared-time units); use stddevp"
   end
 
+  # min / max ride the core reduce Face gate (ORDERABLE storage descent +
+  # output re-lift, see ext/mkkernel.rb face_gate: :relift); the inherited
+  # CArray#min / #max return the Element / CATimedelta shapes directly.
   # minmax has no core gate, so re-lift both extremes here.
 
   # @overload minmax(*axes, **opts)
@@ -1380,17 +1504,17 @@ class CATimedelta
   #   @return [Array(Element, Element), Array(CATimedelta, CATimedelta)]
   def minmax(*args, **opts)
     lo, hi = parent.minmax(*args, **opts)
-    [_lift_extremum(lo), _lift_extremum(hi)]
+    [relift_extremum(lo), relift_extremum(hi)]
   end
 
-  def _lift_extremum(r)
+  def relift_extremum(r)
     case r
     when Integer then Element.new(r, unit)
     when CArray  then r.timedelta(unit: unit)
     else r
     end
   end
-  private :_lift_extremum
+  private :relift_extremum
   # @!endgroup
 
   # sort / partition ride the core sort Face gate (ORDERABLE storage
@@ -1477,7 +1601,7 @@ class CATimedelta
   # The finer of `self`'s unit and `ou` for a duration + duration / ratio.  A
   # cross-group pair (a month vs a second) has no common duration grid, so it
   # raises rather than mixing calendar and fixed durations.
-  def _finer_duration(ou)
+  def common_duration_unit(ou)
     unless CATimeUnitAlgebra.same_group?(unit, ou)
       raise ArgumentError,
             "cannot combine a #{unit} duration with a #{ou} duration " \
@@ -1487,30 +1611,67 @@ class CATimedelta
   end
 end
 
-class CArray
-  # Time is stored as an int64 tick index on a grid whose resolution is
-  # `unit` (= a {CATime::Resolution}, tick = count * base).  The value
-  # is the k-th tick since the Unix epoch (1970-01-01 UTC): e.g. unit
-  # `"10 minutes"` value 3 = 1970-01-01T00:30:00Z.  All parsing is UTC (an
-  # explicit offset is honoured; otherwise UTC), DateTime-independent
-  # (Date._parse + civil kernel).
+# Reads a time literal (Time / DateTime / Integer unix-seconds / String) into
+# the pieces the CATime constructors need.  All parsing is UTC (an explicit
+# offset is honoured; otherwise UTC) and DateTime-independent (Date._parse +
+# a civil-date kernel).  Internal to the time surface: nothing here is part
+# of the public API.
+module CATimeLiteral
+  module_function
+
+  # Date fields of a String literal, UTC.  Ruby's Date._parse does not read
+  # the calendar-grid forms CATime#to_s prints -- "2019-09" comes back as a
+  # month of 20 with a zone, and a bare "2019" as a month and a day -- so
+  # those two are read here and everything else is left to Date._parse.
+  #
+  # What Date._parse returns is then checked, because an out-of-range field
+  # used to flow into the civil kernel and normalise into a different date:
+  # "201909" is a valid YYMMDD to Ruby (2020-19-09, which landed on 2021-07),
+  # and "2019-02-31" landed on 2019-03-03.  A missing finer field is not an
+  # error -- a year or a year-month names the head of that period.
+  def parse_date_fields(spec, format)
+    h =
+      if format                             then Date._strptime(spec, format)
+      elsif spec =~ /\A(\d{4})-(\d{1,2})\z/ then { year: $1.to_i, mon: $2.to_i }
+      elsif spec =~ /\A(\d{4})\z/           then { year: $1.to_i }
+      else                                       Date._parse(spec)
+      end
+    unless h && h[:year]
+      raise ArgumentError, "cannot parse time #{spec.inspect}"
+    end
+    y, m, d = h[:year], h[:mon] || 1, h[:mday] || 1
+    unless (1..12).cover?(m) && Date.valid_date?(y, m, d, Date::GREGORIAN)
+      raise ArgumentError,
+            "cannot parse time #{spec.inspect}: it reads as year #{y}, " \
+            "month #{m}, day #{d}, which is not a date"
+    end
+    h
+  end
+  private_class_method :parse_date_fields
 
   # Exact Rational seconds since the Unix epoch for a start literal (Time /
   # DateTime / Integer unix-seconds / String).  UTC default.
-  def self._epoch_seconds_exact(spec, format = nil)
+  def epoch_seconds(spec, format = nil)
     require 'date'
     require 'time'
     case spec
     when Time     then spec.to_r
     when Integer  then Rational(spec)
-    when String
-      h = format ? Date._strptime(spec, format) : Date._parse(spec)
-      unless h && h[:year] && h[:mon] && h[:mday]
-        raise ArgumentError, "cannot parse time #{spec.inspect}"
+    when CATime::Element
+      # A time element is already an instant, so it needs no parsing: a
+      # fixed unit counts seconds directly, and a calendar one names the
+      # first midnight of its granule (the same instant convert_instant!
+      # gives it).  This is what lets floor / ceil / to_unit output feed
+      # straight back into time_range / time_series / .time.
+      if CATimeUnitAlgebra::FIXED.key?(spec.unit.base)
+        Rational(spec.value) * spec.unit.tick_ratio
+      else
+        Rational(CATimeUnitAlgebra.calendar_days_since_epoch(CA_INT64([spec.value]),
+                                             spec.unit)[0] * 86400)
       end
-      days = CATime.send(:_days_from_civil,
-                               CA_INT64([h[:year]]), CA_INT64([h[:mon]]),
-                               CA_INT64([h[:mday]]))[0]
+    when String
+      h = parse_date_fields(spec, format)
+      days = CATimeCivil.days_from_civil_1(h[:year], h[:mon] || 1, h[:mday] || 1)
       sec  = Rational(days * 86400 + (h[:hour] || 0) * 3600 +
                       (h[:min] || 0) * 60 + (h[:sec] || 0))
       sec += h[:sec_fraction] if h[:sec_fraction]
@@ -1526,17 +1687,25 @@ class CArray
   end
 
   # [year, month] (UTC) of a start literal, for a calendar-resolution grid.
-  def self._epoch_year_month(spec, format = nil)
+  def year_month(spec, format = nil)
     require 'date'
     require 'time'
     case spec
     when Time    then t = spec.utc; [t.year, t.month]
     when Integer then t = Time.at(spec, in: 'UTC'); [t.year, t.month]
-    when String
-      h = format ? Date._strptime(spec, format) : Date._parse(spec)
-      unless h && h[:year]
-        raise ArgumentError, "cannot parse time #{spec.inspect}"
+    when CATime::Element
+      # A calendar element is a month ordinal already, so read it as one
+      # rather than going out through Time (which a :Y / :M element would
+      # have to re-derive).  Integer / and % floor, so a pre-epoch value
+      # lands in the right month.
+      case spec.unit.base
+      when :M then mo = spec.value * spec.unit.count + 1970 * 12
+                   [mo / 12, mo % 12 + 1]
+      when :Y then [spec.value * spec.unit.count + 1970, 1]
+      else         t = spec.to_time.utc; [t.year, t.month]
       end
+    when String
+      h = parse_date_fields(spec, format)
       [h[:year], h[:mon] || 1]
     else
       if defined?(DateTime) && spec.is_a?(DateTime)
@@ -1548,16 +1717,37 @@ class CArray
   end
 
   # Tick index of `spec`'s instant on the `res` grid (floor toward the past).
-  def self._epoch_tick_index(spec, res, format = nil)
+  def tick_index(spec, res, format = nil)
     if CATimeUnitAlgebra::FIXED.key?(res.base)
-      (_epoch_seconds_exact(spec, format) / res.tick_ratio).floor
+      (epoch_seconds(spec, format) / res.tick_ratio).floor
     else
-      y, m    = _epoch_year_month(spec, format)
+      y, m    = year_month(spec, format)
       months  = (y - 1970) * 12 + (m - 1)
       (Rational(months) / res.tick_ratio).floor
     end
   end
 
+  # Single-literal build for {.time}: a 1-element CATime, honouring
+  # the on_error policy (raise, or a masked cell).
+  def to_time_array(literal, res, format, on_error)
+    raw = CArray.int64(1)
+    begin
+      raw[0] = tick_index(literal, res, format)
+    rescue ArgumentError, TypeError
+      raise if on_error == :raise
+      raw[0] = UNDEF
+    end
+    raw.time(unit: res)
+  end
+end
+
+class CArray
+  # Time is stored as an int64 tick index on a grid whose resolution is
+  # `unit` (= a {CATime::Resolution}, tick = count * base).  The value
+  # is the k-th tick since the Unix epoch (1970-01-01 UTC): e.g. unit
+  # `"10 minutes"` value 3 = 1970-01-01T00:30:00Z.  Literals are read by
+  # {CATimeLiteral} (UTC).
+
   # @overload time_range(start, last, unit:, step: nil, format: nil)
   #   Returns a {CATime} from `start` to `last` inclusive on the `unit`
   #   grid, spaced `step` apart.  `unit` is the resolution the result is
@@ -1567,8 +1757,10 @@ class CArray
   #   bucket head (toward the past); the phase is anchored at `start`, and
   #   `last` is a bound rather than a member -- the series stops at the last
   #   step at or before it.
-  #   @param start [Time, String, Integer, DateTime] first instant.
-  #   @param last [Time, String, Integer, DateTime] last instant (inclusive).
+  #   @param start [Time, String, Integer, DateTime, CATime::Element] first
+  #     instant.
+  #   @param last [Time, String, Integer, DateTime, CATime::Element] last
+  #     instant (inclusive).
   #   @param unit [Resolution, Symbol, String] grid resolution (tick).
   #   @param step [Resolution, Symbol, String, nil] spacing between elements
   #     (default: one `unit` tick).  Must be a whole multiple of `unit`.
@@ -1581,8 +1773,8 @@ class CArray
     res    = CATime::Resolution.parse(unit)
     stride = step.nil? ? 1 :
                CATimeUnitAlgebra.multiple_factor(CATime::Resolution.parse(step), res)
-    s = _epoch_tick_index(start, res, format)
-    e = _epoch_tick_index(last,  res, format)
+    s = CATimeLiteral.tick_index(start, res, format)
+    e = CATimeLiteral.tick_index(last,  res, format)
     n = e < s ? 0 : (e - s) / stride + 1
     CArray.int64(n) {|i| s + i * stride }.time(unit: res)
   end
@@ -1593,7 +1785,8 @@ class CArray
   #   is stored on and `step` is the spacing, so an hourly grid sampled once
   #   a day is `unit: :h, step: "1 day"`.  With no `step` the spacing is one
   #   `unit` tick (consecutive ticks, as before).
-  #   @param start [Time, String, Integer, DateTime] first instant.
+  #   @param start [Time, String, Integer, DateTime, CATime::Element] first
+  #     instant.
   #   @param count [Integer] number of elements.
   #   @param unit [Resolution, Symbol, String] grid resolution (tick).
   #   @param step [Resolution, Symbol, String, nil] spacing between elements
@@ -1607,7 +1800,7 @@ class CArray
     res    = CATime::Resolution.parse(unit)
     stride = step.nil? ? 1 :
                CATimeUnitAlgebra.multiple_factor(CATime::Resolution.parse(step), res)
-    s = _epoch_tick_index(start, res, format)
+    s = CATimeLiteral.tick_index(start, res, format)
     CArray.int64(count) {|i| s + i * stride }.time(unit: res)
   end
 
@@ -1622,7 +1815,7 @@ class CArray
   #   pass `on_error: :mask` to make it an UNDEF cell instead.  A masked /
   #   `nil` input cell is a *missing* value (not a parse failure) and always
   #   becomes UNDEF, regardless of `on_error`.
-  #   @param x [Time, String, Integer, DateTime, Array, CArray] a literal, a
+  #   @param x [Time, String, Integer, DateTime, CATime::Element, Array, CArray] a literal, a
   #     Ruby Array of literals, or a CArray of literals.
   #   @param unit [Resolution, Symbol, String] target grid resolution.
   #   @param format [String, nil] optional strptime format for String input.
@@ -1641,7 +1834,7 @@ class CArray
     end
     x = CA_OBJECT(x) if x.is_a?(Array)   # Ruby Array of literals -> object CArray
     unless x.is_a?(CArray)
-      return _time_cell(x, res, format, on_error)
+      return CATimeLiteral.to_time_array(x, res, format, on_error)
     end
     raw = CArray.int64(*x.shape)
     x.each_index do |*idx|
@@ -1651,7 +1844,7 @@ class CArray
         next
       end
       begin
-        raw[*idx] = _epoch_tick_index(s, res, format)
+        raw[*idx] = CATimeLiteral.tick_index(s, res, format)
       rescue ArgumentError, TypeError
         raise if on_error == :raise
         raw[*idx] = UNDEF        # opt-in parse-mask
@@ -1660,19 +1853,6 @@ class CArray
     raw.time(unit: res)
   end
 
-  # Single-literal build for {.time}: a 1-element CATime, honouring
-  # the on_error policy (raise, or a masked cell).
-  def self._time_cell(literal, res, format, on_error)
-    raw = CArray.int64(1)
-    begin
-      raw[0] = _epoch_tick_index(literal, res, format)
-    rescue ArgumentError, TypeError
-      raise if on_error == :raise
-      raw[0] = UNDEF
-    end
-    raw.time(unit: res)
-  end
-
   # @overload time(unit: :ns, origin: nil)
   #   Returns `self` as a {CATime} on the `unit` grid.  With `origin`
   #   nil, `self`'s int64 values are taken as tick indices already anchored
@@ -1680,7 +1860,7 @@ class CArray
   #   indices are relative to `origin` and are rebased to the epoch (a new
   #   int64 array is built; the origin is not stored).
   #   @param unit [Resolution, Symbol, String] grid resolution.
-  #   @param origin [Time, String, Integer, DateTime, nil] base instant that
+  #   @param origin [Time, String, Integer, DateTime, CATime::Element, nil] base instant that
   #     `self`'s indices are counted from (default: the Unix epoch).
   #   @return [CATime]
   #   @note An `int64` receiver is wrapped zero-copy.  A narrower integer type
@@ -1688,11 +1868,11 @@ class CArray
   #     raises (cast it explicitly if the truncation is intended).
   def time(unit: :ns, origin: nil)
     res = CATime::Resolution.parse(unit)
-    src = _time_int64_storage
+    src = as_int64_time_storage
     if origin.nil?
       CATime.wrap(src, unit: res)
     else
-      o = CArray._epoch_tick_index(origin, res)
+      o = CATimeLiteral.tick_index(origin, res)
       (src + o).time(unit: res)
     end
   end
@@ -1705,13 +1885,13 @@ class CArray
   #   @note An `int64` receiver is wrapped zero-copy; a narrower integer type
   #     is widened to `int64` first (a copy); a `Float` / non-integer raises.
   def timedelta(unit: :ns)
-    CATimedelta.wrap(_time_int64_storage, unit: unit)
+    CATimedelta.wrap(as_int64_time_storage, unit: unit)
   end
 
   # Coerce the receiver to the int64 storage a time / timedelta Face needs:
   # int64 passes through (zero-copy), a narrower integer type widens losslessly
   # to int64 (a copy), and any non-integer (Float, boolean, object, ...) raises.
-  def _time_int64_storage
+  def as_int64_time_storage
     return self if data_type == CA_INT64
     unless integer?
       raise TypeError,
@@ -1721,7 +1901,7 @@ class CArray
     end
     int64
   end
-  private :_time_int64_storage
+  private :as_int64_time_storage
 end
 
 # ============================================================================
@@ -1740,6 +1920,198 @@ end
 # See devel/PROPOSAL_DATETIME64_STEP_SYSTEM.md.
 # ============================================================================
 
+# Places a bucket grid on a storage resolution: resolves a timestep into whole
+# storage ticks, resolves an origin into a tick count (or a month ordinal on
+# the calendar path), and guards both against int64 overflow.  Internal to the
+# time surface: nothing here is part of the public API.
+module CATimeGrid
+  module_function
+
+  # Base units that are day-or-finer (a period head is representable exactly;
+  # the civil path targets these for a calendar bucket).
+  SU_LE_DAY = %i[D h m s ms us ns ps fs as].freeze
+
+  # Smallest value an int64 storage tick can hold.
+  INT64_MIN = -(2**63)
+  # Largest value an int64 storage tick can hold.
+  INT64_MAX =  2**63 - 1
+
+  # Raise (rather than let an int64 CArray operand silently wrap) if a
+  # Ruby-domain quantity is out of int64 range.  Returns the value on success
+  # so it composes inline.
+  def check_int64_range(v, what)
+    if v < INT64_MIN || v > INT64_MAX
+      raise RangeError,
+            "time step: #{what} = #{v} overflows int64 " \
+            "(the storage unit is too fine for this step / origin / span; " \
+            "use a coarser unit)"
+    end
+    v
+  end
+
+  # Return [mul, step_ticks, origin_ticks] (all Integer) for the integer
+  # path -- step_ticks and origin_ticks in numerator ticks, the finer of
+  # the storage and step grids (see #resolve_timestep_grid).  The calendar path is
+  # handled by the caller.
+  def resolve_integer_grid(step_res, storage_res, origin)
+    mul, step_ticks = resolve_step_scale(step_res, storage_res)
+    [mul, step_ticks, resolve_origin_ticks(origin, step_res,
+                                            mul == 1 ? storage_res : step_res)]
+  end
+
+  # Storage ticks per day of `storage_res` (must be a whole number, else the
+  # storage grid does not tile a day -- a calendar bucket is unrepresentable).
+  def ticks_per_day(storage_res)
+    r = CATimeUnitAlgebra.ratio(CATime::Resolution.new(1, :D), storage_res)
+    unless r.denominator == 1
+      raise ArgumentError,
+            "cannot place a calendar bucket on storage resolution " \
+            "#{storage_res} (its tick does not tile a day)"
+    end
+    check_int64_range(r.numerator, "ticks per day for #{storage_res}")
+  end
+
+  # Storage ticks of the bucket head at timestep `k` (int64 CArray) for a
+  # calendar bucket: ym0 + k*count months -> day 1 of that month -> ticks.
+  def calendar_bucket_head_ticks(k, st, storage_res, origin)
+    tpd   = ticks_per_day(storage_res)
+    count = st.count * (st.base == :Y ? 12 : 1)
+    ym0   = origin_month_ordinal(origin)
+    ymk   = ym0 + k * count
+    yy    = ymk / 12
+    mm    = ymk - yy * 12 + 1
+    CATimeCivil.days_from_civil(yy, mm, CArray.int64(*k.shape) { 1 }) * tpd
+  end
+
+  # Month ordinal (year*12 + month-1) of origin; day / time ignored.
+  # Default (nil) is the epoch month 1970-01.
+  def origin_month_ordinal(origin)
+    return 1970 * 12 if origin.nil?
+    y, m = check_calendar_origin(origin, nil)
+    y * 12 + (m - 1)
+  end
+
+  # [mul, step_ticks] for the integer path, or :civil (calendar bucket on
+  # day-or-finer storage), or raise.  Bucket arithmetic runs in the finer of
+  # the two grids, so exactly one of the pair is > 1:
+  #   - bucket at or coarser than the storage tick (a :h bucket on :s
+  #     storage) -> [1, N]: N storage ticks per bucket.
+  #   - bucket finer than the storage tick (a :h bucket on :D storage) ->
+  #     [N, 1]: one storage tick spans N buckets exactly, so a timestep is a
+  #     plain widening.  This needs the storage tick to be a *whole* multiple
+  #     of the bucket tick; a partial multiple ("90 minutes" storage against
+  #     an :h bucket) has no integer timestep and raises.
+  def resolve_step_scale(step_res, storage_res)
+    r = CATimeUnitAlgebra.ratio(step_res, storage_res)  # storage ticks / step tick
+    if r
+      what = "bucket #{step_res} in ticks of #{storage_res}"
+      return [1, check_int64_range(r.numerator, what)] if r.denominator == 1
+      return [check_int64_range(r.denominator, what), 1] if r.numerator == 1
+    end
+    if CATimeUnitAlgebra::CALENDAR.key?(step_res.base) && SU_LE_DAY.include?(storage_res.base)
+      return :civil
+    end
+    raise ArgumentError,
+          "cannot express bucket #{step_res} on storage resolution #{storage_res} " \
+          "(neither is a whole multiple of the other)"
+  end
+
+  # origin -> integer tick count in storage ticks.  Default (nil) is the
+  # epoch, except a week bucket defaults to ISO Monday (1970-01-05).  A lossy
+  # conversion (origin not landing exactly on the storage grid) raises; a
+  # bare Integer is rejected (epoch-dependent, ambiguous).
+  def resolve_origin_ticks(origin, step_res, storage_res)
+    if origin.nil?
+      if step_res.base == :W && SU_LE_DAY.include?(storage_res.base)
+        return check_int64_range(ticks_per_day(storage_res) * 4,
+                      "ISO-Monday week origin in ticks of #{storage_res}")
+      end
+      return 0
+    end
+    if CATimeUnitAlgebra::FIXED.key?(storage_res.base)
+      secs = origin_seconds_exact(origin)
+      tick = secs / storage_res.tick_ratio               # Rational
+      unless tick.denominator == 1
+        raise ArgumentError,
+              "origin #{origin.inspect} is not representable losslessly " \
+              "in storage resolution #{storage_res} (would truncate the grid phase)"
+      end
+      check_int64_range(tick.numerator, "origin #{origin.inspect} in ticks of #{storage_res}")
+    else                                                 # :Y / :M storage
+      y, m = check_calendar_origin(origin, storage_res)
+      ord  = storage_res.base == :Y ? (y - 1970) : (y * 12 + (m - 1) - 1970 * 12)
+      if storage_res.count > 1
+        unless (ord % storage_res.count).zero?
+          raise ArgumentError,
+                "origin #{origin.inspect} is not on the #{storage_res} grid"
+        end
+        ord /= storage_res.count
+      end
+      ord
+    end
+  end
+
+  # Exact Rational seconds since the Unix epoch for a fixed-storage origin.
+  # Everything but a bare Integer goes through the shared entry point, so
+  # an origin reads the same here as it does for a start literal.
+  def origin_seconds_exact(origin)
+    case origin
+    when Integer
+      raise ArgumentError,
+            "origin: a bare Integer is ambiguous (epoch-dependent); pass a " \
+            "Time / String / CATime scalar"
+    else
+      CATimeLiteral.epoch_seconds(origin)  # Time / String / DateTime / Element
+    end
+  end
+
+  # Whether `origin` sits exactly on the head of its month (the 1st at
+  # 00:00 UTC).  A calendar grid is addressed by month ordinal, so its
+  # bucket heads are month heads and nothing else; an origin anywhere in
+  # between names a bucket that does not exist.
+  def origin_on_month_head?(origin)
+    # A calendar element is a month head by construction, and the shared
+    # entry point says so by handing back that midnight -- no branch here
+    # has to know it.
+    secs = CATimeLiteral.epoch_seconds(origin)
+    y, m = origin_year_month(origin)
+    head = CATimeCivil.days_from_civil(CA_INT64([y]), CA_INT64([m]), CA_INT64([1]))[0]
+    secs == head * 86400
+  end
+
+  # Raise unless `origin` can be the head of bucket 0 on a calendar grid:
+  # it has to be a month head, and a :Y tick starts in January.  The day
+  # and time would otherwise be dropped silently -- the same loss a fixed
+  # unit already refuses (see resolve_origin_ticks).
+  def check_calendar_origin(origin, storage_res)
+    return if origin.nil?
+    y, m = origin_year_month(origin)
+    unless origin_on_month_head?(origin)
+      raise ArgumentError,
+            "origin #{origin.inspect} is not a month head: a calendar grid " \
+            "is addressed by month, so its origin must be the 1st at 00:00"
+    end
+    if storage_res && storage_res.base == :Y && m != 1
+      raise ArgumentError,
+            "origin #{origin.inspect} is not on the #{storage_res} grid " \
+            "(a #{storage_res} tick starts in January)"
+    end
+    [y, m]
+  end
+
+  # [year, month] of a calendar-storage origin (finer fields ignored).
+  def origin_year_month(origin)
+    case origin
+    when Integer
+      raise ArgumentError,
+            "origin: a bare Integer is ambiguous (epoch-dependent); pass a " \
+            "Time / String / CATime scalar"
+    else
+      CATimeLiteral.year_month(origin)  # Time / String / DateTime / Element
+    end
+  end
+end
+
 class CATime
   # A tick resolution: `count` ticks of a `base` unit.  The human surface is
   # a String ("3 hours" / "1 month"); a bare Symbol (:h) is the count-1
@@ -1802,9 +2174,10 @@ class CATime
 
     def initialize(count, base)
       raise ArgumentError, "unit count must be >= 1 (got #{count})" if count < 1
-      # calendar (Y/M) bases are month-ordinal linear, so only integer
-      # multiples are well-defined; a fractional multiple has no meaning.
-      # (count is already Integer here; the guard documents the rule.)
+      # Only integer multiples are well-defined (calendar Y/M bases are
+      # month-ordinal linear, so a fractional multiple has no meaning).
+      # Resolution.parse always hands in an Integer; a fractional count via
+      # a direct `new` is not guarded here.
       @count = count
       @base  = base
       freeze
@@ -1826,9 +2199,180 @@ class CATime
     def inspect = "#<CATime::Resolution #{count} #{base}>"
   end
 
-  # Base units that are day-or-finer (a period head is representable exactly;
-  # the civil path targets these for a calendar bucket).
-  SU_LE_DAY = %i[D h m s ms us ns ps fs as].freeze
+  # A tick resolution *and where its ticks are anchored*: the `(unit:,
+  # origin:)` pair that {#timesteps}, {#snap} and {.from_timesteps} already
+  # take, given a name and a value.
+  #
+  # {Resolution} says how wide a tick is; Grid says that and where tick 0
+  # starts.  A CATime is stored as epoch-anchored int64 either way, so this
+  # reifies a calling convention -- it does not add a second time
+  # representation, and the reference-time epoch stays out of storage.
+  #
+  #   g = CATime::Grid.parse("12 hours since 2017-11-30 09:00")
+  #   t.snap(g, direction: :floor)     # the pair, passed once
+  #   t.timesteps(g)                   # which tick each element falls in
+  #   g.at(CA_INT64([0, 1, 2]))        # and back
+  #
+  # Proleptic Gregorian, UTC.  There is no calendar seam here on purpose: a
+  # swappable calendar taxes every operation that touches a time, and the
+  # benefit does not follow.
+  class Grid
+
+    # udunits' origin-shift operators, all equivalent: the words `since`,
+    # `after`, `from`, `ref` (whitespace-separated) and the `@` sign, which
+    # needs none ("seconds@1970-01-01").  Generous on input because a
+    # `units` attribute is written by whoever wrote the file; {#to_s} only
+    # ever emits `since`, which is what CF-conforming files use.
+    ORIGIN_SHIFT = /\A(.+?)(?:\s+(?:since|after|from|ref)\s+|\s*@\s*)(.+)\z/i
+
+    # Plural unit words, the spelling {Resolution.parse} reads back.  (Bare
+    # Resolution#to_s does not round-trip: it prints "h" / "12 h", and
+    # Resolution.parse takes neither.)
+    WORD = { Y: "years", M: "months", W: "weeks", D: "days", h: "hours",
+             m: "minutes", s: "seconds", ms: "milliseconds",
+             us: "microseconds", ns: "nanoseconds", ps: "picoseconds",
+             fs: "femtoseconds", as: "attoseconds" }.freeze
+
+    # Storage resolutions to fall back on when the unit's own tick cannot
+    # hold the origin exactly (a day grid anchored at 12:00 needs seconds).
+    FALLBACK_BASES = %i[s ms us ns].freeze
+
+    # @param spec ["<unit> since <instant>", unit spec, Grid]
+    # @param origin [Time, String, DateTime, Element, nil] when `spec`
+    #   carries no origin-shift clause.
+    # @return [Grid]
+    def self.parse(spec, origin: nil)
+      return spec if spec.is_a?(Grid)
+      if spec.is_a?(String) and (fields = ORIGIN_SHIFT.match(spec))
+        new(fields[1], fields[2])
+      else
+        new(spec, origin)
+      end
+    end
+
+    # Normalizes the three ways a grid reaches a method -- positionally, as
+    # `unit:`, or as the loose `(unit:, origin:)` pair -- into that pair.
+    # One call at the head of a method is the whole Grid arm.
+    # @return [Array(Object, Object)] (unit, origin).
+    def self.resolve(grid, unit, origin)
+      return [grid.unit, grid.origin] if grid.is_a?(Grid)
+      return [unit.unit, unit.origin] if unit.is_a?(Grid)
+      unless grid.nil?
+        raise ArgumentError,
+              "the positional argument must be a CATime::Grid (got #{grid.class})"
+      end
+      [unit, origin]
+    end
+
+    def initialize(unit, origin = nil)
+      @unit    = Resolution.parse(unit)
+      @origin  = origin
+      @storage = resolve_storage
+      @origin  = CArray.time(origin, unit: @storage)[0] if origin
+      freeze
+    end
+
+    # @return [Resolution] the tick this grid counts in.
+    attr_reader :unit
+
+    # @return [Element, nil] the instant tick 0 starts at.  nil is the epoch,
+    #   which is what every `origin:` keyword already defaults to.
+    attr_reader :origin
+
+    # @return [Resolution] the resolution an array on this grid is stored on:
+    #   the unit itself, or finer when the origin's phase needs it.  Derived
+    #   from (unit, origin) and memoized here, so a grid's identity stays the
+    #   (count, unit, origin) triple.
+    attr_reader :storage
+
+    # @return [Boolean] whether the unit is a calendar one (:Y / :M), whose
+    #   ticks are month ordinals rather than a fixed number of seconds.
+    def calendar? = %i[Y M].include?(@unit.base)
+
+    # @return [Integer] storage ticks per unit tick.
+    def step_ticks = Integer(@unit.tick_ratio / @storage.tick_ratio)
+
+    # @return [Integer] storage ticks from the epoch to the origin.
+    def origin_ticks
+      @origin ? Integer(CATimeLiteral.epoch_seconds(@origin) / @storage.tick_ratio) : 0
+    end
+
+    # Tick indices -> instants: the {CATime.from_timesteps} direction, but
+    # answering on {#storage} so a phased origin survives.
+    # @param k [CArray, Integer]
+    # @return [CATime, Element]
+    def at(k)
+      return at(CArray.int64(1) { Integer(k) })[0] unless k.is_a?(CArray)
+      return CATime.from_timesteps(k.int64, unit: @unit, origin: @origin) if calendar?
+      (origin_ticks + k.int64 * step_ticks).time(unit: @storage)
+    end
+
+    # Instants -> tick indices: the {CATime#timesteps} direction.  Off-grid
+    # elements floor toward the past; ask {#on} when that would be a lie.
+    # @return [CArray] int64.
+    def index(time) = time.timesteps(self)
+
+    # @return [CArray] boolean, flagging elements that land on a tick.
+    def on(time) = time.is_righttime(self)
+
+    # @return [Boolean] whether every element lands on a tick.
+    def on?(time) = on(time).all
+
+    # A regular series on this grid.
+    def range(start, last) = CArray.time_range(start, last, unit: @storage, step: @unit)
+    # A regular series on this grid: +count+ elements from +start+, one per
+    # tick.
+    def series(start, count:) = CArray.time_series(start, count: count, unit: @storage, step: @unit)
+
+    # @return [String] "12 hours since 2017-11-30 09:00:00", which {.parse}
+    #   reads back into an equal grid.
+    def to_s
+      word = WORD.fetch(@unit.base)
+      spec = @unit.count == 1 ? word : "#{@unit.count} #{word}"
+      @origin ? "#{spec} since #{@origin.to_time.strftime('%Y-%m-%d %H:%M:%S')}" : spec
+    end
+
+    # @return [String] the {#to_s} spec, wrapped for the console.
+    def inspect = "#<CATime::Grid #{self}>"
+
+    # Two grids are equal when they place ticks in the same places: same
+    # timestep, same origin.
+    # @return [Boolean]
+    def ==(other) = other.is_a?(Grid) && other.unit == @unit && other.to_s == to_s
+    alias eql? ==
+
+    # Hashes with {#==}, so a grid works as a Hash key.
+    # @return [Integer]
+    def hash = [@unit, to_s].hash
+
+    private
+
+    # The coarsest storage holding both the unit's tick and the origin's
+    # phase without truncation.  A calendar grid is addressed by month, so
+    # its origin is already pinned to a month head and the unit serves.
+    def resolve_storage
+      return @unit if calendar?
+      candidates = [@unit, *FALLBACK_BASES.map {|base| Resolution.new(1, base) }]
+      candidates.each do |res|
+        next unless (@unit.tick_ratio / res.tick_ratio).denominator == 1
+        next unless @origin.nil? ||
+                    (CATimeLiteral.epoch_seconds(@origin) / res.tick_ratio).denominator == 1
+        return res
+      end
+      raise ArgumentError,
+            "origin #{@origin.inspect} cannot be held exactly on any storage " \
+            "resolution for unit #{@unit}"
+    end
+  end
+
+  # Rounding rules {#snap} accepts, the same three CArray#snap takes.
+  SNAP_DIRECTIONS = %i[round floor ceil].freeze
+
+  # The grid this array is stored on: its own tick, anchored at the epoch.
+  # `t.timesteps` is `t.timesteps(t.grid)`, which is what the `unit:` default
+  # has always meant.
+  # @return [Grid]
+  def grid = Grid.new(unit)
 
   # @overload timesteps(unit: self.unit, origin: nil)
   #   Returns the integer timestep of every element: the k-th `unit`-wide
@@ -1840,17 +2384,23 @@ class CATime
   #   {#ticks}, but a fresh array rather than the live storage).
   #   @param unit [String, Symbol, Resolution] bucket resolution
   #     (default: this array's own storage resolution).
-  #   @param origin [Time, String, CATime::Element, DateTime, nil] grid
-  #     phase (default: the Unix epoch, or ISO Monday for a week bucket).
+  #   @param origin [Time, String, CATime::Element, DateTime, nil] head of
+  #     bucket 0 (default: the Unix epoch, or ISO Monday for a week bucket
+  #     on day-or-finer storage -- a week grid counts from the epoch
+  #     Thursday and cannot hold a Monday, so it keeps its own ticks).
+  #     It has to be a bucket head itself: on a calendar grid, the 1st at
+  #     00:00.
   #   @return [CArray] int64 timesteps.
   #   @raise [ArgumentError] on a sub-resolution / unrepresentable (unit,
   #     storage-resolution) pair or a lossy origin.
-  def timesteps(unit: self.unit, origin: nil)
-    g = _step_grid(unit, origin)
-    return _civil(:index, g[1], origin) if g[0] == :civil
+  def timesteps(grid = nil, unit: nil, origin: nil)
+    unit, origin = Grid.resolve(grid, unit, origin)
+    unit = self.unit if unit.nil?
+    g = resolve_timestep_grid(unit, origin)
+    return calendar_bucket(:index, g[1], origin) if g[0] == :civil
     su, mul, step_ticks, o = g
-    _guard_overflow(su, mul, o)
-    d = _num_ticks(mul) - o
+    raise_if_int64_overflow(su, mul, o)
+    d = storage_ticks_in_numerator_grid(mul) - o
     q = d / step_ticks
     q - (d - q * step_ticks).lt(0)      # floor-div correction (%-independent)
   end
@@ -1859,54 +2409,83 @@ class CATime
   #   Returns each element floored to its bucket head (toward the past), as a
   #   {CATime} in the same storage resolution.
   #   @param unit [String, Symbol, Resolution] bucket resolution.
-  #   @param origin [Time, String, CATime::Element, DateTime, nil] grid phase.
+  #   @param origin [Time, String, CATime::Element, DateTime, nil] head of
+  #     bucket 0 (default: the Unix epoch, or ISO Monday for a week bucket
+  #     on day-or-finer storage -- a week grid counts from the epoch
+  #     Thursday and cannot hold a Monday, so it keeps its own ticks).
+  #     It has to be a bucket head itself: on a calendar grid, the 1st at
+  #     00:00.
+  #   @return [CATime]
+  # @overload snap(grid = nil, unit:, origin: nil, direction: :round)
+  #   Returns each element snapped to a point on the bucket grid, as a
+  #   {CATime} in the same storage resolution.  This is the time-domain twin
+  #   of {CArray#snap}: there, `(step, offset:, direction:)`; here a {Grid}
+  #   (= tick + origin), or the same pair spelled as `unit:` / `origin:`,
+  #   and the same three directions.
+  #
+  #   `:round` picks the nearest bucket head, ties toward the future;
+  #   `:floor` the head at or before; `:ceil` the head at or after.
+  #   {#floor}, {#ceil} and {#round} are this method with `direction:` fixed.
+  #   @param grid [Grid, nil] the bucket grid, passed as one value.
+  #   @param unit [String, Symbol, Resolution, Grid] bucket resolution.
+  #   @param origin [Time, String, CATime::Element, DateTime, nil] head of
+  #     bucket 0 (default: the Unix epoch, or ISO Monday for a week bucket
+  #     on day-or-finer storage -- a week grid counts from the epoch
+  #     Thursday and cannot hold a Monday, so it keeps its own ticks).
+  #     It has to be a bucket head itself: on a calendar grid, the 1st at
+  #     00:00.
+  #   @param direction [:round, :floor, :ceil] rounding rule.
   #   @return [CATime]
-  def floor(unit:, origin: nil)
-    g = _step_grid(unit, origin)
-    return _civil(:floor, g[1], origin) if g[0] == :civil
+  def snap(grid = nil, unit: nil, origin: nil, direction: :round)
+    unless SNAP_DIRECTIONS.include?(direction)
+      raise ArgumentError,
+            "snap: direction must be :round / :floor / :ceil " \
+            "(got #{direction.inspect})"
+    end
+    unit, origin = Grid.resolve(grid, unit, origin)
+    g = resolve_timestep_grid(unit, origin)
+    return calendar_bucket(direction, g[1], origin) if g[0] == :civil
     su, mul, step_ticks, o = g
-    _guard_overflow(su, mul, o, step_ticks, :floor)
-    d = _num_ticks(mul) - o
+    raise_if_int64_overflow(su, mul, o, step_ticks, direction)
+    n = storage_ticks_in_numerator_grid(mul)
+    d = n - o
     q = d / step_ticks
-    q = q - (d - q * step_ticks).lt(0)
-    _head_time(o + q * step_ticks, mul, su)
+    q = q - (d - q * step_ticks).lt(0)            # floor bucket
+    case direction
+    when :ceil
+      fl = o + q * step_ticks
+      return bucket_head_as_time(fl + step_ticks * n.ne(fl), mul, su)
+    when :round
+      r = d - q * step_ticks                      # 0 <= r < step_ticks
+      q = q + r.ge((step_ticks + 1) / 2)          # ties -> future; no 2*d / 2*r
+    end
+    bucket_head_as_time(o + q * step_ticks, mul, su)
   end
 
-  # @overload ceil(unit:, origin: nil)
-  #   Returns each element raised to its bucket head at or after it (an
-  #   element already on a boundary maps to itself), as a {CATime}.
+  # @overload floor(grid = nil, unit:, origin: nil)
+  #   {#snap} with `direction: :floor` -- each element at its bucket head
+  #   (toward the past), as a {CATime} in the same storage resolution.
   #   @return [CATime]
-  def ceil(unit:, origin: nil)
-    g = _step_grid(unit, origin)
-    return _civil(:ceil, g[1], origin) if g[0] == :civil
-    su, mul, step_ticks, o = g
-    _guard_overflow(su, mul, o, step_ticks, :ceil)
-    n  = _num_ticks(mul)
-    d  = n - o
-    q  = d / step_ticks
-    q  = q - (d - q * step_ticks).lt(0)
-    fl = o + q * step_ticks
-    _head_time(fl + step_ticks * n.ne(fl), mul, su)
-  end
-
-  # @overload round(unit:, origin: nil)
-  #   Returns each element rounded to its nearest bucket head (ties toward
-  #   the future, matching `snap` :round), as a {CATime}.  Exact for
-  #   odd `step_ticks` (no half-tick loss).  For a calendar bucket the nearest
-  #   head is by absolute tick distance (month lengths vary), ties toward the
-  #   future.
+  def floor(grid = nil, unit: nil, origin: nil)
+    snap(grid, unit: unit, origin: origin, direction: :floor)
+  end
+
+  # @overload ceil(grid = nil, unit:, origin: nil)
+  #   {#snap} with `direction: :ceil` -- each element at the bucket head at
+  #   or after it (an element already on a boundary maps to itself).
   #   @return [CATime]
-  def round(unit:, origin: nil)
-    g = _step_grid(unit, origin)
-    return _civil(:round, g[1], origin) if g[0] == :civil
-    su, mul, step_ticks, o = g
-    _guard_overflow(su, mul, o, step_ticks, :round)
-    d = _num_ticks(mul) - o
-    q = d / step_ticks
-    q = q - (d - q * step_ticks).lt(0)            # floor bucket
-    r = d - q * step_ticks                        # 0 <= r < step_ticks
-    q = q + r.ge((step_ticks + 1) / 2)            # ties -> future; no 2*d / 2*r
-    _head_time(o + q * step_ticks, mul, su)
+  def ceil(grid = nil, unit: nil, origin: nil)
+    snap(grid, unit: unit, origin: origin, direction: :ceil)
+  end
+
+  # @overload round(grid = nil, unit:, origin: nil)
+  #   {#snap} with `direction: :round` -- each element at its nearest bucket
+  #   head, ties toward the future.  Exact for odd `step_ticks` (no half-tick
+  #   loss).  For a calendar bucket the nearest head is by absolute tick
+  #   distance (month lengths vary), ties toward the future.
+  #   @return [CATime]
+  def round(grid = nil, unit: nil, origin: nil)
+    snap(grid, unit: unit, origin: origin, direction: :round)
   end
 
   # @overload is_righttime(unit:, origin: nil)
@@ -1914,33 +2493,57 @@ class CATime
   #   head.  Use as an assertion before matching to catch off-grid series (a
   #   timesteps match is "same bucket", not "same instant").
   #   @param unit [String, Symbol, Resolution] bucket resolution.
-  #   @param origin [Time, String, CATime::Element, DateTime, nil] grid phase.
+  #   @param origin [Time, String, CATime::Element, DateTime, nil] head of
+  #     bucket 0 (default: the Unix epoch, or ISO Monday for a week bucket
+  #     on day-or-finer storage -- a week grid counts from the epoch
+  #     Thursday and cannot hold a Monday, so it keeps its own ticks).
+  #     It has to be a bucket head itself: on a calendar grid, the 1st at
+  #     00:00.
   #   @return [CArray] boolean.
-  def is_righttime(unit:, origin: nil)
-    g = _step_grid(unit, origin)
-    return _civil(:on, g[1], origin) if g[0] == :civil
+  def is_righttime(grid = nil, unit: nil, origin: nil)
+    unit, origin = Grid.resolve(grid, unit, origin)
+    g = resolve_timestep_grid(unit, origin)
+    return calendar_bucket(:on, g[1], origin) if g[0] == :civil
     su, mul, step_ticks, o = g
-    _guard_overflow(su, mul, o)
-    d = _num_ticks(mul) - o
+    raise_if_int64_overflow(su, mul, o)
+    d = storage_ticks_in_numerator_grid(mul) - o
     q = d / step_ticks
     (d - q * step_ticks).eq(0)
   end
 
   # @overload from_timesteps(k, unit:, origin: nil)
   #   Inverse of {#timesteps}: returns the bucket-head time for timestep
-  #   `k`, stored on the `unit` grid.  Use to relabel a `group_by(timesteps)`
-  #   result, generate a regular grid, or as a timesteps round-trip oracle.
+  #   `k`.  Use to relabel a `group_by(timesteps)` result, generate a
+  #   regular grid, or as a timesteps round-trip oracle.
   #   A scalar `k` returns a {Element}; a CArray `k` returns a {CATime}.
+  #
+  #   The result is stored on the `unit` grid, except a week bucket, which
+  #   is stored on `:D`.  A week grid counts from the epoch (a Thursday) and
+  #   so cannot hold its own bucket head: the head is the ISO Monday, four
+  #   days off every week tick.  Days hold it exactly, so a `:W` bucket
+  #   answers on the day grid and the round trip against a day-or-finer
+  #   series is exact.  `unit:` names the bucket here, the way it does for
+  #   {#floor} / {#ceil} -- not the storage the answer lands on.
   #   @param k [Integer, CArray] timestep / timesteps.
-  #   @param unit [String, Symbol, Resolution] grid resolution of the result.
-  #   @param origin [Time, String, CATime::Element, DateTime, nil] grid phase.
-  #   @return [Element, CATime]
-  def self.from_timesteps(k, unit:, origin: nil)
+  #   @param unit [String, Symbol, Resolution] bucket resolution.
+  #   @param origin [Time, String, CATime::Element, DateTime, nil] head of
+  #     bucket 0 (default: the Unix epoch, or ISO Monday for a week bucket).
+  #     It has to be a bucket head itself: on a calendar grid, the 1st at
+  #     00:00.
+  #   @return [Element, CATime] on the `unit` grid (`:D` for a week bucket).
+  def self.from_timesteps(k, grid = nil, unit: nil, origin: nil)
+    grid = unit if unit.is_a?(Grid)
+    # A Grid answers on its own storage, so an origin off the unit grid
+    # ("12 hours since ... 09:00") survives; the keyword form keeps the
+    # narrower rule it always had, where the origin sits on the unit itself.
+    return grid.at(k) if grid.is_a?(Grid)
+    unit, origin = Grid.resolve(grid, unit, origin)
     res = Resolution.parse(unit)
+    out = res.base == :W ? Resolution.new(1, :D) : res
     kk  = k.is_a?(CArray) ? k.int64 : CArray.int64(1) { Integer(k) }
-    _mul, step_ticks, o = _resolve_grid(res, res, origin)  # step_ticks = 1 (same res)
+    _mul, step_ticks, o = CATimeGrid.resolve_integer_grid(res, out, origin)
     raw = o + kk * step_ticks
-    k.is_a?(CArray) ? raw.time(unit: res) : Element.new(raw[0], res)
+    k.is_a?(CArray) ? raw.time(unit: out) : Element.new(raw[0], out)
   end
 
   private
@@ -1952,19 +2555,19 @@ class CATime
   # per numerator tick) is 1 for a bucket at or coarser than the storage
   # tick, and the widening factor for a finer bucket.  `origin_ticks` is
   # likewise in numerator ticks.
-  def _step_grid(step, origin)
+  def resolve_timestep_grid(step, origin)
     storage_res = unit
     step_res    = Resolution.parse(step)
-    scale = self.class.send(:_resolve_step_scale, step_res, storage_res)
+    scale = CATimeGrid.resolve_step_scale(step_res, storage_res)
     return [:civil, step_res] if scale == :civil
     mul, step_ticks = scale
     num_res = mul == 1 ? storage_res : step_res
-    o = self.class.send(:_resolve_origin_ticks, origin, step_res, num_res)
+    o = CATimeGrid.resolve_origin_ticks(origin, step_res, num_res)
     [storage_res, mul, step_ticks, o]
   end
 
-  # Storage ticks lifted into the numerator grid (see {#_step_grid}).
-  def _num_ticks(mul)
+  # Storage ticks lifted into the numerator grid (see {#resolve_timestep_grid}).
+  def storage_ticks_in_numerator_grid(mul)
     mul == 1 ? parent : CATimeUnitAlgebra.widen(parent, mul)
   end
 
@@ -1972,7 +2575,7 @@ class CATime
   # storage resolution.  The division is exact: a numerator grid finer than
   # the storage tick only arises when every element already sits on it, so
   # each head is a whole number of storage ticks.
-  def _head_time(head, mul, su)
+  def bucket_head_as_time(head, mul, su)
     (mul == 1 ? head : head / mul).time(unit: su)
   end
 
@@ -1993,20 +2596,24 @@ class CATime
   # widened (`mul` > 1) grid, where a coarse storage unit is lifted into a
   # much finer one; a pathological raw value wrapped in a coarse-unit Face is
   # not guarded (the gate is a value-range heuristic, not a proof).
-  def _guard_overflow(su, mul, o, step_ticks = nil, kind = nil)
+  #
+  # min / max skip masked cells, so a masked cell does not decide the range
+  # (it carries no time), and answer UNDEF when there is nothing to bound --
+  # an empty array, or one whose every cell is masked.
+  def raise_if_int64_overflow(su, mul, o, step_ticks = nil, kind = nil)
     return unless mul > 1 or FINE_UNITS.include?(su.base)
-    return if parent.elements == 0
-    raw = parent.has_mask? ? parent.value : parent
-    lo  = Integer(raw.min) * mul
-    hi  = Integer(raw.max) * mul
-    chk = ->(v, w) { self.class.send(:_chk64, v, w) }
+    min = parent.min
+    return if min == UNDEF
+    lo  = Integer(min) * mul
+    hi  = Integer(parent.max) * mul
+    chk = ->(v, w) { CATimeGrid.check_int64_range(v, w) }
     chk.(lo, "ticks in bucket resolution")
     chk.(hi, "ticks in bucket resolution")
     chk.(lo - o, "parent - origin")
     chk.(hi - o, "parent - origin")
     if kind
-      chk.(_bucket_head(lo, o, step_ticks, kind), "bucket head")
-      chk.(_bucket_head(hi, o, step_ticks, kind), "bucket head")
+      chk.(bucket_head_ticks(lo, o, step_ticks, kind), "bucket head")
+      chk.(bucket_head_ticks(hi, o, step_ticks, kind), "bucket head")
     end
   end
 
@@ -2014,7 +2621,7 @@ class CATime
   # scalar mirror of the array floor / ceil / round, used only by the overflow
   # guard.  Ruby Integer `/` and `%` floor, so `(v - o) / s` is the floor
   # bucket directly.
-  def _bucket_head(v, o, s, kind)
+  def bucket_head_ticks(v, o, s, kind)
     fq = (v - o) / s
     case kind
     when :floor then o + fq * s
@@ -2026,27 +2633,27 @@ class CATime
   # Days since the Unix epoch of the date each element represents (mask
   # propagates).  Calendar units (:Y / :M) resolve to day 1 of their year /
   # month; a week is 7 days; day-or-finer units floor to the day.
-  def _field_days
+  def days_since_epoch
     res = unit
     case res.base
     when :Y
       ones = CArray.int64(*shape) { 1 }
-      self.class.send(:_days_from_civil, parent * res.count + 1970, ones, ones)
+      CATimeCivil.days_from_civil(parent * res.count + 1970, ones, ones)
     when :M
       mo = parent * res.count + 1970 * 12
-      y  = self.class.send(:_floordiv_i, mo, 12)
+      y  = mo / 12
       m  = mo - y * 12 + 1
-      self.class.send(:_days_from_civil, y, m, CArray.int64(*shape) { 1 })
+      CATimeCivil.days_from_civil(y, m, CArray.int64(*shape) { 1 })
     when :W then parent * res.count * 7
     when :D then parent * res.count
     else                                                   # fixed sub-day storage
       day = CATime::Resolution.new(1, :D)
       r   = CATimeUnitAlgebra.ratio(day, res)          # storage ticks per day
       if r.denominator == 1
-        self.class.send(:_floordiv_i, parent, r.numerator)
+        parent / r.numerator
       else                                                 # non-day-aligned tick
         tr = res.tick_ratio                                # seconds / tick
-        self.class.send(:_floordiv_i, parent * tr.numerator, 86400 * tr.denominator)
+        parent * tr.numerator / (86400 * tr.denominator)
       end
     end
   end
@@ -2057,13 +2664,13 @@ class CATime
   # coarser than `fu` both resolve exactly (a 10-minute grid gives minute 0 /
   # 10 / 20 / ...; a day grid collapses hour / minute / second to 0).  A
   # calendar-storage element has no intra-day field, so it collapses to 0.
-  def _clock_field(fu)
+  def clock_field(fu)
     r = CATimeUnitAlgebra.ratio(unit, CATime::Resolution.new(1, fu))  # fu ticks / storage tick
     return parent * 0 if r.nil?                            # calendar storage: no clock field
     fi = r.denominator == 1 ? parent * r.numerator         # epoch-relative fu index
-                            : self.class.send(:_floordiv_i, parent * r.numerator, r.denominator)
+                            : parent * r.numerator / r.denominator
     cycle = fu == :h ? 24 : 60                             # hour 0..23; min/sec 0..59
-    fi - self.class.send(:_floordiv_i, fi, cycle) * cycle  # floor-mod (handles pre-epoch)
+    fi % cycle
   end
 
   # Calendar path (Y/M step on day-or-finer storage) via civil-date integer
@@ -2071,19 +2678,19 @@ class CATime
   # min-max, O(N) branch-free, origin-absolute k (negative pre-origin).  The
   # origin's day / time is ignored (month ordinal only, per the design).
   # `kind`: :index / :floor / :ceil / :round / :on.
-  def _civil(kind, st, origin)
+  def calendar_bucket(kind, st, origin)
     su    = unit                                           # storage Resolution
     count = st.count * (st.base == :Y ? 12 : 1)            # bucket in months
-    ym0   = self.class.send(:_origin_month_ordinal, origin)
-    days  = _field_days                                    # count-folded day index
-    y, m  = self.class.send(:_civil_from_days, days)
+    ym0   = CATimeGrid.origin_month_ordinal(origin)
+    days  = days_since_epoch                               # count-folded day index
+    y, m  = CATimeCivil.civil_from_days(days)
     ym    = y * 12 + (m - 1)
-    k     = self.class.send(:_floordiv_i, ym - ym0, count)
+    k     = (ym - ym0) / count
     return k if kind == :index
-    head = self.class.send(:_civil_head_ticks, k, st, su, origin)
+    head = CATimeGrid.calendar_bucket_head_ticks(k, st, su, origin)
     return head.time(unit: su) if kind == :floor
     return parent.eq(head)          if kind == :on
-    head_next = self.class.send(:_civil_head_ticks, k + 1, st, su, origin)
+    head_next = CATimeGrid.calendar_bucket_head_ticks(k + 1, st, su, origin)
     sel =                                # boolean 0/1: pick head_next?
       case kind
       when :ceil  then parent.ne(head)                 # on-boundary keeps head
@@ -2092,198 +2699,6 @@ class CATime
     (head + (head_next - head) * sel).time(unit: su)
   end
 
-  class << self
-    private
-
-    INT64_MIN = -(2**63)
-    INT64_MAX =  2**63 - 1
-
-    # Raise (rather than let an int64 CArray operand silently wrap) if a
-    # Ruby-domain quantity is out of int64 range.  Returns the value on success
-    # so it composes inline.
-    def _chk64(v, what)
-      if v < INT64_MIN || v > INT64_MAX
-        raise RangeError,
-              "time step: #{what} = #{v} overflows int64 " \
-              "(the storage unit is too fine for this step / origin / span; " \
-              "use a coarser unit)"
-      end
-      v
-    end
-
-    # Return [step_ticks, origin_ticks] (both Integer, in storage ticks) for
-    # the integer path.  The calendar path is handled by the caller.
-    def _resolve_grid(step_res, storage_res, origin)
-      mul, step_ticks = _resolve_step_scale(step_res, storage_res)
-      [mul, step_ticks, _resolve_origin_ticks(origin, step_res,
-                                              mul == 1 ? storage_res : step_res)]
-    end
-
-    # Storage ticks per day of `storage_res` (must be a whole number, else the
-    # storage grid does not tile a day -- a calendar bucket is unrepresentable).
-    def _ticks_per_day(storage_res)
-      r = CATimeUnitAlgebra.ratio(Resolution.new(1, :D), storage_res)
-      unless r.denominator == 1
-        raise ArgumentError,
-              "cannot place a calendar bucket on storage resolution " \
-              "#{storage_res} (its tick does not tile a day)"
-      end
-      _chk64(r.numerator, "ticks per day for #{storage_res}")
-    end
-
-    # Storage ticks of the bucket head at timestep `k` (int64 CArray) for a
-    # calendar bucket: ym0 + k*count months -> day 1 of that month -> ticks.
-    def _civil_head_ticks(k, st, storage_res, origin)
-      tpd   = _ticks_per_day(storage_res)
-      count = st.count * (st.base == :Y ? 12 : 1)
-      ym0   = _origin_month_ordinal(origin)
-      ymk   = ym0 + k * count
-      yy    = _floordiv_i(ymk, 12)
-      mm    = ymk - yy * 12 + 1
-      _days_from_civil(yy, mm, CArray.int64(*k.shape) { 1 }) * tpd
-    end
-
-    # Month ordinal (year*12 + month-1) of origin; day / time ignored.
-    # Default (nil) is the epoch month 1970-01.
-    def _origin_month_ordinal(origin)
-      return 1970 * 12 if origin.nil?
-      y, m = _origin_year_month(origin)
-      y * 12 + (m - 1)
-    end
-
-    # Floored integer division of an int64 CArray by a positive Integer
-    # (toward -inf; CArray `/` truncates toward zero).
-    def _floordiv_i(a, b)
-      q = a / b
-      q - (a - q * b).lt(0)
-    end
-
-    # Vectorized Howard Hinnant civil-date algebra (proleptic Gregorian,
-    # negative days supported).  days since the Unix epoch -> [year, month,
-    # day] int64 CArrays.  Truncating division is what the algorithm assumes;
-    # the only negative operand (the 400-year era) is pre-adjusted so
-    # truncation behaves like floor.
-    def _civil_from_days(z)
-      z   = z + 719468
-      era = (z - 146096 * z.lt(0)) / 146097
-      doe = z - era * 146097
-      yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365
-      y   = yoe + era * 400
-      doy = doe - (365 * yoe + yoe / 4 - yoe / 100)
-      mp  = (5 * doy + 2) / 153
-      d   = doy - (153 * mp + 2) / 5 + 1       # day of month, 1..31
-      m   = mp + (3 - 12 * mp.ge(10))          # mp<10 ? +3 : -9
-      [y + m.le(2), m, d]
-    end
-
-    # [year, month, day] int64 CArrays -> days since the Unix epoch.
-    def _days_from_civil(y, m, d)
-      y   = y - m.le(2)
-      era = (y - 399 * y.lt(0)) / 400
-      yoe = y - era * 400
-      doy = (153 * (m + (9 - 12 * m.gt(2))) + 2) / 5 + (d - 1)  # m>2 ? -3 : +9
-      doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
-      era * 146097 + doe - 719468
-    end
-
-    # [mul, step_ticks] for the integer path, or :civil (calendar bucket on
-    # day-or-finer storage), or raise.  Bucket arithmetic runs in the finer of
-    # the two grids, so exactly one of the pair is > 1:
-    #   - bucket at or coarser than the storage tick (a :h bucket on :s
-    #     storage) -> [1, N]: N storage ticks per bucket.
-    #   - bucket finer than the storage tick (a :h bucket on :D storage) ->
-    #     [N, 1]: one storage tick spans N buckets exactly, so a timestep is a
-    #     plain widening.  This needs the storage tick to be a *whole* multiple
-    #     of the bucket tick; a partial multiple ("90 minutes" storage against
-    #     an :h bucket) has no integer timestep and raises.
-    def _resolve_step_scale(step_res, storage_res)
-      r = CATimeUnitAlgebra.ratio(step_res, storage_res)  # storage ticks / step tick
-      if r
-        what = "bucket #{step_res} in ticks of #{storage_res}"
-        return [1, _chk64(r.numerator, what)] if r.denominator == 1
-        return [_chk64(r.denominator, what), 1] if r.numerator == 1
-      end
-      if CATimeUnitAlgebra::CALENDAR.key?(step_res.base) && SU_LE_DAY.include?(storage_res.base)
-        return :civil
-      end
-      raise ArgumentError,
-            "cannot express bucket #{step_res} on storage resolution #{storage_res} " \
-            "(neither is a whole multiple of the other)"
-    end
-
-    # origin -> integer tick count in storage ticks.  Default (nil) is the
-    # epoch, except a week bucket defaults to ISO Monday (1970-01-05).  A lossy
-    # conversion (origin not landing exactly on the storage grid) raises; a
-    # bare Integer is rejected (epoch-dependent, ambiguous).
-    def _resolve_origin_ticks(origin, step_res, storage_res)
-      if origin.nil?
-        if step_res.base == :W && SU_LE_DAY.include?(storage_res.base)
-          return _chk64(_ticks_per_day(storage_res) * 4,
-                        "ISO-Monday week origin in ticks of #{storage_res}")
-        end
-        return 0
-      end
-      if CATimeUnitAlgebra::FIXED.key?(storage_res.base)
-        secs = _origin_seconds_exact(origin)
-        tick = secs / storage_res.tick_ratio               # Rational
-        unless tick.denominator == 1
-          raise ArgumentError,
-                "origin #{origin.inspect} is not representable losslessly " \
-                "in storage resolution #{storage_res} (would truncate the grid phase)"
-        end
-        _chk64(tick.numerator, "origin #{origin.inspect} in ticks of #{storage_res}")
-      else                                                 # :Y / :M storage
-        y, m = _origin_year_month(origin)                  # day / time ignored
-        ord  = storage_res.base == :Y ? (y - 1970) : (y * 12 + (m - 1) - 1970 * 12)
-        if storage_res.count > 1
-          unless (ord % storage_res.count).zero?
-            raise ArgumentError,
-                  "origin #{origin.inspect} is not on the #{storage_res} grid"
-          end
-          ord /= storage_res.count
-        end
-        ord
-      end
-    end
-
-    # Exact Rational seconds since the Unix epoch for a fixed-storage origin.
-    # Time / String / DateTime go through the DateTime-independent parser.
-    def _origin_seconds_exact(origin)
-      case origin
-      when CATime::Element
-        unless CATimeUnitAlgebra::FIXED.key?(origin.unit.base)
-          raise ArgumentError,
-                "origin scalar in calendar unit #{origin.unit} has no exact " \
-                "seconds; use a fixed-unit scalar / Time / String"
-        end
-        Rational(origin.value) * origin.unit.tick_ratio
-      when Integer
-        raise ArgumentError,
-              "origin: a bare Integer is ambiguous (epoch-dependent); pass a " \
-              "Time / String / CATime scalar"
-      else
-        CArray._epoch_seconds_exact(origin)                # Time / String / DateTime
-      end
-    end
-
-    # [year, month] of a calendar-storage origin (finer fields ignored).
-    def _origin_year_month(origin)
-      case origin
-      when CATime::Element
-        case origin.unit.base
-        when :M then mo = origin.value * origin.unit.count + 1970 * 12; [mo / 12, mo % 12 + 1]
-        when :Y then [origin.value * origin.unit.count + 1970, 1]
-        else t = origin.to_time.utc; [t.year, t.month]
-        end
-      when Integer
-        raise ArgumentError,
-              "origin: a bare Integer is ambiguous (epoch-dependent); pass a " \
-              "Time / String / CATime scalar"
-      else
-        CArray._epoch_year_month(origin)                   # Time / String / DateTime
-      end
-    end
-  end
 end
 
 # The view-creating method lift hook lives in the C layer (= subclass-