hron 1.0.0 → 2.0.0

data/lib/hron/evaluator.rb

@@ -5,1146 +5,475 @@ require "time"
 require "tzinfo"
 require_relative "ast"
 require_relative "error"
+require_relative "eval/calendar"
+require_relative "eval/wall_clock"
 
 module Hron
-  # =============================================================================
-  # Iteration Safety Limits
-  # =============================================================================
-  # MAX_ITERATIONS (1000): Maximum iterations for next_from/previous_from loops.
-  # Prevents infinite loops when searching for valid occurrences.
-  #
-  # Expression-specific limits:
-  # - Day repeat: 8 days (covers one week + margin)
-  # - Week repeat: 54 weeks (covers one year + margin)
-  # - Month repeat: 24 * interval months (covers 2 years scaled by interval)
-  # - Year repeat: 8 * interval years (covers reasonable future horizon)
-  #
-  # These limits are generous safety bounds. In practice, valid schedules
-  # find occurrences within the first few iterations.
-  # =============================================================================
-
-  # =============================================================================
-  # DST (Daylight Saving Time) Handling
-  # =============================================================================
-  # When resolving a wall-clock time to an instant:
-  #
-  # 1. DST Gap (Spring Forward):
-  #    - Time doesn't exist (e.g., 2:30 AM during spring forward)
-  #    - Solution: Push forward to the next valid time after the gap
-  #    - Example: 2:30 AM -> 3:00 AM (or 3:30 AM depending on gap size)
-  #
-  # 2. DST Fold (Fall Back):
-  #    - Time is ambiguous (e.g., 1:30 AM occurs twice)
-  #    - Solution: Use first occurrence (fold=0 / pre-transition time)
-  #    - This matches user expectation for scheduling
-  #
-  # All implementations use the same algorithm for cross-language consistency.
-  # =============================================================================
-
-  # =============================================================================
-  # Interval Alignment (Anchor Date)
-  # =============================================================================
-  # For schedules with interval > 1 (e.g., "every 3 days"), we need to
-  # determine which dates are valid based on alignment with an anchor.
-  #
-  # Formula: (date_offset - anchor_offset) mod interval == 0
-  #
-  # Where:
-  #   - date_offset: days/weeks/months from epoch to candidate date
-  #   - anchor_offset: days/weeks/months from epoch to anchor date
-  #   - interval: the repeat interval (e.g., 3 for "every 3 days")
-  #
-  # Default anchor: Epoch (1970-01-01)
-  # Custom anchor: Set via "starting YYYY-MM-DD" clause
-  #
-  # For week repeats, we use epoch Monday (1970-01-05) as the reference
-  # point to align week boundaries correctly.
-  # =============================================================================
-
-  EPOCH_DATE = Date.new(1970, 1, 1)
-  EPOCH_MONDAY = Date.new(1970, 1, 5)
-
-  # Timezone resolution
-  module TzResolver
-    def self.resolve(tz_name)
-      if tz_name && !tz_name.empty?
-        TZInfo::Timezone.get(tz_name)
-      else
-        # Default to UTC for deterministic, portable behavior
-        TZInfo::Timezone.get("UTC")
-      end
-    end
-  end
+  class Evaluator
+    # Default anchor for week intervals (spec/README.md, "WeekRepeat epoch alignment").
+    EPOCH_MONDAY = Date.new(1970, 1, 5, Date::GREGORIAN)
 
-  # Evaluator helpers
-  module EvalHelpers
-    def self.at_time_on_date(d, tod, tz)
-      # Create local time representation (using UTC to avoid system TZ interference)
-      local_time = Time.utc(d.year, d.month, d.day, tod.hour, tod.minute, 0)
-
-      # Get periods for this local time
-      periods = tz.periods_for_local(local_time)
-
-      case periods.length
-      when 0
-        # Time doesn't exist (spring forward gap)
-        # Push the time forward past the gap (like "compatible" disambiguation)
-        # For example: 02:30 during DST spring forward -> 03:30
-
-        # Find the transition on this date
-        day_start = Time.utc(d.year, d.month, d.day, 0, 0, 0)
-        day_end = Time.utc(d.year, d.month, d.day, 23, 59, 59)
-        transitions = tz.transitions_up_to(day_end, day_start)
-
-        if transitions.any?
-          # Find the spring-forward transition (where offset increases / DST starts)
-          transition = transitions.find { |t| t.offset.dst? }
-          if transition
-            # The transition time is when the gap starts
-            # We need to push the requested time forward by the gap size
-            prev_offset = transition.previous_offset.utc_total_offset
-            new_offset = transition.offset.utc_total_offset
-            gap_seconds = new_offset - prev_offset # Positive for spring forward
-
-            # Push the local time forward by the gap amount
-            # E.g., 02:30 + 1 hour = 03:30 local
-            pushed_local = local_time + gap_seconds
-
-            # Convert the pushed local time to UTC using the new offset
-            # E.g., 03:30 local EDT (-4h) -> 07:30 UTC
-            return pushed_local - new_offset
-          end
-        end
+    EPOCH_DATE = Date.new(1970, 1, 1, Date::GREGORIAN)
 
-        # Fallback: try to construct the time and let TZInfo handle it
-        # This shouldn't normally be reached
-        begin
-          tz.local_to_utc(local_time)
-        rescue TZInfo::AmbiguousTime, TZInfo::PeriodNotFound
-          nil
-        end
-      when 1
-        # Unambiguous time - straightforward conversion
-        period = periods[0]
-        utc_offset = period.offset.utc_total_offset
-        local_time - utc_offset
-      when 2
-        # Ambiguous time (fall back) - use first occurrence (pre-transition)
-        # Period 0 is the earlier offset (e.g., EDT -04:00 before fall back)
-        period = periods[0]
-        utc_offset = period.offset.utc_total_offset
-        local_time - utc_offset
-      end
-    end
+    # spec/README.md, "Supported range".
+    SUPPORTED_RANGE = Time.utc(1, 1, 2)...Time.utc(9999, 12, 30)
 
-    def self.matches_day_filter(d, filter)
-      dow = d.cwday # Monday=1 ... Sunday=7
-      case filter
-      when DayFilterEvery
-        true
-      when DayFilterWeekday
-        dow.between?(1, 5)
-      when DayFilterWeekend
-        [6, 7].include?(dow)
-      when DayFilterDays
-        filter.days.any? { |wd| Weekday.number(wd) == dow }
-      else
-        false
-      end
-    end
+    # Slack beyond the horizon for the period one behind the first date's, where a
+    # search starts, and for a horizon that starts mid-period.
+    HORIZON_MARGIN_PERIODS = 2
 
-    def self.last_day_of_month(year, month)
-      Date.new(year, month, -1)
-    end
+    # How many dates past its scheduled date a fixed time can land: one shifted out of a gap
+    # before midnight lands on the next date.
+    MAX_SHIFT_DAYS = 1
 
-    def self.last_weekday_of_month(year, month)
-      d = last_day_of_month(year, month)
-      d -= 1 while d.cwday >= 6
-      d
-    end
+    # How many dates behind a date that has begun now's wall date can read: from the second
+    # pass of a fall-back overlap that crosses midnight, one.
+    MAX_OVERLAP_DAYS = 1
 
-    # Get the nearest weekday to a given day in a month.
-    # - direction=nil: standard cron W behavior (never crosses month boundary)
-    # - direction=NearestDirection::NEXT: always prefer following weekday (can cross to next month)
-    # - direction=NearestDirection::PREVIOUS: always prefer preceding weekday (can cross to prev month)
-    # Returns nil if the target_day doesn't exist in the month (e.g., day 31 in February).
-    def self.nearest_weekday(year, month, target_day, direction)
-      last = last_day_of_month(year, month)
-      last_day_num = last.day
-
-      # If target day doesn't exist in this month, return nil (skip this month)
-      return nil if target_day > last_day_num
-
-      date = Date.new(year, month, target_day)
-      dow = date.cwday # Monday=1 ... Sunday=7
-
-      # Already a weekday (Mon-Fri = 1-5)
-      return date if dow.between?(1, 5)
-
-      case direction
-      when nil
-        # Standard cron W behavior: never cross month boundary
-        if dow == 6 && target_day == 1
-          # Saturday at 1st: can't go to previous month, use Monday (day 3)
-          date + 2
-        elsif dow == 6
-          # Saturday: Friday
-          date - 1
-        elsif target_day >= last_day_num
-          # Sunday at end of month: can't go to next month, use Friday
-          date - 2
-        else
-          # Sunday: Monday
-          date + 1
-        end
+    # Feb 29 can be eight years away, as from 2096-03-01 to 2104-02-29.
+    NAMED_UNTIL_MAX_YEARS = 8
 
-      when NearestDirection::NEXT
-        # Always prefer following weekday (can cross month)
-        if dow == 6 # Saturday -> Monday
-          date + 2
-        else # Sunday -> Monday
-          date + 1
-        end
+    # interval_slots and days_of are shared with Cron.to_cron, so conversion never disagrees with
+    # evaluation.
+    def self.interval_slots(interval, unit, from, to)
+      step = (unit == IntervalUnit::MIN) ? interval : interval * WallClock::MINUTES_PER_HOUR
+      (WallClock.minute_of_day(from)..WallClock.minute_of_day(to)).step(step).to_a
+    end
 
-      when NearestDirection::PREVIOUS
-        # Always prefer preceding weekday (can cross month if day==1)
-        if dow == 6 # Saturday -> Friday
-          date - 1
-        else # Sunday -> Friday (go back 2 days)
-          date - 2
+    def self.days_of(target)
+      target.specs.flat_map do |spec|
+        case spec
+        when SingleDay then [spec.day]
+        when DayRange then (spec.start..spec.end_day).to_a
         end
       end
     end
 
-    def self.nth_weekday_of_month(year, month, weekday, n)
-      target_dow = Weekday.number(weekday)
-      d = Date.new(year, month, 1)
-      d += 1 while d.cwday != target_dow
-      (n - 1).times { d += 7 }
-      return nil if d.month != month
-
-      d
-    end
-
-    def self.last_weekday_in_month(year, month, weekday)
-      target_dow = Weekday.number(weekday)
-      d = last_day_of_month(year, month)
-      d -= 1 while d.cwday != target_dow
-      d
+    def self.next_from(schedule, now)
+      require_time(now, "now")
+      Search.new(schedule).nearest(now, Direction::FORWARD) if SUPPORTED_RANGE.cover?(now)
     end
 
-    def self.weeks_between(a, b)
-      (b - a).to_i / 7
+    def self.previous_from(schedule, now)
+      require_time(now, "now")
+      Search.new(schedule).nearest(now, Direction::BACKWARD) if SUPPORTED_RANGE.cover?(now)
     end
 
-    def self.days_between(a, b)
-      (b - a).to_i
-    end
+    # Not Enumerable#first, which raises RangeError for an n past a machine integer, where
+    # n only caps the count (spec/README.md, "Timestamps and counts").
+    def self.next_n_from(schedule, now, n)
+      require_time(now, "now")
+      raise TypeError, "n must be an Integer, not #{n.class}" unless n.is_a?(Integer)
 
-    def self.months_between_ym(a, b)
-      (b.year * 12) + b.month - ((a.year * 12) + a.month)
-    end
+      results = []
+      return results unless n.positive?
 
-    def self.is_excepted(d, exceptions)
-      exceptions.any? do |exc|
-        case exc
-        when NamedException
-          d.month == MonthName.number(exc.month) && d.day == exc.day
-        when IsoException
-          d == Date.parse(exc.date)
-        else
-          false
-        end
+      occurrences(schedule, now).each do |occurrence|
+        results << occurrence
+        break if results.size == n
       end
+      results
     end
 
-    def self.matches_during(d, during)
-      return true if during.empty?
+    def self.occurrences(schedule, from)
+      require_time(from, "from")
+      Enumerator.new do |yielder|
+        next unless SUPPORTED_RANGE.cover?(from)
 
-      during.any? { |mn| MonthName.number(mn) == d.month }
+        search = Search.new(schedule)
+        current = from
+        while (current = search.nearest(current, Direction::FORWARD))
+          yielder << current
+        end
+      end.lazy
     end
 
-    def self.next_during_month(d, during)
-      months = during.map { |mn| MonthName.number(mn) }.sort
-
-      months.each do |m|
-        return Date.new(d.year, m, 1) if m > d.month
-      end
+    def self.between(schedule, from, to)
+      require_time(from, "from")
+      require_time(to, "to")
+      Enumerator.new do |yielder|
+        next unless SUPPORTED_RANGE.cover?(to)
 
-      # Wrap to first month of next year
-      Date.new(d.year + 1, months[0], 1)
-    end
+        occurrences(schedule, from).each do |instant|
+          break if instant > to
 
-    def self.resolve_until(until_spec, now)
-      case until_spec
-      when IsoUntil
-        Date.parse(until_spec.date)
-      when NamedUntil
-        year = now.year
-        [year, year + 1].each do |y|
-          d = Date.new(y, MonthName.number(until_spec.month), until_spec.day)
-          return d if d >= now.to_date
-        rescue ArgumentError
-          next
+          yielder << instant
         end
-        Date.new(year + 1, MonthName.number(until_spec.month), until_spec.day)
-      end
+      end.lazy
     end
 
-    def self.earliest_future_at_times(d, times, tz, now)
-      best = nil
-      times.each do |tod|
-        candidate = at_time_on_date(d, tod, tz)
-        next unless candidate
+    # Defined through the forward search, so the two cannot disagree (spec/README.md,
+    # "matches is true exactly when the minute containing t is an occurrence").
+    def self.matches(schedule, dt)
+      require_time(dt, "datetime")
+      return false unless SUPPORTED_RANGE.cover?(dt)
 
-        best = candidate if candidate > now && (best.nil? || candidate < best)
-      end
-      best
+      search = Search.new(schedule)
+      local = search.zone.to_local(dt)
+      minute = dt - local.sec - local.subsec
+      # Occurrences fall on whole seconds, so none lies between this and the minute.
+      just_before = minute - 1
+      # An occurrence never lands before the date it is scheduled on, so one at this minute
+      # is scheduled on or before the minute's wall date.
+      search.clauses.end_on(local.to_date.gregorian)
+      search.nearest(just_before, Direction::FORWARD) == minute
     end
 
-    def self.latest_past_at_times(d, times, tz, now)
-      best = nil
-      times.each do |tod|
-        candidate = at_time_on_date(d, tod, tz)
-        next unless candidate
-
-        best = candidate if candidate < now && (best.nil? || candidate > best)
-      end
-      best
+    # A usage error, never a HronError (spec/README.md, "Timestamps and counts").
+    def self.require_time(value, name)
+      raise TypeError, "#{name} must be a Time, not #{value.class}" unless value.is_a?(Time)
     end
+    private_class_method :require_time
 
-    def self.prev_during_month(d, during)
-      months = during.map { |mn| MonthName.number(mn) }.sort.reverse
+    class Direction
+      attr_reader :sign
 
-      months.each do |m|
-        return last_day_of_month(d.year, m) if m < d.month
+      def initialize(sign)
+        @sign = sign
+        @forward = sign.positive?
       end
 
-      # Wrap to last month of previous year
-      return last_day_of_month(d.year - 1, months[0]) unless months.empty?
-
-      nil
-    end
-  end
-
-  # Main evaluator class
-  class Evaluator
-    def self.next_from(schedule, now)
-      tz = TzResolver.resolve(schedule.timezone)
-      until_date = schedule.until ? EvalHelpers.resolve_until(schedule.until, now) : nil
-      has_exceptions = !schedule.except.empty?
-      has_during = !schedule.during.empty?
-
-      # Check if expression is NearestWeekday with direction (can cross month boundaries)
-      handles_during_internally = schedule.expr.is_a?(MonthRepeat) &&
-        schedule.expr.target.is_a?(NearestWeekdayTarget) &&
-        !schedule.expr.target.direction.nil?
-
-      current = now
-      1000.times do
-        candidate = next_expr(schedule.expr, tz, schedule.anchor, current, schedule.during)
-        return nil unless candidate
-
-        c_date = candidate.to_date
-
-        # Apply until filter
-        return nil if until_date && c_date > until_date
-
-        # Apply during filter
-        # Skip this check for expressions that handle during internally (NearestWeekday with direction)
-        if has_during && !handles_during_internally && !EvalHelpers.matches_during(c_date, schedule.during)
-          skip_to = EvalHelpers.next_during_month(c_date, schedule.during)
-          midnight = EvalHelpers.at_time_on_date(skip_to, TimeOfDay.new(0, 0), tz)
-          current = midnight - 1
-          next
-        end
-
-        # Apply except filter
-        if has_exceptions && EvalHelpers.is_excepted(c_date, schedule.except)
-          next_day = c_date + 1
-          midnight = EvalHelpers.at_time_on_date(next_day, TimeOfDay.new(0, 0), tz)
-          current = midnight - 1
-          next
-        end
-
-        return candidate
+      def forward?
+        @forward
       end
 
-      nil
-    end
-
-    def self.next_n_from(schedule, now, n)
-      results = []
-      current = now
-      n.times do
-        nxt = next_from(schedule, current)
-        break unless nxt
-
-        results << nxt
-        current = nxt + 60 # Add 1 minute
+      def precedes?(a, b)
+        @forward ? a < b : a > b
       end
-      results
-    end
 
-    def self.previous_from(schedule, now)
-      tz = TzResolver.resolve(schedule.timezone)
-      anchor_date = schedule.anchor ? Date.parse(schedule.anchor) : nil
-      has_exceptions = !schedule.except.empty?
-      has_during = !schedule.during.empty?
-
-      # Handle until clause - if now is after until, search from end of until date
-      search_from = now
-      if schedule.until
-        until_date = EvalHelpers.resolve_until(schedule.until, now)
-        now_date = now.to_date
-        if now_date > until_date
-          next_day = until_date + 1
-          search_from = EvalHelpers.at_time_on_date(next_day, TimeOfDay.new(0, 0), tz)
-        end
+      def in_order(items)
+        (@forward || items.size < 2) ? items : items.reverse
       end
 
-      1000.times do
-        candidate = prev_expr(schedule.expr, tz, schedule.anchor, search_from)
-        return nil unless candidate
+      FORWARD = new(1)
+      BACKWARD = new(-1)
+      private_class_method :new
+    end
 
-        c_date = candidate.to_date
+    class Search
+      attr_reader :zone, :clauses
 
-        # Check if before anchor
-        return nil if anchor_date && c_date < anchor_date
+      def initialize(schedule)
+        name = schedule.timezone
+        @zone = TZInfo::Timezone.get(name || "UTC")
+        @result_zone = name ? @zone : "UTC"
+        @clauses = Clauses.new(schedule)
+        @cadence = Cadence.of(schedule.expression, @clauses.starting)
+        @times = DailyTimes.of(schedule.expression)
+        @expr = schedule.expression
+      end
 
-        # Check until date - should not return occurrences after until
-        if schedule.until
-          until_date = EvalHelpers.resolve_until(schedule.until, now)
-          if c_date > until_date
-            search_from = candidate
-            next
-          end
-        end
+      def nearest(now, direction)
+        now = @zone.utc_to_local(now.getutc)
+        now_date = now.to_date.gregorian
+        first_date = @clauses.clamp(now_date, direction)
+        # A nearest weekday or a DST shift can move an occurrence out of the period it is
+        # scheduled in, so the search starts one period back.
+        first_period = @cadence.period_of(first_date) - direction.sign
+        farthest = @clauses.farthest_except_date(direction)
+        reach = farthest ? @cadence.period_of(farthest) : first_period
+        shift = @times.max_shift_days
+        best = nil
+        each_candidate(first_period, reach, direction) do |candidate|
+          date = candidate.date
+          break if best && !could_beat?(date, best.landing, direction, shift)
+          break if @clauses.ends_search?(date, direction)
+          next if behind?(date, now_date, direction, shift) || !@clauses.allows?(candidate)
 
-        # Apply except filter
-        if has_exceptions && EvalHelpers.is_excepted(c_date, schedule.except)
-          search_from = candidate
-          next
+          occurrence = nearest_on_date(date, now, direction)
+          best = occurrence if occurrence && (best.nil? || direction.precedes?(occurrence.instant, best.instant))
         end
+        Time.at(best.instant, in: @result_zone) if best && SUPPORTED_RANGE.cover?(best.instant)
+      end
 
-        # Apply during filter
-        if has_during && !EvalHelpers.matches_during(c_date, schedule.during)
-          prev_month = EvalHelpers.prev_during_month(c_date, schedule.during)
-          return nil unless prev_month
+      private
 
-          next_day = prev_month + 1
-          search_from = EvalHelpers.at_time_on_date(next_day, TimeOfDay.new(0, 0), tz)
-          next
+      def each_candidate(first_period, reach, direction, &)
+        @cadence.period_starts(first_period, reach, direction) do |start|
+          direction.in_order(candidates_in_period(start)).each(&) unless rejects_period?(start)
         end
-
-        return candidate
       end
 
-      nil
-    end
-
-    def self.prev_expr(expr, tz, anchor, now)
-      case expr
-      when DayRepeat
-        prev_day_repeat(expr.interval, expr.days, expr.times, tz, anchor, now)
-      when IntervalRepeat
-        prev_interval_repeat(expr.interval, expr.unit, expr.from_time, expr.to_time, expr.day_filter, tz, now)
-      when WeekRepeat
-        prev_week_repeat(expr.interval, expr.days, expr.times, tz, anchor, now)
-      when MonthRepeat
-        prev_month_repeat(expr.interval, expr.target, expr.times, tz, anchor, now)
-      when SingleDateExpr
-        prev_single_date(expr.date, expr.times, tz, now)
-      when YearRepeat
-        prev_year_repeat(expr.interval, expr.target, expr.times, tz, anchor, now)
+      # A day or month period's candidates all target its own month, so one whose month
+      # during rejects holds nothing.
+      def rejects_period?(start)
+        unit = @cadence.unit
+        (unit == :day || unit == :month) && !@clauses.allows_month?(start.month)
       end
-    end
-
-    def self.prev_day_repeat(interval, days, times, tz, anchor, now)
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-
-      1000.times do
-        if interval > 1
-          offset = EvalHelpers.days_between(anchor_date, d)
-          mod = offset % interval
-          mod += interval if mod.negative?
-          unless mod.zero?
-            d -= mod
-            next
-          end
-        end
 
-        if EvalHelpers.matches_day_filter(d, days)
-          candidate = EvalHelpers.latest_past_at_times(d, times, tz, now)
-          return candidate if candidate
+      def candidates_in_period(start)
+        case @expr
+        when DayRepeat
+          Calendar.matches_day_filter?(start, @expr.days) ? [Candidate.on(start)] : []
+        when IntervalRepeat
+          Calendar.matches_day_filter?(start, @expr.day_filter) ? [Candidate.on(start)] : []
+        when WeekRepeat
+          @expr.days.map { |day| start + (Weekday.number(day) - 1) }.uniq.sort.map { |date| Candidate.on(date) }
+        when MonthRepeat
+          Calendar.month_target_dates(start.year, start.month, @expr.target).map { |date| Candidate.new(date, start.month) }
+        when YearRepeat
+          date = Calendar.year_target_date(start.year, @expr.target)
+          date ? [Candidate.on(date)] : []
+        when SingleDateExpr
+          date = @expr.date.is_a?(IsoDate) ? start : Calendar.date(start.year, MonthName.number(@expr.date.month), @expr.date.day)
+          date ? [Candidate.on(date)] : []
         end
-
-        d -= (interval > 1) ? interval : 1
       end
 
-      nil
-    end
-
-    def self.prev_interval_repeat(interval, unit, from_time, to_time, day_filter, tz, now)
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-      step_minutes = (unit == IntervalUnit::MIN) ? interval : interval * 60
-      from_minutes = (from_time.hour * 60) + from_time.minute
-      to_minutes = (to_time.hour * 60) + to_time.minute
-
-      1000.times do
-        if day_filter && !EvalHelpers.matches_day_filter(d, day_filter)
-          d -= 1
-          next
-        end
-
-        # Build list of times in window
-        window_times = []
-        m = from_minutes
-        while m <= to_minutes
-          window_times << m
-          m += step_minutes
-        end
-
-        # Search backwards through window
-        window_times.reverse_each do |slot|
-          h = slot / 60
-          min = slot % 60
-          candidate = EvalHelpers.at_time_on_date(d, TimeOfDay.new(h, min), tz)
-          return candidate if candidate && candidate < now
-        end
-
-        d -= 1
+      # An occurrence lands from its scheduled date to shift dates after it, on a first pass,
+      # and first passes keep wall-clock order.
+      def could_beat?(date, landing, direction, shift)
+        direction.forward? ? date <= landing : Calendar.days_between(date, landing) <= shift
       end
 
-      nil
-    end
-
-    def self.prev_week_repeat(interval, days, times, tz, anchor, now)
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_MONDAY
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-
-      # Sort target DOWs in descending order for backwards search
-      sorted_days = days.sort_by { |wd| -Weekday.number(wd) }
-
-      dow_offset = d.cwday - 1
-      current_monday = d - dow_offset
-
-      anchor_dow_offset = anchor_date.cwday - 1
-      anchor_monday = anchor_date - anchor_dow_offset
-
-      54.times do
-        weeks = EvalHelpers.weeks_between(anchor_monday, current_monday)
-        return nil if weeks.negative?
-
-        if (weeks % interval).zero?
-          sorted_days.each do |wd|
-            day_offset = Weekday.number(wd) - 1
-            target_date = current_monday + day_offset
-            candidate = EvalHelpers.latest_past_at_times(target_date, times, tz, now)
-            return candidate if candidate
-          end
+      def behind?(date, now_date, direction, shift)
+        if direction.forward?
+          Calendar.days_between(date, now_date) > shift
+        else
+          Calendar.days_between(now_date, date) > MAX_OVERLAP_DAYS
         end
-
-        remainder = weeks % interval
-        skip_weeks = remainder.zero? ? interval : remainder
-        current_monday -= skip_weeks * 7
       end
 
-      nil
-    end
+      def nearest_on_date(date, now, direction)
+        case @times
+        when DailyTimes::Fixed
+          # Every time is compared: one shifted out of a gap can land after a later wall time.
+          nearest = landing = nil
+          @times.times.each do |time|
+            instant, lands_on = WallClock.fixed_time_on(date, time, @zone)
+            next if !direction.precedes?(now, instant) || (nearest && !direction.precedes?(instant, nearest))
 
-    def self.prev_month_repeat(interval, target, times, tz, anchor, now)
-      now_local = tz.utc_to_local(now.utc)
-      year = now_local.year
-      month = now_local.month
-
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-      max_iter = (interval > 1) ? 24 * interval : 24
-
-      max_iter.times do
-        if interval > 1
-          cur = Date.new(year, month, 1)
-          month_offset = EvalHelpers.months_between_ym(anchor_date, cur)
-          if month_offset.negative? || (month_offset % interval) != 0
-            month -= 1
-            if month < 1
-              month = 12
-              year -= 1
-            end
-            next
+            nearest = instant
+            landing = lands_on
           end
-        end
-
-        date_candidates = []
-
-        case target
-        when DaysTarget
-          expanded = Hron.expand_month_target(target)
-          last = EvalHelpers.last_day_of_month(year, month)
-          expanded.sort.reverse_each do |day_num|
-            next unless day_num <= last.day
-
-            begin
-              date_candidates << Date.new(year, month, day_num)
-            rescue ArgumentError
-              # Invalid date
-            end
-          end
-        when LastDayTarget
-          date_candidates << EvalHelpers.last_day_of_month(year, month)
-        when LastWeekdayTarget
-          date_candidates << EvalHelpers.last_weekday_of_month(year, month)
-        when NearestWeekdayTarget
-          nw = EvalHelpers.nearest_weekday(year, month, target.day, target.direction)
-          date_candidates << nw if nw
-        when OrdinalWeekdayTarget
-          ordinal_date = if target.ordinal == OrdinalPosition::LAST
-            EvalHelpers.last_weekday_in_month(year, month, target.weekday)
+          Occurrence.new(nearest, landing) if nearest
+        when DailyTimes::Slots
+          instant = nearest_slot(date, now, direction)
+          # A slot outside a gap is the first pass of its wall time, so it lands on its date.
+          Occurrence.new(instant, date) if instant
+        end
+      end
+
+      # Slot keys never decrease in wall-clock order, so one binary search finds where the
+      # slots past now begin.
+      def nearest_slot(date, now, direction)
+        minutes = @times.minutes
+        forward = direction.forward?
+        low = 0
+        high = minutes.size
+        below = above = nil
+        while low < high
+          middle = (low + high) / 2
+          slot = WallClock.slot_on(date, minutes[middle], @zone)
+          if forward ? slot.key > now : slot.key >= now
+            high = middle
+            above = slot
           else
-            EvalHelpers.nth_weekday_of_month(year, month, target.weekday, OrdinalPosition.to_n(target.ordinal))
+            low = middle + 1
+            below = slot
           end
-          date_candidates << ordinal_date if ordinal_date
         end
+        index, slot = forward ? [low, above] : [low - 1, below]
+        while index >= 0 && index < minutes.size
+          slot ||= WallClock.slot_on(date, minutes[index], @zone)
+          return slot.instant if slot.instant
 
-        # Sort in descending order for backwards search
-        date_candidates.sort! { |a, b| b <=> a }
-
-        date_candidates.each do |dc|
-          candidate = EvalHelpers.latest_past_at_times(dc, times, tz, now)
-          return candidate if candidate
-        end
-
-        month -= 1
-        if month < 1
-          month = 12
-          year -= 1
-        end
-      end
-
-      nil
-    end
-
-    def self.prev_single_date(date_spec, times, tz, now)
-      case date_spec
-      when IsoDate
-        d = Date.parse(date_spec.date)
-        EvalHelpers.latest_past_at_times(d, times, tz, now)
-      when NamedDate
-        now_local = tz.utc_to_local(now.utc)
-        start_year = now_local.year
-        8.times do |y|
-          year = start_year - y
-          begin
-            d = Date.new(year, MonthName.number(date_spec.month), date_spec.day)
-            candidate = EvalHelpers.latest_past_at_times(d, times, tz, now)
-            return candidate if candidate
-          rescue ArgumentError
-            # Invalid date
-          end
+          slot = nil
+          index += direction.sign
         end
         nil
       end
     end
 
-    def self.prev_year_repeat(interval, target, times, tz, anchor, now)
-      now_local = tz.utc_to_local(now.utc)
-      start_year = now_local.year
-      anchor_year = anchor ? Date.parse(anchor).year : EPOCH_DATE.year
-
-      max_iter = (interval > 1) ? 8 * interval : 8
+    Occurrence = Data.define(:instant, :landing)
 
-      max_iter.times do |y|
-        year = start_year - y
-
-        if interval > 1
-          year_offset = year - anchor_year
-          next if year_offset.negative? || (year_offset % interval) != 0
-        end
-
-        target_date = compute_year_target_date(target, year)
-        next unless target_date
-
-        candidate = EvalHelpers.latest_past_at_times(target_date, times, tz, now)
-        return candidate if candidate
+    # target_month differs from date's month only when a directional nearest weekday crosses
+    # into the adjacent month. A Struct, as one is made for every date a search walks and a
+    # Data costs twice as much to make.
+    Candidate = Struct.new(:date, :target_month) do
+      def self.on(date)
+        new(date, date.month)
       end
-
-      nil
     end
 
-    # Returns a lazy Enumerator of occurrences starting after `from`.
-    # The iterator respects the `until` clause if specified.
-    def self.occurrences(schedule, from)
-      Enumerator.new do |yielder|
-        current = from
-        loop do
-          nxt = next_from(schedule, current)
-          break unless nxt
-
-          yielder << nxt
-          current = nxt + 60 # Add 1 minute
+    module DailyTimes
+      Fixed = Data.define(:times) do
+        def max_shift_days
+          MAX_SHIFT_DAYS
         end
-      end.lazy
-    end
-
-    # Returns a lazy Enumerator of occurrences where from < occurrence <= to.
-    def self.between(schedule, from, to)
-      Enumerator.new do |yielder|
-        occurrences(schedule, from).each do |dt|
-          break if dt > to
+      end
 
-          yielder << dt
+      # Each slot is skipped in a gap, so it lands on its own date.
+      Slots = Data.define(:minutes) do
+        def max_shift_days
+          0
         end
-      end.lazy
-    end
-
-    def self.matches(schedule, dt)
-      tz = TzResolver.resolve(schedule.timezone)
-      # Convert to local time in the target timezone
-      dt_local = tz.utc_to_local(dt.utc)
-      d = dt_local.to_date
-
-      return false if !schedule.during.empty? && !EvalHelpers.matches_during(d, schedule.during)
-      return false if EvalHelpers.is_excepted(d, schedule.except)
-
-      if schedule.until
-        until_date = EvalHelpers.resolve_until(schedule.until, dt)
-        return false if d > until_date
       end
 
-      matches_expr(schedule.expr, schedule.anchor, d, dt_local, tz)
-    end
+      def self.of(expr)
+        return Fixed.new(expr.times) unless expr.is_a?(IntervalRepeat)
 
-    def self.next_expr(expr, tz, anchor, now, during = [])
-      case expr
-      when DayRepeat
-        next_day_repeat(expr.interval, expr.days, expr.times, tz, anchor, now)
-      when IntervalRepeat
-        next_interval_repeat(expr.interval, expr.unit, expr.from_time, expr.to_time, expr.day_filter, tz, now)
-      when WeekRepeat
-        next_week_repeat(expr.interval, expr.days, expr.times, tz, anchor, now)
-      when MonthRepeat
-        next_month_repeat(expr.interval, expr.target, expr.times, tz, anchor, now, during)
-      when SingleDateExpr
-        next_single_date(expr.date, expr.times, tz, now)
-      when YearRepeat
-        next_year_repeat(expr.interval, expr.target, expr.times, tz, anchor, now)
+        Slots.new(Evaluator.interval_slots(expr.interval, expr.unit, expr.from_time, expr.to_time))
       end
     end
 
-    def self.matches_expr(expr, anchor, d, dt, tz)
-      time_matches = ->(times) { time_matches_with_dst(times, d, dt, tz) }
-
-      case expr
-      when DayRepeat
-        return false unless EvalHelpers.matches_day_filter(d, expr.days)
-        return false unless time_matches.call(expr.times)
-
-        if expr.interval > 1
-          anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-          day_offset = EvalHelpers.days_between(anchor_date, d)
-          return day_offset >= 0 && (day_offset % expr.interval).zero?
-        end
-        true
-
-      when IntervalRepeat
-        return false if expr.day_filter && !EvalHelpers.matches_day_filter(d, expr.day_filter)
+    # during applies to a candidate's target month; except, until and starting to its date
+    # (spec/README.md, "Nearest weekday and `during`", "The `starting` clause").
+    class Clauses
+      attr_reader :starting
 
-        from_minutes = (expr.from_time.hour * 60) + expr.from_time.minute
-        to_minutes = (expr.to_time.hour * 60) + expr.to_time.minute
-        current_minutes = (dt.hour * 60) + dt.min
-        return false if current_minutes < from_minutes || current_minutes > to_minutes
-
-        diff = current_minutes - from_minutes
-        step = (expr.unit == IntervalUnit::MIN) ? expr.interval : expr.interval * 60
-        diff >= 0 && (diff % step).zero?
-
-      when WeekRepeat
-        dow = d.cwday
-        return false unless expr.days.any? { |wd| Weekday.number(wd) == dow }
-        return false unless time_matches.call(expr.times)
-
-        anchor_date = anchor ? Date.parse(anchor) : EPOCH_MONDAY
-        weeks = EvalHelpers.weeks_between(anchor_date, d)
-        weeks >= 0 && (weeks % expr.interval).zero?
-
-      when MonthRepeat
-        return false unless time_matches.call(expr.times)
-
-        if expr.interval > 1
-          anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-          month_offset = EvalHelpers.months_between_ym(anchor_date, d)
-          return false if month_offset.negative? || (month_offset % expr.interval) != 0
-        end
-        matches_month_target(expr.target, d)
-
-      when SingleDateExpr
-        return false unless time_matches.call(expr.times)
-
-        matches_date_spec(expr.date, d)
-
-      when YearRepeat
-        return false unless time_matches.call(expr.times)
-
-        if expr.interval > 1
-          anchor_year = anchor ? Date.parse(anchor).year : EPOCH_DATE.year
-          year_offset = d.year - anchor_year
-          return false if year_offset.negative? || (year_offset % expr.interval) != 0
-        end
-        matches_year_target(expr.target, d)
-
-      else
-        false
+      def initialize(schedule)
+        @starting = schedule.starting && Calendar.parse_date(schedule.starting)
+        @until = schedule.until && resolve_until(schedule.until, @starting)
+        named, iso = schedule.except.partition { |exception| exception.is_a?(NamedException) }
+        @except_month_days = named.map { |exception| [MonthName.number(exception.month), exception.day] }
+        @except_dates = iso.map { |exception| Calendar.parse_date(exception.date) }
+        @during = schedule.during.map { |month| MonthName.number(month) }
       end
-    end
 
-    def self.time_matches_with_dst(times, d, dt, tz)
-      times.any? do |tod|
-        if dt.hour == tod.hour && dt.min == tod.minute
-          true
-        else
-          # DST gap check
-          resolved = EvalHelpers.at_time_on_date(d, tod, tz)
-          resolved && resolved.to_i == dt.to_i
-        end
+      def allows?(candidate)
+        date = candidate.date
+        allows_month?(candidate.target_month) &&
+          @except_month_days.none? { |month, day| date.month == month && date.day == day } &&
+          !@except_dates.include?(date) &&
+          (@until.nil? || date <= @until) &&
+          (@starting.nil? || date >= @starting)
       end
-    end
 
-    def self.matches_month_target(target, d)
-      case target
-      when DaysTarget
-        expanded = Hron.expand_month_target(target)
-        expanded.include?(d.day)
-      when LastDayTarget
-        d == EvalHelpers.last_day_of_month(d.year, d.month)
-      when LastWeekdayTarget
-        d == EvalHelpers.last_weekday_of_month(d.year, d.month)
-      when NearestWeekdayTarget
-        target_date = EvalHelpers.nearest_weekday(d.year, d.month, target.day, target.direction)
-        target_date && d == target_date
-      when OrdinalWeekdayTarget
-        ordinal_date = if target.ordinal == OrdinalPosition::LAST
-          EvalHelpers.last_weekday_in_month(d.year, d.month, target.weekday)
-        else
-          EvalHelpers.nth_weekday_of_month(d.year, d.month, target.weekday, OrdinalPosition.to_n(target.ordinal))
-        end
-        ordinal_date && d == ordinal_date
-      else
-        false
+      def allows_month?(month)
+        @during.empty? || @during.include?(month)
       end
-    end
 
-    def self.matches_date_spec(date_spec, d)
-      case date_spec
-      when IsoDate
-        d == Date.parse(date_spec.date)
-      when NamedDate
-        d.month == MonthName.number(date_spec.month) && d.day == date_spec.day
-      else
-        false
+      def end_on(date)
+        @until = date if @until.nil? || date < @until
       end
-    end
-
-    def self.matches_year_target(target, d)
-      case target
-      when YearDateTarget
-        d.month == MonthName.number(target.month) && d.day == target.day
-      when YearOrdinalWeekdayTarget
-        return false if d.month != MonthName.number(target.month)
 
-        ordinal_date = if target.ordinal == OrdinalPosition::LAST
-          EvalHelpers.last_weekday_in_month(d.year, d.month, target.weekday)
-        else
-          EvalHelpers.nth_weekday_of_month(d.year, d.month, target.weekday,
-            OrdinalPosition.to_n(target.ordinal))
-        end
-        ordinal_date && d == ordinal_date
-      when YearDayOfMonthTarget
-        d.month == MonthName.number(target.month) && d.day == target.day
-      when YearLastWeekdayTarget
-        return false if d.month != MonthName.number(target.month)
-
-        d == EvalHelpers.last_weekday_of_month(d.year, d.month)
-      else
-        false
+      # The one-off except date farthest along direction: the calendar repeats only beyond
+      # it (spec/README.md, "Search horizon").
+      def farthest_except_date(direction)
+        direction.forward? ? @except_dates.max : @except_dates.min
       end
-    end
-
-    # Per-variant next functions
-    def self.next_day_repeat(interval, days, times, tz, anchor, now)
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-
-      if interval <= 1
-        if EvalHelpers.matches_day_filter(d, days)
-          candidate = EvalHelpers.earliest_future_at_times(d, times, tz, now)
-          return candidate if candidate
-        end
 
-        8.times do
-          d += 1
-          if EvalHelpers.matches_day_filter(d, days)
-            candidate = EvalHelpers.earliest_future_at_times(d, times, tz, now)
-            return candidate if candidate
-          end
+      def clamp(date, direction)
+        if direction.forward?
+          @starting ? [date, @starting].max : date
+        else
+          @until ? [date, @until].min : date
         end
-
-        return nil
-      end
-
-      # Interval > 1
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-      offset = EvalHelpers.days_between(anchor_date, d)
-      remainder = offset % interval
-      aligned_date = remainder.zero? ? d : d + (interval - remainder)
-
-      400.times do
-        candidate = EvalHelpers.earliest_future_at_times(aligned_date, times, tz, now)
-        return candidate if candidate
-
-        aligned_date += interval
       end
 
-      nil
-    end
-
-    def self.next_interval_repeat(interval, unit, from_time, to_time, day_filter, tz, now)
-      step_minutes = (unit == IntervalUnit::MIN) ? interval : interval * 60
-      from_minutes = (from_time.hour * 60) + from_time.minute
-      to_minutes = (to_time.hour * 60) + to_time.minute
-
-      # Convert now to local time in the target timezone
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-
-      400.times do
-        if day_filter && !EvalHelpers.matches_day_filter(d, day_filter)
-          d += 1
-          next
-        end
-
-        same_day = d == now_local.to_date
-        now_minutes = same_day ? (now_local.hour * 60) + now_local.min : -1
-
-        next_slot = if now_minutes < from_minutes
-          from_minutes
+      def ends_search?(date, direction)
+        if direction.forward?
+          !@until.nil? && date > @until
         else
-          elapsed = now_minutes - from_minutes
-          from_minutes + (((elapsed / step_minutes) + 1) * step_minutes)
+          !@starting.nil? && date < @starting
         end
+      end
 
-        # Try each slot within the day's window until we find one that exists
-        # This handles DST gaps where intermediate times don't exist
-        while next_slot <= to_minutes
-          h = next_slot / 60
-          m = next_slot % 60
-          candidate = EvalHelpers.at_time_on_date(d, TimeOfDay.new(h, m), tz)
-          return candidate if candidate && candidate > now
+      private
 
-          # Slot didn't exist (DST gap) or wasn't in the future, try next slot
-          next_slot += step_minutes
+      # A named until date is the first such date on or after the starting date, which a
+      # named until always has (spec/README.md, "Named `until`"). nil when the date never
+      # occurs, so nothing bounds the schedule.
+      def resolve_until(until_spec, starting)
+        case until_spec
+        when IsoUntil then Calendar.parse_date(until_spec.date)
+        when NamedUntil
+          month = MonthName.number(until_spec.month)
+          (0..NAMED_UNTIL_MAX_YEARS)
+            .filter_map { |k| Calendar.date(starting.year + k, month, until_spec.day) }
+            .find { |date| date >= starting }
         end
-
-        d += 1
       end
-
-      nil
     end
 
-    def self.next_week_repeat(interval, days, times, tz, anchor, now)
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_MONDAY
-
-      now_local = tz.utc_to_local(now.utc)
-      d = now_local.to_date
-      sorted_days = days.sort_by { |wd| Weekday.number(wd) }
+    class Cadence
+      attr_reader :unit
 
-      dow_offset = d.cwday - 1
-      current_monday = d - dow_offset
+      # Units in 400 years, after which the proleptic Gregorian calendar repeats.
+      PER_400_YEARS = {day: 146_097, week: 20_871, month: 4800, year: 400}.freeze
 
-      anchor_dow_offset = anchor_date.cwday - 1
-      anchor_monday = anchor_date - anchor_dow_offset
-
-      54.times do
-        weeks = EvalHelpers.weeks_between(anchor_monday, current_monday)
-
-        if weeks.negative?
-          # When weeks_since_anchor < 0, anchor_monday is in the future
-          # Use anchor_monday directly as the first aligned week
-          current_monday = anchor_monday
-          next
+      def self.of(expr, starting)
+        unit, interval, default_anchor = case expr
+        in SingleDateExpr[date: IsoDate[date:]] then return new(:day, Calendar.parse_date(date), 1, single: true)
+        in SingleDateExpr then [:year, 1, EPOCH_DATE]
+        in IntervalRepeat then [:day, 1, EPOCH_DATE]
+        in DayRepeat then [:day, expr.interval, EPOCH_DATE]
+        in WeekRepeat then [:week, expr.interval, EPOCH_MONDAY]
+        in MonthRepeat then [:month, expr.interval, EPOCH_DATE]
+        in YearRepeat then [:year, expr.interval, EPOCH_DATE]
         end
-
-        if (weeks % interval).zero?
-          sorted_days.each do |wd|
-            day_offset = Weekday.number(wd) - 1
-            target_date = current_monday + day_offset
-            candidate = EvalHelpers.earliest_future_at_times(target_date, times, tz, now)
-            return candidate if candidate
-          end
+        anchor = starting || default_anchor
+        origin = case unit
+        when :day then anchor
+        when :week then Calendar.monday_of_week(anchor)
+        when :month then Calendar.date(anchor.year, anchor.month, 1)
+        when :year then Calendar.first_of_year(anchor.year)
         end
-
-        remainder = weeks % interval
-        skip_weeks = remainder.zero? ? interval : interval - remainder
-        current_monday += skip_weeks * 7
+        new(unit, origin, interval)
       end
 
-      nil
-    end
-
-    def self.next_month_repeat(interval, target, times, tz, anchor, now, during = [])
-      now_local = tz.utc_to_local(now.utc)
-      year = now_local.year
-      month = now_local.month
-
-      anchor_date = anchor ? Date.parse(anchor) : EPOCH_DATE
-      max_iter = (interval > 1) ? 24 * interval : 24
-
-      # For NearestWeekday with direction, we need to apply the during filter here
-      # because the result can cross month boundaries
-      apply_during_filter = !during.empty? &&
-        target.is_a?(NearestWeekdayTarget) &&
-        !target.direction.nil?
-
-      max_iter.times do
-        # Check during filter for NearestWeekday with direction
-        if apply_during_filter && !during.any? { |mn| MonthName.number(mn) == month }
-          month += 1
-          if month > 12
-            month = 1
-            year += 1
-          end
-          next
-        end
-
-        if interval > 1
-          cur = Date.new(year, month, 1)
-          month_offset = EvalHelpers.months_between_ym(anchor_date, cur)
-          if month_offset.negative? || (month_offset % interval) != 0
-            month += 1
-            if month > 12
-              month = 1
-              year += 1
-            end
-            next
-          end
-        end
-
-        date_candidates = []
-
-        case target
-        when DaysTarget
-          expanded = Hron.expand_month_target(target)
-          last = EvalHelpers.last_day_of_month(year, month)
-          expanded.each do |day_num|
-            next unless day_num <= last.day
-
-            begin
-              date_candidates << Date.new(year, month, day_num)
-            rescue ArgumentError
-              # Invalid date
-            end
-          end
-        when LastDayTarget
-          date_candidates << EvalHelpers.last_day_of_month(year, month)
-        when LastWeekdayTarget
-          date_candidates << EvalHelpers.last_weekday_of_month(year, month)
-        when NearestWeekdayTarget
-          nw = EvalHelpers.nearest_weekday(year, month, target.day, target.direction)
-          date_candidates << nw if nw
-        when OrdinalWeekdayTarget
-          ordinal_date = if target.ordinal == OrdinalPosition::LAST
-            EvalHelpers.last_weekday_in_month(year, month, target.weekday)
-          else
-            EvalHelpers.nth_weekday_of_month(year, month, target.weekday, OrdinalPosition.to_n(target.ordinal))
-          end
-          date_candidates << ordinal_date if ordinal_date
-        end
-
-        best = nil
-        date_candidates.each do |dc|
-          candidate = EvalHelpers.earliest_future_at_times(dc, times, tz, now)
-          best = candidate if candidate && (best.nil? || candidate < best)
-        end
-        return best if best
+      def initialize(unit, origin, interval, single: false)
+        @unit = unit
+        @origin = origin
+        @interval = interval
+        @single = single
+        @origin_month = Calendar.month_index(origin)
+        # A nearest weekday can move a candidate into the calendar from the period on
+        # either side of it.
+        @earliest = period_of(Calendar::FIRST_DATE) - 1
+        @latest = period_of(Calendar::LAST_DATE) + 1
+      end
 
-        month += 1
-        if month > 12
-          month = 1
-          year += 1
+      def period_of(date)
+        case @unit
+        when :day then Calendar.days_between(@origin, date)
+        when :week then Calendar.days_between(@origin, date).div(7)
+        when :month then Calendar.month_index(date) - @origin_month
+        when :year then date.year - @origin.year
         end
       end
 
-      nil
-    end
-
-    def self.next_single_date(date_spec, times, tz, now)
-      case date_spec
-      when IsoDate
-        d = Date.parse(date_spec.date)
-        EvalHelpers.earliest_future_at_times(d, times, tz, now)
-      when NamedDate
-        now_local = tz.utc_to_local(now.utc)
-        start_year = now_local.year
-        8.times do |y|
-          year = start_year + y
-          begin
-            d = Date.new(year, MonthName.number(date_spec.month), date_spec.day)
-            candidate = EvalHelpers.earliest_future_at_times(d, times, tz, now)
-            return candidate if candidate
-          rescue ArgumentError
-            # Invalid date
-          end
+      def start_of(k)
+        case @unit
+        when :day then @origin + k
+        when :week then @origin + (k * 7)
+        when :month then Calendar.first_of_month(@origin_month + k)
+        when :year then Calendar.first_of_year(@origin.year + k)
         end
-        nil
       end
-    end
 
-    def self.next_year_repeat(interval, target, times, tz, anchor, now)
-      now_local = tz.utc_to_local(now.utc)
-      start_year = now_local.year
-      anchor_year = anchor ? Date.parse(anchor).year : EPOCH_DATE.year
+      # Walks one search horizon beyond whichever of first_period and reach is farther along
+      # direction (spec/README.md, "Search horizon").
+      def period_starts(first_period, reach, direction)
+        return yield @origin if @single
 
-      max_iter = (interval > 1) ? 8 * interval : 8
-
-      max_iter.times do |y|
-        year = start_year + y
-
-        if interval > 1
-          year_offset = year - anchor_year
-          next if year_offset.negative? || (year_offset % interval) != 0
-        end
+        first = align(first_period, direction)
+        beyond = direction.sign * (align(reach, direction) - first)
+        count = horizon_periods + HORIZON_MARGIN_PERIODS + ([beyond, 0].max / @interval)
+        # A walk starts inside the calendar, at now or a starting date, and ends at its edge.
+        far = direction.sign * ((direction.forward? ? @latest : @earliest) - first)
+        inside = 0...[(far / @interval) + 1, count].min
+        step = direction.sign * @interval
+        inside.each { |i| yield start_of(first + (i * step)) }
+      end
 
-        target_date = compute_year_target_date(target, year)
-        next unless target_date
+      private
 
-        candidate = EvalHelpers.earliest_future_at_times(target_date, times, tz, now)
-        return candidate if candidate
+      def align(k, direction)
+        direction.forward? ? k + (-k % @interval) : k - (k % @interval)
       end
 
-      nil
-    end
-
-    def self.compute_year_target_date(target, year)
-      case target
-      when YearDateTarget
-        Date.new(year, MonthName.number(target.month), target.day)
-      when YearOrdinalWeekdayTarget
-        if target.ordinal == OrdinalPosition::LAST
-          EvalHelpers.last_weekday_in_month(year, MonthName.number(target.month), target.weekday)
-        else
-          EvalHelpers.nth_weekday_of_month(year, MonthName.number(target.month), target.weekday,
-            OrdinalPosition.to_n(target.ordinal))
-        end
-      when YearDayOfMonthTarget
-        Date.new(year, MonthName.number(target.month), target.day)
-      when YearLastWeekdayTarget
-        EvalHelpers.last_weekday_of_month(year, MonthName.number(target.month))
+      # Aligned periods in lcm(400 years, interval units), after which both the calendar and
+      # the alignment repeat.
+      def horizon_periods
+        cycle = PER_400_YEARS.fetch(@unit)
+        cycle / cycle.gcd(@interval)
       end
-    rescue ArgumentError
-      nil
     end
+
+    private_constant :EPOCH_MONDAY, :EPOCH_DATE, :SUPPORTED_RANGE, :HORIZON_MARGIN_PERIODS, :MAX_SHIFT_DAYS, :NAMED_UNTIL_MAX_YEARS,
+      :Direction, :Search, :Occurrence, :Candidate, :DailyTimes, :Clauses, :Cadence,
+      :Calendar, :WallClock
   end
 end