Register cycle kinds explicitly

[saturnflyer]

Why

Redoes the spirit of #55 — move tracking of cycle classes out of Cycle and into a registry — with one change of goal: no inherited hook.

#55 kept it, just pointed it at the registry:

def inherited(subclass)
  registry.register(subclass)
end

That leaves registration as a side effect of subclassing. Anything inheriting from Cycle — an abstract intermediate, a test double, a one-off — silently becomes a handler, and there's no way to inherit without joining.

The larger problem it exposed: the gem was extensible in the half that didn't matter and closed in the half that did. An application could define its own cycle class and it registered fine, but the notation would not parse:

class Fortnightly < SOF::Cycle
  @notation_id = "X"
  @kind = :fortnightly
end

SOF::Cycle.for("V1X2W")
# => SOF::Cycle::InvalidInput: 'V1X2W' is not a valid input

because the parser's kind alternation was a closed literal in a constant:

(?<set>(?<kind>LE|L|C|W|E|I)   # kind

So adding a kind meant patching PARTS_REGEX. A registry that only replaces inherited is a tidy-up; a registry the parser reads is the thing that makes the extension point real.

Summary

• Cycle.handles declares kind, notation id, periods and the volume-only flag, and registers — one call, so declaration and registration cannot drift apart. It replaces four bare ivar assignments per handler, which nothing previously enforced.
• SOF::CycleRegistry, reachable as Cycle.registry, owns the collection. Cycle.inherited and Cycle.cycle_handlers are gone.
• The parser's pattern is derived from the registry and rebuilt when a class registers, so a kind added at runtime is recognised from then on. Cached in between, since parsing is hot.
• Registering displaces conflicts — a class handling the same kind or notation id takes over from the one already there. That is what lets an application replace a built-in, not merely add beside it. unregister undoes it.
• Notation ids are Regexp.escaped and ordered longest-first when building the alternation.

An application now gets this, with no change to the gem:

class Fortnightly < SOF::Cycle
  handles :fortnightly, notation: "X", periods: %w[D W M]
  def self.recurring? = true
end

SOF::Cycle.for("V2X3W")   # => #<Fortnightly> "2x every 3 weeks"
SOF::Cycle.legend["kind"] # includes "X"

Notes for reviewers

Cycle keeps its own @kind/@notation_id/@valid_periods/@volume_only defaults as plain assignments, since the base class handles no kind and must not register itself.

Parser.dormant_capable_kinds still has to be a method rather than a constant, for the same load-order reason as before: handlers register as sof/cycles/*.rb loads, which happens after parser.rb.

Covered by spec/sof/cycle_registry_spec.rb (registry behaviour in isolation) and spec/sof/custom_cycle_kind_spec.rb (an application adding a kind, overriding a built-in, and subclassing without declaring). The latter restores the registry around each example so registration cannot leak between specs.

Periods too

DatePeriod had the identical pattern one level down — an inherited hook, and a D|W|M|Q|Y alternation written out in the regex — so a second commit gives it the same treatment:

measures :month, code: "M", interval: "months"

The parser now builds the period alternation from the registry alongside the kind alternation. No inherited hook remains anywhere in lib/.

Periods are not an extension point, unlike kinds. DatePeriod is a private_constant, so an application cannot name it in order to subclass it — the asymmetry with SOF::Cycle, which is public. The registry is private for the same reason and is reached through the public TimeSpan.period_registry, which is what the parser uses rather than reaching into DatePeriod for it. Opening periods up would mean making DatePeriod public API; that's a deliberate decision for another day, not a side effect of this change.

That commit also moves the cycle registry from SOF::CycleRegistry to SOF::Cycle::Registry. The first commit introduced it as a third constant directly under SOF, which undid part of what #7 set out to do. SOF.constants is back to [:Cycle, :Cycles].

Deliberately not included

Thread safety. #55 reached for Concurrent::Set and a concurrent-ruby dependency. Both registries are written at load time and read afterwards, so a plain collection is enough. The genuinely racy state is TimeSpan's cached periods and the DatePeriod memo hashes — a real issue, but a separate one.