Restrict classes to the gem namespace

[saturnflyer]

Why

SOF::Parser and SOF::TimeSpan sat directly under SOF, a namespace shared with other libraries and applications. Both carry the comment "This class is not intended to be referenced directly. This is an internal implementation of Cycle behavior." An internal implementation detail of Cycle has no claim on the shared namespace.

Summary

• SOF::Parser → SOF::Cycle::Parser
• SOF::TimeSpan → SOF::Cycle::TimeSpan

SOF::Cycles stays where it is. The gem owns two names under SOF, which is a deliberate trade: the handlers each inherit from SOF::Cycle, so nesting them beneath it would put a class inside its own superclass. A second top-level constant is the cheaper price.

No aliases are left at the old names. An alias would keep holding the namespace this change exists to release.

Notes for reviewers

These are file moves, but git renders the lib/ ones as add + delete. The added nesting re-indents every line, so rename detection fails even at 40% similarity. Reviewing with whitespace ignored shows the bodies are untouched.

Low breakage risk: both classes are documented internals. Predicate-based and public-API code (SOF::Cycle.for, SOF::Cycle.legend, cycle.end_of?, SOF::Cycle::InvalidInput) is unaffected.

Review feedback

• Freeze dormant_capable_kinds — done, in its own commit.
• Make it a constant instead — not done, and worth recording why. Handlers register themselves through Cycle.inherited as each file in sof/cycles loads, which happens after parser.rb. At that point Cycle.cycle_handlers is empty, so a constant would capture [] permanently and dormant_capable? would return false for every E, I and W cycle. That reasoning is now a comment beside the method so it doesn't get "simplified" later.
• The @time_span shape-variations warning — done, and extended. The warning is live on Ruby 4.0; enabling it (-W:performance) and building a control class that exceeds the limit reproduces it, and Ruby's own remediation text is "define instance variables in a consistent order, for instance by eagerly defining them all in the #initialize method." Neither class here was near the eight-variation threshold, so no warning was firing — but DatePeriod was the more interesting case than Parser: end_date and begin_date each added an ivar on first call, so the shape depended on call order. Both now declare every ivar in the constructor and take exactly one shape, and the ||= {} guards are gone.
• Make Parser a module to avoid the nested-class antipattern — not applicable; Parser is instantiated. The related concern about nesting is why SOF::Cycles is left alone rather than folded under Cycle.

Deferred as out of scope for a namespace change: decoupling from ActiveSupport, dependency injection in .load (which must stay a plain dump/load pair for ActiveRecord serialization), casting in the constructor, and extracting a serializer object.

[bkuhlmann]

Left some feedback on the first class only but I think some of what I'm talking about could be applied to the TimeSpan class too.