acute 1.0.0

data/lib/acute/resolve/named.rb

@@ -0,0 +1,116 @@
+module Acute
+  module Resolve
+    # Named periods: parts of the day, weekends, seasons and holidays, each inside the period that holds one
+    module Named
+      DAY = Period::DAY
+      PART_POINT = Assumption.for(:part_of_day_point)
+      WEEKEND_FRIDAY = Assumption.for(:weekend_friday_evening)
+      SEASON = Assumption.for(:meteorological_season)
+
+      # D1, D35: start and end in seconds from the day's start, and the point
+      PARTS = Ractor.make_shareable({
+        morning: [6 * 3600, 12 * 3600, 9 * 3600], afternoon: [12 * 3600, 17 * 3600, 15 * 3600],
+        evening: [17 * 3600, 21 * 3600, 19 * 3600], night: [21 * 3600, 28 * 3600, 22 * 3600],
+        tonight: [17 * 3600, 28 * 3600, 22 * 3600], lunch: [12 * 3600, 14 * 3600, 12 * 3600 + 1800],
+        early_hours: [0, 4 * 3600, 2 * 3600] # D42
+      })
+      # D3: meteorological, by the month each starts in; the south is six months on
+      SEASONS = { spring: 3, summer: 6, autumn: 9, winter: 12 }.freeze
+      # D15, D28: each built-in holiday as a formula. [month, day] is a fixed date; [month, day, wday] the first
+      # wday on or after it (the third Monday of January is the first from the 15th); [holiday, days] an offset
+      # from Easter or another holiday
+      HOLIDAYS = Ractor.make_shareable({
+        new_years_day: [1, 1], groundhog_day: [2, 2], valentines: [2, 14], st_patricks: [3, 17], april_fools: [4, 1],
+        earth_day: [4, 22], flag_day: [6, 14], juneteenth: [6, 19], independence_day: [7, 4], patriot_day: [9, 11],
+        bosses_day: [10, 16], halloween: [10, 31], veterans_day: [11, 11], christmas_eve: [12, 24],
+        christmas: [12, 25], boxing_day: [12, 26], new_years_eve: [12, 31],
+        mlk_day: [1, 15, 1], presidents_day: [2, 15, 1], mothers_day: [5, 8, 0], memorial_day: [5, 25, 1],
+        fathers_day: [6, 15, 0], labor_day: [9, 1, 1], columbus_day: [10, 8, 1], thanksgiving: [11, 22, 4],
+        us_thanksgiving: [11, 22, 4], black_friday: [:us_thanksgiving, 1], cyber_monday: [:us_thanksgiving, 4],
+        easter: [:easter, 0], good_friday: [:easter, -2], easter_monday: [:easter, 1], palm_sunday: [:easter, -7],
+        maundy_thursday: [:easter, -3], ash_wednesday: [:easter, -46], mardi_gras: [:easter, -47],
+        pentecost: [:easter, 49], whit_monday: [:easter, 50], trinity_sunday: [:easter, 56],
+        # D40, D48: the Tuesday after the first Monday; the Wednesday of April's last full week
+        election_day: [11, 2, 2], admin_day: [4, 21, 3], grandparents_day: [:labor_day, 6],
+        military_spouse_day: [:mothers_day, -2], lincolns_birthday: [2, 12], law_day: [5, 1], loyalty_day: [5, 1],
+        may_day: [5, 1], workers_day: [5, 1], siblings_day: [4, 10], world_vegan_day: [11, 1], kwanzaa: [12, 26],
+        ides_of_march: [3, 15], leap_day: [2, 29]
+      })
+      # D48: a holiday of several days names its first, then all of them
+      LASTS = { kwanzaa: 7 }.freeze
+      # D15, D27: the holidays a country has its own way, or alone
+      GB_IE = { mothers_day: [:easter, -21], mothering_sunday: [:easter, -21], may_day: [5, 1, 1] }.freeze
+      LOCAL = Ractor.make_shareable({
+        "CA" => { thanksgiving: [10, 8, 1], canada_day: [7, 1], victoria_day: [5, 18, 1], vimy_ridge_day: [4, 9] },
+        "AU" => { australia_day: [1, 26], anzac_day: [4, 25], melbourne_cup: [11, 1, 2] },
+        "NZ" => { anzac_day: [4, 25] }, "GB" => { **GB_IE, guy_fawkes: [11, 5] }, "IE" => GB_IE,
+        "ZA" => { reconciliation_day: [12, 16], kruger_day: [10, 10] }, "PH" => { rizal_day: [12, 30] },
+        "TT" => { indian_arrival_day: [5, 30] }, "BZ" => { garifuna_day: [11, 19] }
+      })
+
+      def self.part(name, day, ctx)
+        b, e, point = PARTS.fetch(name)
+        ctx.note(PART_POINT)
+        Span.new(day * DAY + b, day * DAY + e, :hour, day * DAY + point)
+      end
+
+      # D8: Saturday 00:00 to Monday 00:00, then from Friday 18:00
+      def self.weekends(week, ctx)
+        sat = week.b + ((6 - ctx.week_start) % 7) * DAY
+        ctx.note(WEEKEND_FRIDAY)
+        [Span.new(sat, sat + 2 * DAY, :weekend, nil), Span.new(sat - 6 * 3600, sat + 2 * DAY, :weekend, nil)]
+      end
+
+      # D48: "labor day weekend": the weekend nearest the holiday, the one before from Monday to Wednesday, and the
+      # holiday with it when it is a Monday or Friday
+      def self.long_weekend(h, ctx)
+        d = h.b / DAY
+        wd = (d + 4) % 7
+        sat = (d + (wd == 0 ? -1 : wd <= 3 ? -1 - wd : 6 - wd)) * DAY
+        e = [sat + 2 * DAY, h.e].max
+        return [Span.new(h.b, e, :weekend, nil)] if h.b < sat
+        ctx.note(WEEKEND_FRIDAY)
+        [Span.new(sat, e, :weekend, nil), Span.new(sat - 6 * 3600, e, :weekend, nil)]
+      end
+
+      # D3, D33: a season belongs to the year it starts in
+      def self.season(name, year, ctx)
+        m = SEASONS.fetch(name)
+        m = (m + 5) % 12 + 1 if ctx.south
+        ctx.note(SEASON)
+        b = Period.civil(year, m, 1)
+        Span.new(b, Period.add(b, 3, :month), :season, nil)
+      end
+
+      # D15, D28: the holiday in the year, or nil when the locale has none of that name. D47: a holidays: given
+      # is asked first
+      def self.holiday(name, year, ctx)
+        if (given = ctx.holidays) && (date = given.named(name, year))
+          d = date.jd - 2_440_588
+          return Span.new(d * DAY, d * DAY + DAY, :day, nil)
+        end
+        if name == :leap_year # D48: named like a holiday, the whole of a year with a 29 February
+          return unless Calendar.leap?(year)
+          return Span.new(Period.civil(year, 1, 1), Period.civil(year + 1, 1, 1), :year, nil)
+        end
+        f = (own = LOCAL[ctx.locale.country]) && own[name] || HOLIDAYS[name]
+        return unless f
+        return if f[1] == 29 && f[0] == 2 && !Calendar.leap?(year) # D48: no leap day in a common year
+        d = day_of(f, year)
+        Span.new(d * DAY, d * DAY + DAY, :day, nil)
+      end
+
+      def self.day_of(f, year)
+        a, b, wday = f
+        if Integer === a
+          wday ? nth_weekday(Calendar.days_from_civil(year, a, b), wday, 1) : Calendar.days_from_civil(year, a, b)
+        elsif a == :easter then Calendar.easter(year) + b
+        else day_of(HOLIDAYS.fetch(a), year) + b
+        end
+      end
+
+      # The day number of the nth wday on or after the day first; (first + 4) % 7 is its weekday
+      def self.nth_weekday(first, wday, n) = first + (wday - (first + 4) % 7) % 7 + 7 * (n - 1)
+    end
+  end
+end

data/lib/acute/resolve/nth.rb

@@ -0,0 +1,47 @@
+module Acute
+  module Resolve
+    module Periodic
+      # "second tuesday of march", "last friday of the month", "Q3", "first day of next month"
+      def self.nth(node, s, ctx)
+        n = node.n
+        x = node.node
+        out = case x
+              when G::Weekday
+                # the nth wday from the first day, or the last one back from the last day; (d + 4) % 7 is d's weekday
+                if n > 0
+                  d = s.b / DAY
+                  d += (x.wday - (d + 4) % 7) % 7 + 7 * (n - 1)
+                else
+                  d = s.e / DAY - 1
+                  d -= (d + 4 - x.wday) % 7 - 7 * (n + 1) # D48: "second last friday"
+                end
+                b = d * DAY
+                return b >= s.b && b + DAY <= s.e ? [Span.new(b, b + DAY, :day, nil)] : []
+              when G::Weekend
+                if n > 0
+                  sat = Named.nth_weekday(Period.day(s.b), 6, n)
+                else
+                  sat = s.e / DAY - 1
+                  sat -= (sat - 2) % 7 - 7 * (n + 1) # (sat + 4 - 6) % 7: days back to a Saturday
+                end
+                # D44: the weekend whose Saturday is in the period, though it ends after it
+                return [] unless sat * DAY >= s.b && sat * DAY < s.e
+                return Named.weekends(Period.span(:week, ctx, Period.index(:week, ctx, sat * DAY)), ctx)
+              else
+                unit = x.unit
+                if unit == :business_day # D44: the nth weekday, or the last
+                  b = n > 0 ? Period.business(s.b - DAY, n, ctx) : Period.business(s.e, n, ctx)
+                  [Span.new(b, b + DAY, :day, nil)]
+                elsif Period::DAYS[unit]
+                  b = n > 0 ? s.b + (n - 1) * Period::DAYS[unit] * DAY : s.e + n * Period::DAYS[unit] * DAY
+                  [Span.new(b, b + Period::DAYS[unit] * DAY, unit, nil)]
+                else
+                  b = n > 0 ? Period.add(s.b, n - 1, unit) : Period.add(s.e, n, unit)
+                  [Span.new(b, Period.add(b, 1, unit), unit, nil)]
+                end
+              end
+        out.select { |o| o.b >= s.b && o.e <= s.e }
+      end
+    end
+  end
+end

data/lib/acute/resolve/period.rb

@@ -0,0 +1,160 @@
+module Acute
+  module Resolve
+    # Calendar periods and unit arithmetic on local wall seconds
+    module Period
+      DAY = 86_400
+      SECONDS = { second: 1, minute: 60, hour: 3600 }.freeze
+      MONTHS = { month: 1, quarter: 3, season: 3, year: 12, decade: 120, century: 1200 }.freeze
+      DAYS = { day: 1, week: 7, fortnight: 14 }.freeze
+
+      def self.day(t) = t / DAY
+
+      def self.ymd(t) = Calendar.civil_from_days(t / DAY)
+
+      def self.year(t) = Calendar.year_of(t / DAY)
+
+      def self.civil(y, m, d) = Calendar.days_from_civil(y, m, d) * DAY
+
+      # Months since year 0, so a month is one Integer
+      def self.month_index(t)
+        p = ymd(t)
+        (p / 10_000) * 12 + p / 100 % 100 - 1
+      end
+
+      def self.month_start(i) = civil(i / 12, i % 12 + 1, 1)
+
+      # The first day (a day number) of the week holding day d, for a week starting on week_start
+      def self.week_first(d, week_start) = d - (Calendar.weekday(d) - week_start) % 7
+
+      # A cycle is how often a periodic phrase repeats: :day, :week, :month or :year. Index i counts cycles.
+      def self.index(cycle, ctx, t)
+        case cycle
+        when :day then day(t)
+        when :week then (day(t) - ctx.week_start + 4) / 7
+        when :month then month_index(t)
+        else Calendar.year_of(t / DAY)
+        end
+      end
+
+      def self.span(cycle, ctx, i)
+        case cycle
+        when :day then Span.new(i * DAY, (i + 1) * DAY, :day, nil)
+        when :week
+          b = (i * 7 + ctx.week_start - 4) * DAY
+          Span.new(b, b + 7 * DAY, :week, nil)
+        when :month then Span.new(month_start(i), month_start(i + 1), :month, nil)
+        else
+          y = i - 1 # Calendar.year_start, inline
+          b = 365 * y + y / 4 - y / 100 + y / 400 - 719_162
+          Span.new(b * DAY, (b + (i % 4 == 0 && (i % 100 != 0 || i % 400 == 0) ? 366 : 365)) * DAY, :year, nil)
+        end
+      end
+
+      # The calendar unit holding t
+      def self.unit(unit, ctx, t)
+        case unit
+        when :second, :minute, :hour
+          len = SECONDS[unit]
+          b = t - t % len
+          Span.new(b, b + len, unit, nil)
+        when :day, :business_day then span(:day, ctx, day(t))
+        when :week, :fortnight then span(:week, ctx, index(:week, ctx, t))
+        when :month then span(:month, ctx, month_index(t))
+        else
+          n = MONTHS[unit]
+          i = month_index(t)
+          i -= unit == :season ? (i + 1) % 3 : i % n # D33: seasons start in December, March, June and September
+          Span.new(month_start(i), month_start(i + n), unit, nil)
+        end
+      end
+
+      # t moved by n units (D23: Temporal arithmetic, so jan 31 + 1 month is feb 28). ctx only for business days.
+      def self.add(t, n, unit, ctx = nil)
+        if (s = SECONDS[unit]) then t + n * s
+        elsif (d = DAYS[unit]) then t + n * d * DAY
+        elsif unit == :business_day then business(t, n, ctx)
+        else
+          p = ymd(t)
+          y = p / 10_000
+          m = p / 100 % 100
+          i = y * 12 + m - 1 + n * MONTHS[unit]
+          y = i / 12
+          m = i % 12 + 1
+          d = p % 100
+          last = Calendar.days_in_month(y, m)
+          civil(y, m, d < last ? d : last) + t % DAY
+        end
+      end
+
+      LIMIT = 10_000
+      class Limit < StandardError; end
+
+      # D49: what one call may still count, shared by every count in it (T17): LIMIT business days in all, and
+      # LIMIT days a business_days: calendar says aren't. It holds the calendar too, so a holidays-gem year is
+      # looked up once a call.
+      class Budget
+        attr_accessor :days, :skips, :workdays
+
+        def initialize
+          @days = @skips = LIMIT
+        end
+      end
+
+      # D17: Monday to Friday, or D47: the days business_days: or holidays: give; D38: the time of day is kept.
+      # D49: past the call's Budget is a failure.
+      def self.business(t, n, ctx)
+        return t if n == 0
+        budget = ctx.budget
+        raise Limit if n.abs > budget.days
+        budget.days -= n.abs
+        d = t / DAY
+        days = ctx.business_days
+        to = case days
+             when nil then Calendar.add_weekdays(d, n)
+             when Holidays::RegionDays then days.add(d, n)
+             else step(d, n, days, budget)
+             end
+        t + (to - d) * DAY
+      end
+
+      # A business_days: calendar, or holidays: that only answer holiday?, are asked day by day
+      def self.step(d, n, days, budget)
+        step = n < 0 ? -1 : 1
+        n.abs.times do
+          d += step
+          until days.business_day?(::Date.jd(d + 2_440_588))
+            raise Limit if (budget.skips -= 1) < 0
+            d += step
+          end
+        end
+        d
+      end
+
+      # D40: "half a year" is 6 months; a fraction becomes a whole count of the next smaller unit
+      SMALLER = Ractor.make_shareable({ year: [:month, 12], quarter: [:month, 3], season: [:month, 3], month: [:day, 30], fortnight: [:day, 14],
+                                        week: [:day, 7], day: [:hour, 24], hour: [:minute, 60], minute: [:second, 60] })
+
+      def self.whole(count, unit)
+        while count.is_a?(Rational) && count.denominator != 1 && (smaller = SMALLER[unit])
+          unit, k = smaller
+          count *= k
+        end
+        [count.to_i, unit]
+      end
+
+      # D17, D38: only with fiscal_year_start:, and FY27 is the year ending in 2027; "next fiscal year" is the
+      # one after the fiscal year holding today
+      def self.fiscal(node, ctx, shift = nil)
+        start = ctx.fiscal_year_start
+        return [] unless start
+        if shift
+          ym = ymd(ctx.now_local) / 100
+          y = ym / 100 + shift - (ym % 100 < start ? 1 : 0)
+        else
+          y = start == 1 ? node.year : node.year - 1
+        end
+        Span.new(civil(y, start, 1), civil(y + 1, start, 1), :year, nil).then { [_1] }
+      end
+    end
+  end
+end

data/lib/acute/resolve/periodic.rb

@@ -0,0 +1,274 @@
+module Acute
+  module Resolve
+    # Phrases that repeat: "friday" weekly, "the 3rd" monthly, "march 3" and "christmas" yearly, "tonight"
+    # daily. Each is found as an occurrence in one cycle (a week, month, year or day), so every rule about
+    # which occurrence is meant (D11, D20, D21, D32, D40) is written once, here and in rel.rb.
+    module Periodic
+      DAY = Period::DAY
+      LIMIT = 12 # cycles to search; enough for "feb 29"
+      SAME_DAY = Assumption.for(:same_day_or_next)
+      SAME_DAY_PASSED = Assumption.for(:same_day_passed)
+      SEASON_YEAR = Assumption.for(:season_year)
+      SAME_OR_NEXT = [0, DAY].freeze
+      SUB_DAY = { G::Clock => true, G::Part => true, G::Range => true, G::Fuzzy => true }.freeze # "friday early evening"
+
+      def self.cycle(node)
+        case G::KIND[node.class]
+        when :weekday, :weekend then :week
+        when :date then node.year || node.sep ? nil : node.month ? :year : :month
+        when :holiday, :season, :iso_week then :year
+        when :part, :clock then :day
+        when :nth then G::Unit === node.node && (node.node.unit == :quarter || node.node.unit == :month) ? :year : :month
+        when :within then cycle(node.outer)
+        when :fuzzy then cycle(node.node)
+        end
+      end
+
+      # The occurrences in cycle i, the main one first; empty when there is none ("feb 29" in 2027)
+      def self.at(node, ctx, i, cyc = cycle(node))
+        inside(node, nil, Period.span(cyc, ctx, i), ctx)
+      end
+
+      # D11, D23: the current one if it isn't over, else the next; in past context the latest that has begun
+      def self.bare(node, ctx, cyc = cycle(node))
+        return [] unless cyc
+        now = ctx.now_local
+        i = Period.index(cyc, ctx, now)
+        # The cycles either side of now's are looked at only when an occurrence there can reach into it
+        near = contained?(node) ? 0 : 1
+        # The weekday or day of the month, under any time or part of day; (today + 4) % 7 is today's weekday
+        if cyc == :week || cyc == :month
+          day = node
+          day = day.outer while G::Within === day && SUB_DAY[day.inner.class]
+          today = cyc == :week ? G::Weekday === day && (ctx.today + 4) % 7 == day.wday :
+                    G::Date === day && day.day == Calendar.civil_from_days(ctx.today) % 100
+          return on_that_day(node, ctx, i, cyc) if today && ctx.past != :back
+          # A weekday already gone this week (or, looking back, still to come) can't hold the occurrence
+          if near == 0 && !today && G::Weekday === day
+            w = i * 7 + ctx.week_start - 4 # the week's first day
+            d = w + (day.wday - w - 4) % 7
+            i += ctx.past? ? (d > ctx.today ? -1 : 0) : (d < ctx.today ? 1 : 0)
+          end
+        elsif cyc == :year && near == 0
+          # The same for a month already gone this year
+          d = node
+          d = d.outer while G::Within === d
+          if G::Date === d && (m = d.month)
+            cur = Period.ymd(now) / 100 % 100
+            i += ctx.past? ? (m > cur ? -1 : 0) : (m < cur ? 1 : 0)
+          end
+        end
+        if ctx.past?
+          list = last(node, ctx, i + near, cyc) { |s| s.b <= now }
+          # D44: in past context, a period under way is the current one, then the one before
+          if ctx.past == true && !list.empty? && list[0].e > now
+            b = list[0].b
+            list += last(node, ctx, Period.index(cyc, ctx, b) - 1, cyc) { |s| s.b < b }.take(1)
+          end
+          return list
+        end
+        list = first(node, ctx, i - near, cyc) { |s| s.e > now }
+        # D40, D41: "tonight" said at exactly 00:00 is the rest of the night under way, then the coming one
+        if now % DAY == 0 && G::Part === node && node.name == :tonight && !list.empty? && list[0].b < now
+          return [Span.new(now, list[0].e, list[0].grain, nil), *at(node, ctx, i, cyc)]
+        end
+        list
+      end
+
+      # D40, D44: a weekday or a day of the month said on that day, with or without a time: today's, then the
+      # next one (in past context the one before); today's comes second once it is over
+      def self.on_that_day(node, ctx, i, cyc)
+        cur = at(node, ctx, i, cyc)
+        if ctx.past?
+          other = last(node, ctx, i - 1, cyc) { true }.take(1)
+          return other if cur.empty?
+          today_first = cur[0].b <= ctx.now_local
+        else
+          other = first(node, ctx, i + 1, cyc) { true }
+          return other if cur.empty?
+          other = other.take(1) if cur.size == 1
+          today_first = cur[0].e > ctx.now_local
+        end
+        ctx.note(today_first ? SAME_DAY : SAME_DAY_PASSED)
+        today_first ? cur + other : other + cur
+      end
+
+      # The first occurrence from cycle i on whose main reading passes the block
+      # A while loop: a return from inside a block would unwind through it, which costs more than the search
+      def self.first(node, ctx, i, cyc = cycle(node), &)
+        stop = i + LIMIT
+        while i < stop
+          list = at(node, ctx, i, cyc)
+          return list if !list.empty? && yield(list[0])
+          return [] if list.empty? && !skips?(node) && !passed_over?(node, ctx, i, cyc, &)
+          i += 1
+        end
+        []
+      end
+
+      # Whether every occurrence lies inside its own cycle
+      def self.contained?(node)
+        case G::KIND[node.class]
+        when :weekday, :date, :holiday, :nth then true
+        when :clock then node.named != :midnight
+        when :within then contained?(node.inner) && contained?(node.outer)
+        else false
+        end
+      end
+
+      # D42: only a date skips the cycles it doesn't exist in ("feb 29", "the 31st"); "5th tuesday in may" is
+      # nil, not a later May that has one
+      def self.skips?(node) = G::Date === node || G::IsoWeek === node || (G::Within === node && skips?(node.inner)) ||
+                              (G::Holiday === node && LEAP[node.name]) # D48
+      LEAP = { leap_day: true, leap_year: true }.freeze
+
+      # D37: a weekday with a date filters the date's own occurrence, so a cycle whose date falls on another
+      # weekday is passed over only when the date's occurrence there would be
+      def self.passed_over?(node, ctx, i, cyc)
+        date = unfiltered(node)
+        return false if date.equal?(node)
+        list = inside(date, nil, Period.span(cyc, ctx, i), ctx)
+        !list.empty? && !yield(list[0])
+      end
+
+      def self.unfiltered(node)
+        return node unless G::Within === node
+        return node.outer if G::Weekday === node.inner && G::Date === node.outer
+        outer = unfiltered(node.outer)
+        outer.equal?(node.outer) ? node : G::Within.new(node.inner, outer)
+      end
+
+      # The latest occurrence at or before cycle i whose main reading passes the block
+      def self.last(node, ctx, i, cyc = cycle(node), &)
+        stop = i - LIMIT
+        while i > stop
+          list = at(node, ctx, i, cyc)
+          return list if !list.empty? && yield(list[0])
+          return [] if list.empty? && !skips?(node) && !passed_over?(node, ctx, i, cyc, &)
+          i -= 1
+        end
+        []
+      end
+
+      # The readings of node inside the span s; outer is the node s came from, which a clock needs to see a
+      # part of day
+      def self.inside(node, outer, s, ctx)
+        case G::KIND[node.class]
+        when :within
+          outers = inside(node.outer, outer, s, ctx)
+          return inside(node.inner, node.outer, outers[0], ctx) if outers.size == 1
+          outers.flat_map { |o| inside(node.inner, node.outer, o, ctx) }
+        when :clock then clock(node, outer, s, ctx)
+        when :weekday
+          d = s.b / DAY
+          d += (node.wday - (d + 4) % 7) % 7 # (d + 4) % 7: d's weekday
+          d * DAY < s.e ? [Span.new(d * DAY, d * DAY + DAY, :day, nil)] : []
+        when :date then date(node, s, ctx)
+        when :part then [Named.part(node.name, Period.day(s.b), ctx)]
+        when :weekend
+          return Named.long_weekend(s, ctx) if G::Holiday === outer
+          week = s.grain == :week ? s : Period.span(:week, ctx, Period.index(:week, ctx, s.b))
+          Named.weekends(week, ctx)
+        when :holiday
+          return [] unless (h = Named.holiday(node.name, Period.year(s.b), ctx))
+          list = within(h, s)
+          n = Named::LASTS[node.name]
+          n && !list.empty? ? [*list, Span.new(h.b, h.b + n * DAY, :day, nil)] : list
+        when :season
+          y = Period.year(s.b)
+          list = within(Named.season(node.name, y, ctx), s)
+          return list unless G::Date === outer && s.grain == :year
+          # D3: "winter 2026" is the one starting in 2026, then the one ending in it
+          before = Named.season(node.name, y - 1, ctx)
+          return list unless before.e > s.b
+          ctx.note(SEASON_YEAR)
+          list << before
+        when :nth then nth(node, s, ctx)
+        when :iso_week then iso_week(node, Period.year(s.b))
+        when :range then Ranges.inside(node, outer, s, ctx)
+        when :fuzzy then inside(node.node, outer, s, ctx).flat_map { |x| Fuzzy.apply(node.pos, x, node.node, ctx) }
+        else Resolve.spans(node, ctx).select { |x| x.b >= s.b && x.b < s.e }
+        end
+      end
+
+      # D13: the ISO week of year y, which may start in December before it; week 53 only in a year that has one
+      def self.iso_week(node, y)
+        d = Calendar.iso_week_one(y) + 7 * (node.week - 1)
+        return [] if node.week == 53 && d == Calendar.iso_week_one(y + 1)
+        return [Span.new(d * DAY, d * DAY + 7 * DAY, :week, nil)] unless node.day
+        d += node.day - 1
+        [Span.new(d * DAY, d * DAY + DAY, :day, nil)]
+      end
+
+      def self.within(x, s) = x.b >= s.b && x.b < s.e ? [x] : []
+
+      def self.date(node, s, ctx)
+        return Dates.orders(node, ctx).flat_map { |d| date(d, s, ctx) } if node.sep
+        # A year from January 1st (a cycle, not a fiscal year) needs no civil date
+        if s.grain == :year && (y = Calendar.year_if_first(s.b / DAY))
+          y = node.year || y
+          m = node.month || 1
+        else
+          p = Period.ymd(s.b)
+          y = node.year || p / 10_000
+          m = node.month || p / 100 % 100
+        end
+        if node.day
+          return [] unless m >= 1 && m <= 12 && node.day >= 1 && (node.day <= 28 || node.day <= Calendar.days_in_month(y, m))
+          b = Calendar.days_from_civil(y, m, node.day) * DAY
+          b >= s.b && b < s.e ? [Span.new(b, b + DAY, :day, nil)] : []
+        elsif node.month
+          return [] unless m >= 1 && m <= 12
+          b = Calendar.days_from_civil(y, m, 1) * DAY
+          b >= s.b && b < s.e ? [Span.new(b, b + (m == 2 ? Calendar.days_in_month(y, m) : Calendar::MONTH_DAYS[m]) * DAY, :month, nil)] : []
+        else
+          within(Span.new(Calendar.year_start(y) * DAY, Calendar.year_start(y + 1) * DAY, :year, nil), s)
+        end
+      end
+
+      # D4, D6 for a clock inside a day; D35, D40 inside a part of the day
+      def self.clock(c, outer, s, ctx)
+        cands = Clock.candidates(c, ctx, true)
+        grain, len = Clock.grain(c)
+        day = s.b - s.b % DAY
+        part = part_name(outer)
+        # D6: midnight "at the start of" a day is its first moment, "at the end of" its last
+        cands = [outer.pos == :start ? 0 : 86_400] if c.named == :midnight && G::Fuzzy === outer && (outer.pos == :start || outer.pos == :end)
+        unless part
+          return [Span.new(day + cands[0], day + cands[0] + len, grain, nil)] if cands.size == 1
+          return cands.map { |secs| Span.new(day + secs, day + secs + len, grain, nil) }
+        end
+        if c.hour == 12 && !c.meridiem && !c.named # D30, D40: 12 in the morning, 12 at night
+          secs = c.min * 60 + c.sec
+          cands = [secs + (part == :morning ? 0 : part == :afternoon || part == :lunch ? 43_200 : 86_400)]
+        elsif !c.meridiem && part != :night && part != :tonight && part != :lunch
+          # D40: the part fixes am or pm, even for a time written with seconds; D35: lunch takes the closer
+          pm = part != :morning && part != :early_hours
+          cands = [c.hour * 3600 + c.min * 60 + c.sec + (pm ? 43_200 : 0)] if !c.h24 && c.hour >= 1 && c.hour <= 11
+          fixed = cands.select { |x| (x >= 43_200) == pm }
+          cands = fixed unless fixed.empty?
+        end
+        best = nil
+        best_gap = nil
+        cands.each do |secs|
+          SAME_OR_NEXT.each do |k| # the next day too, for a part that runs past midnight
+            t = day + k + secs
+            gap = t < s.b ? s.b - t : t >= s.e ? t - s.e : -1
+            next if best_gap && gap >= best_gap
+            best = t
+            best_gap = gap
+          end
+        end
+        [Span.new(best, best + len, grain, nil)]
+      end
+
+      def self.part_name(node)
+        case node
+        when G::Part then node.name
+        when G::Rel, G::Fuzzy then part_name(node.node)
+        when G::Within then part_name(node.inner)
+        end
+      end
+    end
+  end
+end