sof-cycle 0.1.14 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bf300b22d76c7736f524022360c052b1546fa573ca39e851d4ce2a2ec2de4b7
-  data.tar.gz: 30f5a7972655d52acd3a547f59482c32d6c8fbdf22711f9f23eca27e695053cf
+  metadata.gz: ace7e7bdb57808f1c633cf78aaab4fc7949e6820e86089c283926e0c22558bbd
+  data.tar.gz: 5c12b7d8d840f2afe367d13cc7e5864fd835d62e2f0b9bc480d17873e706182c
 SHA512:
-  metadata.gz: 63208d5574eaf86293c0a39214155f7a645b74d51b2dd23bfd03ae83b9dcbd032d145ffd909a8b3a675caef7485f6abe14d5b4bbfcbaafac3c383e29193fa8a7
-  data.tar.gz: e4caecf602ea58c7b0cec5a27b1efe36e23b65d0cf191b9c71eb7415e75a01c05079d4783c75d69e02d1ed31da76ef2765a15bc93ee84d43b39c8f03d615a17d
+  metadata.gz: d1c8dda915931d2a5cd860ebf1ad79d2c6cc353d8794a159cc52720bde02f2e3e3aa7001fbb7af240dbf16c1b212f44ce28eacb7ec10fa1868dd47c7860406ae
+  data.tar.gz: ea2ca6604e38d85894d0df757010449f839040b28c01de608270cdffc536ed5f8e62125ecea7ec59f9100106eae6a3ab2a3243b68b4218a7269b671f483e9bad

data/CHANGELOG.md

@@ -5,18 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.14] - 2026-04-27
-
-## [0.1.13] - 2026-03-20
-
-### Added
-
-- Interval cycle kind (`I` notation) — repeating windows anchored to a from_date that re-anchor from completion date (e.g., `V1I24MF2026-03-31`)
+## [0.1.15] - 2026-07-27
 
-### Changed
-
-- Dormant capability is now declared on each cycle class (`def self.dormant_capable? = true`) instead of only in `Parser.dormant_capable_kinds`
-
-### Fixed
-
-- EndOf cycle `final_date` was off by one period — `V1E12M` now correctly expires at the end of the 12th month, not the 11th
+## [0.1.14] - 2026-04-27

data/checksums/sof-cycle-0.1.13.gem.sha512

@@ -0,0 +1 @@
+bb21b935b95e99c2616c397155c6354976d343e669c34a7c36a319c495bdfda5b3a24c5d6042d891672215f90e405703a3ee24f79623e129c17bdd9967190a29

data/checksums/sof-cycle-0.1.14.gem.sha512

@@ -0,0 +1 @@
+33dfd415ab31a635f8af0e515187f22f958227d26cf9c27f087dccc03c4c8ff4b7c38f9f303f5f134597b652aafe8363d8683d82ccb93492e3bb4310f218f50d

data/checksums/sof-cycle-0.1.3.gem.sha512

@@ -0,0 +1 @@
+0c1dbd71ae4ba8c8dd68e6285acd567ebe5f715c88a6a25c16e9abc1baa48a02618e006a5b1234b0d2c97bacdef53d1a0deb0691a8659474eeb9304c95764289

data/checksums/sof-cycle-0.1.4.gem.sha512

@@ -0,0 +1 @@
+8692e06774fdb76269fa438824887f87991703885a2cf2cb7dc5bd77ba44b2e0ddce1a78c40e5411da8be2b88dfb0c875900b42f8a784a4060db7d4f4c4d4f1b

data/checksums/sof-cycle-0.1.5.gem.sha512

@@ -0,0 +1 @@
+7c06ae8b1c4eaafac55f16143c7f60b4ce3c613a83d75859e2f798e850a90190d1f26109057e349c42f03fcce8c0f81a85904bab3ca96877b60c27ad52ee1517

data/lib/sof/cycle/parser.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../cycle"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/inclusion"
+require "active_support/core_ext/hash/reverse_merge"
+require "active_support/isolated_execution_state"
+
+module SOF
+  class Cycle
+    # This class is not intended to be referenced directly.
+    # This is an internal implementation of Cycle behavior.
+    class Parser
+      extend Forwardable
+
+      # Built from the registry rather than written out, so an application
+      # that declares its own kind has its notation recognised too. Rebuilt
+      # whenever a class registers; cached in between, since parsing is hot.
+      def self.parts_regex
+        pattern = [Cycle.registry.notation_pattern, Cycle::TimeSpan.period_registry.code_pattern]
+        return @parts_regex if @parts_regex && @parts_regex_pattern == pattern
+
+        @parts_regex_pattern = pattern
+        kinds, periods = pattern
+        @parts_regex = /
+          ^(?<vol>V(?<volume>\d*))? # optional volume
+          (?<set>(?<kind>#{kinds}) # kind
+          (?<period_count>\d+) # period count
+          (?<period_key>#{periods})?)? # period_key
+          (?<from>F(?<from_date>\d{4}-\d{2}-\d{2}))?$ # optional from
+        /ix
+      end
+
+      # Deliberately a method, not a constant: handlers register as each file
+      # in sof/cycles loads, which happens after this file. A constant would
+      # capture the empty set and leave every dormant-capable kind
+      # unrecognized.
+      def self.dormant_capable_kinds
+        Cycle.registry.cycle_classes.select(&:dormant_capable?).map(&:notation_id).compact.freeze
+      end
+
+      def self.for(notation_or_parser)
+        return notation_or_parser if notation_or_parser.is_a? self
+
+        new(notation_or_parser)
+      end
+
+      def self.load(hash)
+        hash.symbolize_keys!
+        hash.reverse_merge!(volume: 1)
+        keys = %i[volume kind period_count period_key]
+        str = "V#{hash.values_at(*keys).join}"
+        return new(str) unless hash[:from_date]
+
+        new([str, "F#{hash[:from_date]}"].join)
+      end
+
+      def initialize(notation)
+        @notation = notation&.upcase
+        @match = @notation&.match(self.class.parts_regex)
+        @time_span = nil
+      end
+
+      attr_reader :match, :notation
+
+      delegate [:dormant_capable_kinds] => "self.class"
+      delegate [:period, :humanized_period] => :time_span
+
+      # Return a TimeSpan object for the period and period_count
+      def time_span
+        @time_span ||= TimeSpan.for(period_count, period_key)
+      end
+
+      def valid? = match.present?
+
+      def inspect = notation
+      alias_method :to_s, :inspect
+
+      def activated_notation(date)
+        return notation unless dormant_capable?
+
+        self.class.load(to_h.merge(from_date: date.to_date)).notation
+      end
+
+      def ==(other) = other.to_h == to_h
+
+      def to_h
+        {
+          volume:,
+          kind:,
+          period_count:,
+          period_key:,
+          from_date:
+        }
+      end
+
+      def parses?(notation_id) = kind == notation_id
+
+      def active? = !dormant?
+
+      def dormant? = dormant_capable? && from_date.nil?
+
+      def dormant_capable? = kind.in?(dormant_capable_kinds)
+
+      def period_count = match[:period_count]
+
+      def period_key = match[:period_key]
+
+      def vol = match[:vol] || "V1"
+
+      def volume = (match[:volume] || 1).to_i
+
+      def from_data
+        return {} unless from
+
+        {from: from}
+      end
+
+      def from_date = match[:from_date]
+
+      def from = match[:from]
+
+      def kind = match[:kind]
+    end
+  end
+end

data/lib/sof/cycle/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SOF
+  class Cycle
+    # The set of classes that handle cycle kinds.
+    #
+    # Registration is explicit — a class joins by declaring what it handles
+    # (see Cycle.handles), not by subclassing. Inheriting from Cycle for any
+    # other reason, such as a test double or an abstract intermediate, then
+    # carries no hidden side effect.
+    #
+    # The registry is also what the parser reads to recognise notations, so an
+    # application can add a kind of its own and have its notation parse without
+    # reopening this gem.
+    class Registry
+      def self.instance = @instance ||= new
+
+      def initialize
+        @cycle_classes = []
+        @notation_pattern = nil
+      end
+
+      # Add a handler, displacing any already handling the same kind or
+      # notation id. That is what lets an application override a built-in
+      # kind — declare a class handling :lookback and it takes over "L" —
+      # as well as add one of its own. Re-registering the same class is a
+      # no-op, so a reloaded file accumulates no duplicates.
+      #
+      # Returns the class, so a declaration can use the result.
+      def register(cycle_class)
+        displaced = @cycle_classes.reject { |klass| klass.equal?(cycle_class) }
+          .select { |klass| conflicts?(klass, cycle_class) }
+        @cycle_classes -= displaced
+        @cycle_classes << cycle_class unless @cycle_classes.include?(cycle_class)
+        @notation_pattern = nil
+        cycle_class
+      end
+
+      # Drop a handler. Mainly for an application undoing an override, and for
+      # tests that register a throwaway kind.
+      def unregister(cycle_class)
+        @cycle_classes.delete(cycle_class)
+        @notation_pattern = nil
+        cycle_class
+      end
+
+      def cycle_classes = @cycle_classes.dup
+
+      # The class declaring `kind`.
+      def handling(kind)
+        @cycle_classes.find { |klass| klass.handles?(kind) } ||
+          raise(InvalidKind, "':#{kind}' is not a valid kind of Cycle")
+      end
+
+      # The class declaring `notation_id` — the letter(s) that open a cycle's
+      # notation, such as "L" or "LE".
+      def for_notation_id(notation_id)
+        @cycle_classes.find { |klass| klass.notation_id == notation_id } ||
+          raise(InvalidKind, "'#{notation_id}' is not a valid kind of Cycle")
+      end
+
+      # Registered notation ids, longest first. A volume-only cycle has none,
+      # so it contributes nothing to parse.
+      def notation_ids
+        @cycle_classes.filter_map(&:notation_id).uniq.sort_by { |id| [-id.length, id] }
+      end
+
+      # The alternation the parser splices into its pattern. Rebuilt whenever a
+      # class registers, so a kind added at runtime is recognised from then on.
+      def notation_pattern
+        @notation_pattern ||= notation_ids.map { Regexp.escape(it) }.join("|")
+      end
+
+      private
+
+      # Two handlers conflict when they answer to the same kind, or claim the
+      # same notation id. A nil notation id claims nothing.
+      def conflicts?(existing, incoming)
+        return true if existing.kind == incoming.kind
+        return false if incoming.notation_id.nil?
+
+        existing.notation_id == incoming.notation_id
+      end
+    end
+  end
+end

data/lib/sof/cycle/time_span.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+module SOF
+  class Cycle
+    # This class is not intended to be referenced directly.
+    # This is an internal implementation of Cycle behavior.
+    class TimeSpan
+      extend Forwardable
+
+      # TimeSpan objects map Cycle notations to behaviors for their periods
+      #
+      # For example:
+      #   'M' => TimeSpan::DatePeriod::Month
+      #   'Y' => TimeSpan::DatePeriod::Year
+      # Read each DatePeriod subclass for more information.
+      #
+      class InvalidPeriod < StandardError; end
+
+      # The set of classes measuring a period of time. Registration is
+      # explicit — a class joins by declaring what it measures, not by
+      # subclassing — which is what removes the inherited hook and lets the
+      # parser build its period alternation from what is registered.
+      #
+      # Internal, like DatePeriod itself: periods are not an extension point.
+      # Reach it through TimeSpan.period_registry.
+      class PeriodRegistry
+        def self.instance = @instance ||= new
+
+        def initialize
+          @period_classes = []
+          @code_pattern = nil
+        end
+
+        # Add a period class, displacing any already measuring the same period
+        # or claiming the same code, so an application can replace a built-in as
+        # well as add to it. Returns the class.
+        def register(period_class)
+          displaced = @period_classes.reject { |klass| klass.equal?(period_class) }
+            .select { |klass| conflicts?(klass, period_class) }
+          @period_classes -= displaced
+          @period_classes << period_class unless @period_classes.include?(period_class)
+          @code_pattern = nil
+          period_class
+        end
+
+        def unregister(period_class)
+          @period_classes.delete(period_class)
+          @code_pattern = nil
+          period_class
+        end
+
+        def period_classes = @period_classes.dup
+
+        # The class whose notation code this is, e.g. "M". Case-insensitive,
+        # since a notation may be written either way. Nil when unrecognised —
+        # DatePeriod.for falls back to its own default.
+        def for_code(code)
+          return if code.nil?
+
+          normalized = code.to_s.upcase
+          @period_classes.find { |klass| klass.code == normalized }
+        end
+
+        # The class measuring this period, e.g. :month. Nil when unrecognised.
+        def for_period(period)
+          @period_classes.find { |klass| klass.period.to_s == period.to_s }
+        end
+
+        # Registered codes, longest first so a longer code is never shadowed by
+        # its own prefix.
+        def codes
+          @period_classes.filter_map(&:code).uniq.sort_by { |code| [-code.length, code] }
+        end
+
+        # The alternation the parser splices in for the period key. Rebuilt
+        # whenever a class registers.
+        def code_pattern
+          @code_pattern ||= codes.map { Regexp.escape(it) }.join("|")
+        end
+
+        private
+
+        def conflicts?(existing, incoming)
+          return true if existing.period == incoming.period
+          return false if incoming.code.nil?
+
+          existing.code == incoming.code
+        end
+      end
+
+      class << self
+        # Return a time_span for the given count and period
+        def for(count, period)
+          case count.to_i
+          when 0
+            TimeSpanNothing
+          when 1
+            TimeSpanOne
+          else
+            self
+          end.new(count, period)
+        end
+
+        # Return a notation string from a hash
+        def notation(hash)
+          return unless hash.key?(:period) && hash[:period].present?
+
+          [
+            hash.fetch(:period_count) { 1 },
+            notation_id_from_name(hash[:period])
+          ].compact.join
+        end
+
+        # The registry of period classes, owned by DatePeriod. Exposed here
+        # because DatePeriod is a private constant, so callers outside cannot
+        # name it — the parser needs the code alternation to build its pattern.
+        def period_registry = PeriodRegistry.instance
+
+        # Return the notation character for the given period name
+        def notation_id_from_name(name)
+          period_registry.for_period(name)&.code ||
+            raise(InvalidPeriod, "'#{name}' is not a valid period")
+        end
+      end
+
+      def notation
+        [period_count, code].join
+      end
+
+      # Class used to calculate the windows of time so that
+      # a TimeSpan object will know the correct end of year,
+      # quarter, etc.
+      class DatePeriod
+        extend Forwardable
+
+        class << self
+          def for(count, period_notation)
+            @cached_periods ||= {}
+            @cached_periods[period_notation] ||= {}
+            @cached_periods[period_notation][count] ||= (for_notation(period_notation) || self).new(count)
+            @cached_periods[period_notation][count]
+          end
+
+          def for_notation(notation) = registry.for_code(notation)
+
+          def types = registry.period_classes
+
+          def registry = TimeSpan.period_registry
+
+          # Declare the period this class measures, and register it.
+          #
+          # As with Cycle.handles, registration follows from declaring, so
+          # subclassing DatePeriod on its own registers nothing, and an
+          # application can add a period of its own — its code is recognised
+          # because the parser builds that alternation from the registry.
+          #
+          # @param period [Symbol] the period measured, e.g. :month
+          # @param code [String] the notation character, e.g. "M"
+          # @param interval [String] the plural name used in descriptions
+          #
+          # @example
+          #   class Fortnight < DatePeriod
+          #     measures :fortnight, code: "N", interval: "fortnights"
+          #     def duration = (count * 2).weeks
+          #   end
+          def measures(period, code:, interval:)
+            @period = period
+            @code = code
+            @interval = interval
+            registry.register(self)
+          end
+
+          @period = nil
+          @code = nil
+          @interval = nil
+          attr_reader :period, :code, :interval
+        end
+
+        delegate [:period, :code, :interval] => "self.class"
+
+        def initialize(count)
+          @count = count
+          @end_date = {}
+          @begin_date = {}
+        end
+        attr_reader :count
+
+        def end_date(date)
+          @end_date[date] ||= date + duration
+        end
+
+        def begin_date(date)
+          @begin_date[date] ||= date - duration
+        end
+
+        def duration = count.send(period)
+
+        def end_of_period(_) = nil
+
+        def humanized_period
+          return period if count == 1
+
+          "#{period}s"
+        end
+
+        class Year < self
+          measures :year, code: "Y", interval: "years"
+
+          def end_of_period(date)
+            date.end_of_year
+          end
+
+          def beginning_of_period(date)
+            date.beginning_of_year
+          end
+        end
+
+        class Quarter < self
+          measures :quarter, code: "Q", interval: "quarters"
+
+          def duration
+            (count * 3).months
+          end
+
+          def end_of_period(date)
+            date.end_of_quarter
+          end
+
+          def beginning_of_period(date)
+            date.beginning_of_quarter
+          end
+        end
+
+        class Month < self
+          measures :month, code: "M", interval: "months"
+
+          def end_of_period(date)
+            date.end_of_month
+          end
+
+          def beginning_of_period(date)
+            date.beginning_of_month
+          end
+        end
+
+        class Week < self
+          measures :week, code: "W", interval: "weeks"
+
+          def end_of_period(date)
+            date.end_of_week
+          end
+
+          def beginning_of_period(date)
+            date.beginning_of_week
+          end
+        end
+
+        class Day < self
+          measures :day, code: "D", interval: "days"
+
+          def end_of_period(date)
+            date
+          end
+
+          def beginning_of_period(date)
+            date
+          end
+        end
+      end
+      private_constant :DatePeriod, :PeriodRegistry
+
+      def initialize(count, period_id)
+        @count = Integer(count, exception: false)
+        @window = DatePeriod.for(period_count, period_id)
+      end
+      attr_reader :window
+
+      delegate [:end_date, :begin_date, :code] => :window
+
+      def end_date_of_period(date)
+        window.end_of_period(date)
+      end
+
+      def begin_date_of_period(date)
+        window.beginning_of_period(date)
+      end
+
+      # Integer value for the period count or nil
+      def period_count
+        @count
+      end
+
+      delegate [:period, :duration, :interval, :humanized_period] => :window
+
+      # Return a date according to the rules of the time_span
+      def final_date(date)
+        return unless period
+
+        window.end_date(date.to_date)
+      end
+
+      def to_h
+        {
+          period:,
+          period_count:
+        }
+      end
+
+      class TimeSpanNothing < self
+      end
+
+      class TimeSpanOne < self
+        def interval = humanized_period
+      end
+    end
+  end
+end

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.14"
+    VERSION = "0.1.15"
   end
 end

data/lib/sof/cycle.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require "forwardable"
-require_relative "parser"
+require_relative "cycle/registry"
+require_relative "cycle/parser"
 
 module SOF
   class Cycle
@@ -70,9 +71,7 @@ module SOF
           raise InvalidInput, "'#{notation}' is not a valid input"
         end
 
-        cycle = Cycle.cycle_handlers.find do |klass|
-          parser.parses?(klass.notation_id)
-        end.new(notation, parser:)
+        cycle = registry.for_notation_id(parser.kind).new(notation, parser:)
         return cycle if parser.active?
 
         Cycles::Dormant.new(cycle, parser:)
@@ -84,22 +83,14 @@ module SOF
       # @example
       #   class_for_notation_id('L')
       #
-      def class_for_notation_id(notation_id)
-        Cycle.cycle_handlers.find do |klass|
-          klass.notation_id == notation_id
-        end || raise(InvalidKind, "'#{notation_id}' is not a valid kind of #{name}")
-      end
+      def class_for_notation_id(notation_id) = registry.for_notation_id(notation_id)
 
       # Return the class handling the kind
       #
       # @param sym [Symbol] symbol matching the kind of Cycle class
       # @example
       #   class_for_kind(:lookback)
-      def class_for_kind(sym)
-        Cycle.cycle_handlers.find do |klass|
-          klass.handles?(sym)
-        end || raise(InvalidKind, "':#{sym}' is not a valid kind of Cycle")
-      end
+      def class_for_kind(sym) = registry.handling(sym)
 
       # Return a legend explaining all notation components
       #
@@ -123,6 +114,8 @@ module SOF
         }
       end
 
+      # Defaults for the base class itself, which handles no kind and so is
+      # never registered.
       @volume_only = false
       @notation_id = nil
       @kind = nil
@@ -150,23 +143,77 @@ module SOF
         kind.to_s == sym.to_s
       end
 
-      def cycle_handlers
-        @cycle_handlers ||= Set.new
+      # Declare what kind of cycle this class handles, and register it.
+      #
+      # Registration is a consequence of declaring, so the two can never
+      # disagree, and subclassing Cycle for any other reason — an abstract
+      # intermediate, a test double — registers nothing.
+      #
+      # An application can declare its own kind this way and the parser will
+      # recognise its notation, because the pattern is built from what is
+      # registered.
+      #
+      # @param kind [Symbol] the kind this class handles, e.g. :lookback
+      # @param notation [String, nil] the notation id opening the cycle, e.g.
+      #   "L". Omit for a cycle with no notation of its own, such as
+      #   volume-only.
+      # @param periods [Array<String>] period keys this kind accepts. Empty
+      #   means the kind takes no period.
+      # @param volume_only [Boolean] whether this kind carries volume alone.
+      #
+      # @example
+      #   class Fortnightly < SOF::Cycle
+      #     handles :fortnightly, notation: "X", periods: %w[D W]
+      #     def self.recurring? = true
+      #   end
+      def handles(kind, notation: nil, periods: [], volume_only: false)
+        @kind = kind
+        @notation_id = notation
+        @valid_periods = periods
+        @volume_only = volume_only
+        register(self)
       end
 
-      def inherited(klass)
-        Cycle.cycle_handlers << klass
-      end
+      # Register a handler that does not inherit from Cycle. Inheriting and
+      # declaring with `handles` is the easier path, because it supplies the
+      # behaviour Cycle.for goes on to use; this is for a class that would
+      # rather implement that itself.
+      #
+      # The class must answer, at the class level:
+      #
+      #   kind             the kind it handles, e.g. :lookback
+      #   notation_id      the notation opening it, e.g. "L", or nil
+      #   valid_periods    period keys it accepts, e.g. %w[D W M Y]
+      #   volume_only?     whether it carries volume alone
+      #   handles?(kind)   whether it answers to a kind
+      #   recurring?       whether the window repeats
+      #   dormant_capable? whether it can be written without a from date
+      #   validate_period(key)
+      #   description, examples   (for the legend)
+      #
+      # and instances are built as `new(notation, parser:)`.
+      #
+      # Registering displaces any handler already answering to the same kind
+      # or notation id, so this replaces a built-in as readily as it adds one.
+      #
+      # @param cycle_class [Class] the handler to register
+      # @return [Class] the class registered
+      def register(cycle_class) = registry.register(cycle_class)
+
+      # Drop a handler, undoing `register` or a `handles` declaration.
+      def unregister(cycle_class) = registry.unregister(cycle_class)
+
+      def registry = Registry.instance
 
       private
 
       def build_kind_legend
         legend = {}
-        Cycle.cycle_handlers.each do |handler|
+        registry.cycle_classes.each do |handler|
           # Skip volume_only since it doesn't have a notation_id
-          next if handler.instance_variable_get(:@volume_only)
+          next if handler.volume_only?
 
-          notation_id = handler.instance_variable_get(:@notation_id)
+          notation_id = handler.notation_id
           next unless notation_id
 
           legend[notation_id] = {
@@ -179,14 +226,10 @@ module SOF
 
       def build_period_legend
         legend = {}
-        # Use known period codes since DatePeriod is private
-        period_mappings = {
-          "D" => "day",
-          "W" => "week",
-          "M" => "month",
-          "Q" => "quarter",
-          "Y" => "year"
-        }
+        # Built from the registered periods, so one an application adds shows
+        # up here too.
+        period_mappings = TimeSpan.period_registry.period_classes
+          .to_h { |klass| [klass.code, klass.period.to_s] }
 
         period_mappings.each do |code, period_name|
           legend[code] = {
@@ -253,6 +296,39 @@ module SOF
 
     def extend_period(_ = nil) = self
 
+    # Whether this kind of cycle can be written without a from date, and so
+    # can be anchored later. Answers on the instance so a dormant cycle can
+    # be asked too — `cycle.class` is Cycles::Dormant there, which knows
+    # nothing of the kind it wraps.
+    def dormant_capable? = self.class.dormant_capable?
+
+    # The cycle restarted from the latest of `dates` past its current anchor.
+    #
+    # A recurring, dormant-capable window (E and I) is reset by the act that
+    # satisfies it — "complete 1 by that date to reset the cycle". Nothing in
+    # the notation does that on its own, so this used to fall to each
+    # consuming app.
+    #
+    # Dates on or before the current anchor are ignored: a back-dated act
+    # must not drag a forward-running window backwards. Every other kind
+    # returns itself — a lookback window already slides, a calendar window is
+    # pinned to the calendar, a one-shot window does not repeat, and an
+    # un-anchored one has no window to move until it is activated.
+    #
+    # @param dates [Array<Date, Time, nil>] the acts that satisfy this cycle
+    # @return [Cycle] the reset cycle, or self when nothing resets it
+    #
+    # @example
+    #   Cycle.for("V1E18MF2026-02-01").reset_by([Date.new(2026, 9, 15)])
+    #   # => Cycle.for("V1E18MF2026-09-15")
+    def reset_by(dates)
+      return self unless recurring? && dormant_capable?
+      return self if from_date.nil?
+
+      reset = reset_date(dates)
+      reset ? Cycle.for(activated_notation(reset)) : self
+    end
+
     # From the supplied anchor date, are there enough in-window completions to
     # satisfy the cycle?
     #
@@ -303,5 +379,13 @@ module SOF
     end
 
     def as_json(...) = notation
+
+    private
+
+    # The latest date that moves this cycle's window forward, or nil.
+    def reset_date(dates)
+      anchored_on = from_date.to_date
+      Array(dates).filter_map { it&.to_date }.select { it > anchored_on }.max
+    end
   end
 end

data/lib/sof/cycles/calendar.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Calendar < Cycle
-      @volume_only = false
-      @notation_id = "C"
-      @kind = :calendar
-      @valid_periods = %w[M Q Y]
+      handles :calendar, notation: "C", periods: %w[M Q Y]
 
       class << self
         def frame_of_reference = "total"

data/lib/sof/cycles/dormant.rb

@@ -22,6 +22,10 @@ module SOF
 
       def covered_dates(...) = []
 
+      # No anchor yet, so nothing to move: a dormant cycle is reset by being
+      # activated, not by the acts that satisfy it.
+      def reset_by(...) = self
+
       def expiration_of(...) = nil
 
       def satisfied_by?(...) = false

data/lib/sof/cycles/end_of.rb

@@ -11,10 +11,7 @@
 module SOF
   module Cycles
     class EndOf < Cycle
-      @volume_only = false
-      @notation_id = "E"
-      @kind = :end_of
-      @valid_periods = %w[W M Q Y]
+      handles :end_of, notation: "E", periods: %w[W M Q Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/interval.rb

@@ -11,10 +11,7 @@
 module SOF
   module Cycles
     class Interval < Cycle
-      @volume_only = false
-      @notation_id = "I"
-      @kind = :interval
-      @valid_periods = %w[D W M Y]
+      handles :interval, notation: "I", periods: %w[D W M Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/lookback.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Lookback < Cycle
-      @volume_only = false
-      @notation_id = "L"
-      @kind = :lookback
-      @valid_periods = %w[D W M Y]
+      handles :lookback, notation: "L", periods: %w[D W M Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/lookback_end_of.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class LookbackEndOf < Cycle
-      @volume_only = false
-      @notation_id = "LE"
-      @kind = :lookback_end_of
-      @valid_periods = %w[D W M Q Y]
+      handles :lookback_end_of, notation: "LE", periods: %w[D W M Q Y]
 
       def self.recurring? = true
 

data/lib/sof/cycles/volume_only.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class VolumeOnly < Cycle
-      @volume_only = true
-      @notation_id = nil
-      @kind = :volume_only
-      @valid_periods = []
+      handles :volume_only, volume_only: true
 
       class << self
         def handles?(sym) = sym.nil? || sym.to_s == "volume_only"

data/lib/sof/cycles/within.rb

@@ -3,10 +3,7 @@
 module SOF
   module Cycles
     class Within < Cycle
-      @volume_only = false
-      @notation_id = "W"
-      @kind = :within
-      @valid_periods = %w[D W M Y]
+      handles :within, notation: "W", periods: %w[D W M Y]
 
       def self.recurring? = false
 
@@ -24,7 +21,7 @@ module SOF
 
       def extend_period(count)
         Cycle.for(
-          Parser.load(
+          Cycle::Parser.load(
             parser.to_h.merge(period_count: period_count + count)
           ).to_s
         )

data/lib/sof-cycle.rb

@@ -14,4 +14,4 @@ require_relative "sof/cycle"
 
 Dir[File.join(__dir__, "sof", "cycles", "*.rb")].each { |file| require file }
 
-require_relative "sof/time_span"
+require_relative "sof/cycle/time_span"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.15
 platform: ruby
 authors:
 - Jim Gay
@@ -55,13 +55,21 @@ files:
 - checksums/sof-cycle-0.1.10.gem.sha512
 - checksums/sof-cycle-0.1.11.gem.sha512
 - checksums/sof-cycle-0.1.12.gem.sha512
+- checksums/sof-cycle-0.1.13.gem.sha512
+- checksums/sof-cycle-0.1.14.gem.sha512
 - checksums/sof-cycle-0.1.2.gem.sha512
+- checksums/sof-cycle-0.1.3.gem.sha512
+- checksums/sof-cycle-0.1.4.gem.sha512
+- checksums/sof-cycle-0.1.5.gem.sha512
 - checksums/sof-cycle-0.1.6.gem.sha512
 - checksums/sof-cycle-0.1.7.gem.sha512
 - checksums/sof-cycle-0.1.8.gem.sha512
 - checksums/sof-cycle-0.1.9.gem.sha512
 - lib/sof-cycle.rb
 - lib/sof/cycle.rb
+- lib/sof/cycle/parser.rb
+- lib/sof/cycle/registry.rb
+- lib/sof/cycle/time_span.rb
 - lib/sof/cycle/version.rb
 - lib/sof/cycles/calendar.rb
 - lib/sof/cycles/dormant.rb
@@ -71,8 +79,6 @@ files:
 - lib/sof/cycles/lookback_end_of.rb
 - lib/sof/cycles/volume_only.rb
 - lib/sof/cycles/within.rb
-- lib/sof/parser.rb
-- lib/sof/time_span.rb
 homepage: https://github.com/SOFware/sof-cycle
 licenses: []
 metadata:

data/lib/sof/parser.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "cycle"
-require "active_support/core_ext/hash/keys"
-require "active_support/core_ext/object/blank"
-require "active_support/core_ext/object/inclusion"
-require "active_support/core_ext/hash/reverse_merge"
-require "active_support/isolated_execution_state"
-
-module SOF
-  # This class is not intended to be referenced directly.
-  # This is an internal implementation of Cycle behavior.
-  class Parser
-    extend Forwardable
-
-    PARTS_REGEX = /
-      ^(?<vol>V(?<volume>\d*))? # optional volume
-      (?<set>(?<kind>LE|L|C|W|E|I) # kind
-      (?<period_count>\d+) # period count
-      (?<period_key>D|W|M|Q|Y)?)? # period_key
-      (?<from>F(?<from_date>\d{4}-\d{2}-\d{2}))?$ # optional from
-    /ix
-
-    def self.dormant_capable_kinds
-      Cycle.cycle_handlers.select(&:dormant_capable?).map(&:notation_id).compact
-    end
-
-    def self.for(notation_or_parser)
-      return notation_or_parser if notation_or_parser.is_a? self
-
-      new(notation_or_parser)
-    end
-
-    def self.load(hash)
-      hash.symbolize_keys!
-      hash.reverse_merge!(volume: 1)
-      keys = %i[volume kind period_count period_key]
-      str = "V#{hash.values_at(*keys).join}"
-      return new(str) unless hash[:from_date]
-
-      new([str, "F#{hash[:from_date]}"].join)
-    end
-
-    def initialize(notation)
-      @notation = notation&.upcase
-      @match = @notation&.match(PARTS_REGEX)
-    end
-
-    attr_reader :match, :notation
-
-    delegate [:dormant_capable_kinds] => "self.class"
-    delegate [:period, :humanized_period] => :time_span
-
-    # Return a TimeSpan object for the period and period_count
-    def time_span
-      @time_span ||= TimeSpan.for(period_count, period_key)
-    end
-
-    def valid? = match.present?
-
-    def inspect = notation
-    alias_method :to_s, :inspect
-
-    def activated_notation(date)
-      return notation unless dormant_capable?
-
-      self.class.load(to_h.merge(from_date: date.to_date)).notation
-    end
-
-    def ==(other) = other.to_h == to_h
-
-    def to_h
-      {
-        volume:,
-        kind:,
-        period_count:,
-        period_key:,
-        from_date:
-      }
-    end
-
-    def parses?(notation_id) = kind == notation_id
-
-    def active? = !dormant?
-
-    def dormant? = dormant_capable? && from_date.nil?
-
-    def dormant_capable? = kind.in?(dormant_capable_kinds)
-
-    def period_count = match[:period_count]
-
-    def period_key = match[:period_key]
-
-    def vol = match[:vol] || "V1"
-
-    def volume = (match[:volume] || 1).to_i
-
-    def from_data
-      return {} unless from
-
-      {from: from}
-    end
-
-    def from_date = match[:from_date]
-
-    def from = match[:from]
-
-    def kind = match[:kind]
-  end
-end

data/lib/sof/time_span.rb

@@ -1,236 +0,0 @@
-# frozen_string_literal: true
-
-module SOF
-  # This class is not intended to be referenced directly.
-  # This is an internal implementation of Cycle behavior.
-  class TimeSpan
-    extend Forwardable
-
-    # TimeSpan objects map Cycle notations to behaviors for their periods
-    #
-    # For example:
-    #   'M' => TimeSpan::DatePeriod::Month
-    #   'Y' => TimeSpan::DatePeriod::Year
-    # Read each DatePeriod subclass for more information.
-    #
-    class InvalidPeriod < StandardError; end
-
-    class << self
-      # Return a time_span for the given count and period
-      def for(count, period)
-        case count.to_i
-        when 0
-          TimeSpanNothing
-        when 1
-          TimeSpanOne
-        else
-          self
-        end.new(count, period)
-      end
-
-      # Return a notation string from a hash
-      def notation(hash)
-        return unless hash.key?(:period) && hash[:period].present?
-
-        [
-          hash.fetch(:period_count) { 1 },
-          notation_id_from_name(hash[:period])
-        ].compact.join
-      end
-
-      # Return the notation character for the given period name
-      def notation_id_from_name(name)
-        type = DatePeriod.types.find do |klass|
-          klass.period.to_s == name.to_s
-        end
-
-        raise InvalidPeriod, "'#{name}' is not a valid period" unless type
-
-        type.code
-      end
-    end
-
-    def notation
-      [period_count, code].join
-    end
-
-    # Class used to calculate the windows of time so that
-    # a TimeSpan object will know the correct end of year,
-    # quarter, etc.
-    class DatePeriod
-      extend Forwardable
-
-      class << self
-        def for(count, period_notation)
-          @cached_periods ||= {}
-          @cached_periods[period_notation] ||= {}
-          @cached_periods[period_notation][count] ||= (for_notation(period_notation) || self).new(count)
-          @cached_periods[period_notation][count]
-        end
-
-        def for_notation(notation)
-          DatePeriod.types.find do |klass|
-            klass.code == notation.to_s.upcase
-          end
-        end
-
-        def types = @types ||= Set.new
-
-        def inherited(klass)
-          DatePeriod.types << klass
-        end
-
-        @period = nil
-        @code = nil
-        @interval = nil
-        attr_reader :period, :code, :interval
-      end
-
-      delegate [:period, :code, :interval] => "self.class"
-
-      def initialize(count)
-        @count = count
-      end
-      attr_reader :count
-
-      def end_date(date)
-        @end_date ||= {}
-        @end_date[date] ||= date + duration
-      end
-
-      def begin_date(date)
-        @begin_date ||= {}
-        @begin_date[date] ||= date - duration
-      end
-
-      def duration = count.send(period)
-
-      def end_of_period(_) = nil
-
-      def humanized_period
-        return period if count == 1
-
-        "#{period}s"
-      end
-
-      class Year < self
-        @period = :year
-        @code = "Y"
-        @interval = "years"
-
-        def end_of_period(date)
-          date.end_of_year
-        end
-
-        def beginning_of_period(date)
-          date.beginning_of_year
-        end
-      end
-
-      class Quarter < self
-        @period = :quarter
-        @code = "Q"
-        @interval = "quarters"
-
-        def duration
-          (count * 3).months
-        end
-
-        def end_of_period(date)
-          date.end_of_quarter
-        end
-
-        def beginning_of_period(date)
-          date.beginning_of_quarter
-        end
-      end
-
-      class Month < self
-        @period = :month
-        @code = "M"
-        @interval = "months"
-
-        def end_of_period(date)
-          date.end_of_month
-        end
-
-        def beginning_of_period(date)
-          date.beginning_of_month
-        end
-      end
-
-      class Week < self
-        @period = :week
-        @code = "W"
-        @interval = "weeks"
-
-        def end_of_period(date)
-          date.end_of_week
-        end
-
-        def beginning_of_period(date)
-          date.beginning_of_week
-        end
-      end
-
-      class Day < self
-        @period = :day
-        @code = "D"
-        @interval = "days"
-
-        def end_of_period(date)
-          date
-        end
-
-        def beginning_of_period(date)
-          date
-        end
-      end
-    end
-    private_constant :DatePeriod
-
-    def initialize(count, period_id)
-      @count = Integer(count, exception: false)
-      @window = DatePeriod.for(period_count, period_id)
-    end
-    attr_reader :window
-
-    delegate [:end_date, :begin_date, :code] => :window
-
-    def end_date_of_period(date)
-      window.end_of_period(date)
-    end
-
-    def begin_date_of_period(date)
-      window.beginning_of_period(date)
-    end
-
-    # Integer value for the period count or nil
-    def period_count
-      @count
-    end
-
-    delegate [:period, :duration, :interval, :humanized_period] => :window
-
-    # Return a date according to the rules of the time_span
-    def final_date(date)
-      return unless period
-
-      window.end_date(date.to_date)
-    end
-
-    def to_h
-      {
-        period:,
-        period_count:
-      }
-    end
-
-    class TimeSpanNothing < self
-    end
-
-    class TimeSpanOne < self
-      def interval = humanized_period
-    end
-  end
-end