rigortype 0.2.7 → 0.2.8

data/lib/rigor/type/refined.rb

@@ -8,35 +8,26 @@ require_relative "acceptance_router"
 
 module Rigor
   module Type
-    # `Refined[base, predicate_id]` — predicate-subset half of
-    # the OQ3 refinement-carrier strategy
-    # ([ADR-3](docs/adr/3-type-representation.md), Working
-    # Decision Option C). Sibling of `Type::Difference`, which
-    # carries the point-removal half.
+    # `Refined[base, predicate_id]` — predicate-subset half of the OQ3 refinement-carrier strategy
+    # ([ADR-3](docs/adr/3-type-representation.md), Working Decision Option C). Sibling of
+    # `Type::Difference`, which carries the point-removal half.
     #
     #   lowercase-string = Refined[Nominal[String], :lowercase]
     #   uppercase-string = Refined[Nominal[String], :uppercase]
     #   numeric-string   = Refined[Nominal[String], :numeric]
     #
-    # The carrier wraps a base type and a `predicate_id` Symbol
-    # drawn from {PREDICATES}. The recogniser is invoked at
-    # constant-fold and acceptance time over a `Constant<base>`
-    # value; for non-Constant receivers the carrier is a marker
-    # the catalog tier consults to project `String#downcase` /
+    # The carrier wraps a base type and a `predicate_id` Symbol drawn from {PREDICATES}. The recogniser
+    # is invoked at constant-fold and acceptance time over a `Constant<base>` value; for non-Constant
+    # receivers the carrier is a marker the catalog tier consults to project `String#downcase` /
     # `String#upcase` (etc.) into the matching refinement.
     #
-    # Display routes through {CANONICAL_NAMES}: registered
-    # `(base_class_name, predicate_id)` pairs print in their
-    # kebab-case spelling (`lowercase-string`); unregistered
-    # combinations fall back to the `base & predicate?` operator
-    # form per
-    # [`type-operators.md`](docs/type-specification/type-operators.md).
+    # Display routes through {CANONICAL_NAMES}: registered `(base_class_name, predicate_id)` pairs print
+    # in their kebab-case spelling (`lowercase-string`); unregistered combinations fall back to the
+    # `base & predicate?` operator form per [`type-operators.md`](docs/type-specification/type-operators.md).
     #
-    # Construction MUST go through `Type::Combinator.refined` /
-    # the per-name factories (`Combinator.lowercase_string`,
-    # `Combinator.uppercase_string`, `Combinator.numeric_string`).
-    # Direct `.new` is an internal escape hatch for tests and
-    # combinator's own implementation.
+    # Construction MUST go through `Type::Combinator.refined` / the per-name factories
+    # (`Combinator.lowercase_string`, `Combinator.uppercase_string`, `Combinator.numeric_string`). Direct
+    # `.new` is an internal escape hatch for tests and combinator's own implementation.
     class Refined
       attr_reader :base, :predicate_id
 
@@ -55,8 +46,8 @@ module Rigor
         "#{base.describe(verbosity)} & #{predicate_id}?"
       end
 
-      # Erases to the base nominal: every refinement MUST erase
-      # to its base per [`rbs-erasure.md`](docs/type-specification/rbs-erasure.md).
+      # Erases to the base nominal: every refinement MUST erase to its base per
+      # [`rbs-erasure.md`](docs/type-specification/rbs-erasure.md).
       def erase_to_rbs
         base.erase_to_rbs
       end
@@ -83,12 +74,9 @@ module Rigor
         "#<Rigor::Type::Refined #{describe(:short)}>"
       end
 
-      # Recognises a Ruby value against this carrier's
-      # predicate. The trinary return is intentional: `true` /
-      # `false` when the predicate registry decides, `nil`
-      # when the predicate is unknown to the registry, so
-      # callers (today {Inference::Acceptance}) can fall
-      # through to gradual-mode `:maybe`.
+      # Recognises a Ruby value against this carrier's predicate. The trinary return is intentional:
+      # `true` / `false` when the predicate registry decides, `nil` when the predicate is unknown to the
+      # registry, so callers (today {Inference::Acceptance}) can fall through to gradual-mode `:maybe`.
       # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
       def matches?(value)
         recogniser = PREDICATES[predicate_id]
@@ -98,60 +86,42 @@ module Rigor
       end
       # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
 
-      # `predicate_id => recogniser` table. The recogniser is
-      # called with a Ruby value (typically the inner `value`
-      # of a `Constant`) and returns truthy when the value
-      # satisfies the predicate. The recogniser MUST be total
-      # (return false rather than raise) over arbitrary input,
-      # so callers can pass any `Constant#value` without a
-      # type-prefilter.
+      # `predicate_id => recogniser` table. The recogniser is called with a Ruby value (typically the
+      # inner `value` of a `Constant`) and returns truthy when the value satisfies the predicate. The
+      # recogniser MUST be total (return false rather than raise) over arbitrary input, so callers can
+      # pass any `Constant#value` without a type-prefilter.
       #
-      # Plugin-contributed predicates are not yet wired; today
-      # the table covers the built-in catalogue.
+      # Plugin-contributed predicates are not yet wired; today the table covers the built-in catalogue.
       #
       # Recogniser policy:
       #
-      # - `:numeric` recognises a string that is a *single Ruby
-      #   numeric literal* — exactly the syntax that, written in
-      #   Ruby source, evaluates to an `Integer` / `Float` /
-      #   `Rational` / `Complex`. The recogniser delegates to the
-      #   real Ruby parser ({Refined.ruby_numeric_literal?} via
-      #   Prism), so it tracks Ruby's grammar precisely: decimal /
-      #   `0x` hex / `0o` (or leading-zero) octal / `0b` binary /
-      #   `0d` decimal integers, underscore digit separators
-      #   (`1_000`), decimal fractions and scientific floats
-      #   (`1.5`, `1E-5`), and the `r` rational / `i` imaginary
-      #   suffixes (`1r`, `2i`, `0xffr`). A single leading sign is
-      #   folded into the literal (`-1`, `+1.5`), but a doubled
-      #   sign (`--1`, `++1`) parses as a unary-operator chain — a
-      #   `CallNode`, not a literal — and is rejected, as are
-      #   multi-dot junk (`1.2.3`), partial literals (`0x`, `1_`),
-      #   whitespace-padded strings, and — crucially — non-ASCII
-      #   "digits" (full-width `１`, superscript `²`, other Unicode
-      #   number characters): Ruby's lexer only accepts `[0-9]` in
-      #   a numeric literal, so those are `CallNode`s too. The
-      #   stricter base-N predicates below remain proper subsets.
-      # - `:decimal_int` is "what `Integer(s, 10)` would parse
-      #   without remainder" — one or more decimal digits,
-      #   optional leading sign, no whitespace, no fractional
-      #   tail.
-      # - `:octal_int` and `:hex_int` REQUIRE their conventional
-      #   prefix (`0o` / `0O` / leading `0` for octal; `0x` /
-      #   `0X` for hex) so the predicate is disjoint from
-      #   `:decimal_int`. A bare `"755"` is decimal-int-string,
-      #   not octal-int-string. This matches the typical user
-      #   intent — a refinement marks a string that "looks like
-      #   octal", not "happens to be base-8 valid".
+      # - `:numeric` recognises a string that is a *single Ruby numeric literal* — exactly the syntax
+      #   that, written in Ruby source, evaluates to an `Integer` / `Float` / `Rational` / `Complex`. The
+      #   recogniser delegates to the real Ruby parser ({Refined.ruby_numeric_literal?} via Prism), so it
+      #   tracks Ruby's grammar precisely: decimal / `0x` hex / `0o` (or leading-zero) octal / `0b`
+      #   binary / `0d` decimal integers, underscore digit separators (`1_000`), decimal fractions and
+      #   scientific floats (`1.5`, `1E-5`), and the `r` rational / `i` imaginary suffixes (`1r`, `2i`,
+      #   `0xffr`). A single leading sign is folded into the literal (`-1`, `+1.5`), but a doubled sign
+      #   (`--1`, `++1`) parses as a unary-operator chain — a `CallNode`, not a literal — and is
+      #   rejected, as are multi-dot junk (`1.2.3`), partial literals (`0x`, `1_`), whitespace-padded
+      #   strings, and — crucially — non-ASCII "digits" (full-width `１`, superscript `²`, other Unicode
+      #   number characters): Ruby's lexer only accepts `[0-9]` in a numeric literal, so those are
+      #   `CallNode`s too. The stricter base-N predicates below remain proper subsets.
+      # - `:decimal_int` is "what `Integer(s, 10)` would parse without remainder" — one or more decimal
+      #   digits, optional leading sign, no whitespace, no fractional tail.
+      # - `:octal_int` and `:hex_int` REQUIRE their conventional prefix (`0o` / `0O` / leading `0` for
+      #   octal; `0x` / `0X` for hex) so the predicate is disjoint from `:decimal_int`. A bare `"755"` is
+      #   decimal-int-string, not octal-int-string. This matches the typical user intent — a refinement
+      #   marks a string that "looks like octal", not "happens to be base-8 valid".
       DECIMAL_INT_STRING_PATTERN = /\A-?\d+\z/
       OCTAL_INT_STRING_PATTERN = /\A-?(?:0[oO][0-7]+|0[0-7]+)\z/
       HEX_INT_STRING_PATTERN = /\A-?0[xX][0-9a-fA-F]+\z/
       private_constant :DECIMAL_INT_STRING_PATTERN,
                        :OCTAL_INT_STRING_PATTERN, :HEX_INT_STRING_PATTERN
 
-      # Prism node classes that represent a numeric literal. A
-      # string is a numeric-string exactly when the parser reduces
-      # the whole input to a single one of these (the leading sign
-      # is already folded into the literal by the parser).
+      # Prism node classes that represent a numeric literal. A string is a numeric-string exactly when
+      # the parser reduces the whole input to a single one of these (the leading sign is already folded
+      # into the literal by the parser).
       NUMERIC_LITERAL_NODES = [
         Prism::IntegerNode,
         Prism::FloatNode,
@@ -160,11 +130,9 @@ module Rigor
       ].freeze
       private_constant :NUMERIC_LITERAL_NODES
 
-      # Cheap pre-filter applied before invoking the parser: every
-      # Ruby numeric literal starts with an ASCII digit, optionally
-      # preceded by exactly one sign. Strings that fail this never
-      # reach Prism (the common non-numeric case stays allocation-
-      # and parse-free).
+      # Cheap pre-filter applied before invoking the parser: every Ruby numeric literal starts with an
+      # ASCII digit, optionally preceded by exactly one sign. Strings that fail this never reach Prism
+      # (the common non-numeric case stays allocation- and parse-free).
       NUMERIC_LITERAL_PREFIX = /\A[+-]?\d/
       private_constant :NUMERIC_LITERAL_PREFIX
 
@@ -176,10 +144,8 @@ module Rigor
       def self.ruby_numeric_literal?(value)
         return false unless value.is_a?(String)
         return false if value.empty?
-        # A numeric literal carries no whitespace; reject any
-        # leading / trailing / interior space so the *whole* string
-        # must be the literal (Prism would otherwise accept a
-        # trailing-space `"1 "`).
+        # A numeric literal carries no whitespace; reject any leading / trailing / interior space so the
+        # *whole* string must be the literal (Prism would otherwise accept a trailing-space `"1 "`).
         return false if value.match?(/\s/)
         return false unless value.match?(NUMERIC_LITERAL_PREFIX)
 
@@ -203,28 +169,21 @@ module Rigor
         decimal_int: ->(v) { v.is_a?(String) && DECIMAL_INT_STRING_PATTERN.match?(v) },
         octal_int: ->(v) { v.is_a?(String) && OCTAL_INT_STRING_PATTERN.match?(v) },
         hex_int: ->(v) { v.is_a?(String) && HEX_INT_STRING_PATTERN.match?(v) },
-        # `literal-string` is a flow-tracked predicate, not a value-
-        # level predicate: a String is literal-string when it is
-        # known to come from a source-code literal (or composition
-        # of literals). Every concrete `Constant<String>` is
-        # already literal by construction, so the inspection
-        # recogniser returns true for any String — the property is
-        # really tracked in the flow analysis (interpolation,
-        # concatenation, RBS::Extended `return: literal-string`)
-        # rather than recovered by inspecting an arbitrary string.
+        # `literal-string` is a flow-tracked predicate, not a value-level predicate: a String is
+        # literal-string when it is known to come from a source-code literal (or composition of
+        # literals). Every concrete `Constant<String>` is already literal by construction, so the
+        # inspection recogniser returns true for any String — the property is really tracked in the flow
+        # analysis (interpolation, concatenation, RBS::Extended `return: literal-string`) rather than
+        # recovered by inspecting an arbitrary string.
         literal_string: ->(v) { v.is_a?(String) }
       }.freeze
 
-      # Maps `[base_class_name, predicate_id]` pairs to their
-      # kebab-case canonical name. Registered shapes print
-      # through `describe`; unregistered combinations fall back
-      # to the operator form.
+      # Maps `[base_class_name, predicate_id]` pairs to their kebab-case canonical name. Registered
+      # shapes print through `describe`; unregistered combinations fall back to the operator form.
       #
-      # ADR-15 Phase 4b.x — `Ractor.make_shareable` (not `.freeze`)
-      # because the keys are nested two-element Arrays. Plain
-      # `.freeze` would leave the inner arrays mutable, so a
-      # worker Ractor reading `CANONICAL_NAMES[[base, predicate]]`
-      # would trip `Ractor::IsolationError`.
+      # ADR-15 Phase 4b.x — `Ractor.make_shareable` (not `.freeze`) because the keys are nested
+      # two-element Arrays. Plain `.freeze` would leave the inner arrays mutable, so a worker Ractor
+      # reading `CANONICAL_NAMES[[base, predicate]]` would trip `Ractor::IsolationError`.
       CANONICAL_NAMES = Ractor.make_shareable({
                                                 ["String", :lowercase] => "lowercase-string",
                                                 ["String", :not_lowercase] => "non-lowercase-string",
@@ -239,21 +198,15 @@ module Rigor
                                               })
       private_constant :CANONICAL_NAMES
 
-      # Bidirectional `predicate_id ↔ complement_predicate_id`
-      # registry. `~Refined[base, p]` narrows to
-      # `Refined[base, COMPLEMENT_PAIRS[p]]` when the part is the
-      # refinement's base — the precise carrier the spec promises
-      # under the `~T` operator. Predicates without a registered
-      # complement fall back to the imprecise but sound
-      # `Difference[part, refined]` carrier from the existing
-      # narrowing rule.
+      # Bidirectional `predicate_id ↔ complement_predicate_id` registry. `~Refined[base, p]` narrows to
+      # `Refined[base, COMPLEMENT_PAIRS[p]]` when the part is the refinement's base — the precise carrier
+      # the spec promises under the `~T` operator. Predicates without a registered complement fall back
+      # to the imprecise but sound `Difference[part, refined]` carrier from the existing narrowing rule.
       #
-      # Adding a new pair here is an additive change: register the
-      # complement predicate in {PREDICATES}, give it a kebab-case
-      # canonical name in {CANONICAL_NAMES}, and add the bidirectional
-      # entry below. No call site needs to know about the new pair —
-      # `complement_refined` consults this map and routes through
-      # the registered complement automatically.
+      # Adding a new pair here is an additive change: register the complement predicate in {PREDICATES},
+      # give it a kebab-case canonical name in {CANONICAL_NAMES}, and add the bidirectional entry below.
+      # No call site needs to know about the new pair — `complement_refined` consults this map and
+      # routes through the registered complement automatically.
       COMPLEMENT_PAIRS = {
         lowercase: :not_lowercase,
         not_lowercase: :lowercase,

data/lib/rigor/type/singleton.rb

@@ -7,13 +7,11 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # The singleton type for a Ruby class or module. Inhabitants are the
-    # class object itself (e.g. the constant `Foo`), not its instances.
-    # In RBS this corresponds to `singleton(Foo)`.
+    # The singleton type for a Ruby class or module. Inhabitants are the class object itself (e.g. the
+    # constant `Foo`), not its instances. In RBS this corresponds to `singleton(Foo)`.
     #
-    # `Singleton[Foo]` and `Nominal[Foo]` share the same `class_name` but
-    # are NEVER equal; they describe disjoint values (the class object vs.
-    # instances of the class).
+    # `Singleton[Foo]` and `Nominal[Foo]` share the same `class_name` but are NEVER equal; they describe
+    # disjoint values (the class object vs. instances of the class).
     #
     # See docs/type-specification/rbs-compatible-types.md (singleton(T)).
     class Singleton

data/lib/rigor/type/struct_class.rb

@@ -7,25 +7,20 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # The class object produced by `Struct.new(:x, :y)` (ADR-48 Struct
-    # follow-up). The mutable sibling of {DataClass}: it models the *class*
-    # (the value bound to `Point` in `Point = Struct.new(:x, :y)`, or the
-    # anonymous superclass in `class Point < Struct.new(:x, :y)`), carrying
-    # the ordered member-name list so `Point.new(...)` can materialise a
-    # {StructInstance}.
+    # The class object produced by `Struct.new(:x, :y)` (ADR-48 Struct follow-up). The mutable sibling of
+    # {DataClass}: it models the *class* (the value bound to `Point` in `Point = Struct.new(:x, :y)`, or
+    # the anonymous superclass in `class Point < Struct.new(:x, :y)`), carrying the ordered member-name
+    # list so `Point.new(...)` can materialise a {StructInstance}.
     #
-    # `keyword_init` records the `Struct.new(..., keyword_init: true)` flag
-    # so `.new` only materialises a precise instance for the matching call
-    # form — a positional `.new(1, 2)` on a `keyword_init: true` struct, or
-    # a keyword `.new(x: 1)` on a positional struct, is a different runtime
-    # shape and must degrade rather than fold a wrong member map.
+    # `keyword_init` records the `Struct.new(..., keyword_init: true)` flag so `.new` only materialises a
+    # precise instance for the matching call form — a positional `.new(1, 2)` on a `keyword_init: true`
+    # struct, or a keyword `.new(x: 1)` on a positional struct, is a different runtime shape and must
+    # degrade rather than fold a wrong member map.
     #
-    # `class_name` carries the binding name when known (the named-subclass
-    # form) and is `nil` for the anonymous result of a bare `Struct.new(...)`
-    # before it is assigned to a constant.
+    # `class_name` carries the binding name when known (the named-subclass form) and is `nil` for the
+    # anonymous result of a bare `Struct.new(...)` before it is assigned to a constant.
     #
-    # Equality and hashing are structural over the member list, the class
-    # name, and the keyword-init flag.
+    # Equality and hashing are structural over the member list, the class name, and the keyword-init flag.
     #
     # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
     class StructClass

data/lib/rigor/type/struct_instance.rb

@@ -7,28 +7,23 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A `Struct.new` value instance (ADR-48 Struct follow-up) —
-    # `Point.new(1, 2)`. The mutable sibling of {DataInstance}: a closed,
-    # total, class-tagged member map (member name -> value type),
+    # A `Struct.new` value instance (ADR-48 Struct follow-up) — `Point.new(1, 2)`. The mutable sibling of
+    # {DataInstance}: a closed, total, class-tagged member map (member name -> value type),
     # HashShape-shaped but nominal.
     #
-    # Unlike {DataInstance}, a `Struct` instance is **mutable** — `s.x = v`,
-    # `s[:x] = v`, and escape can invalidate the member map. The folding
-    # tier therefore only projects member reads off a **fresh** instance
-    # (the transient receiver of a `.new(...).x` / `.with(...).x` chain,
-    # which provably cannot have been mutated between materialisation and
-    # the read); a read off a *stored* binding degrades to `Dynamic[top]`
-    # rather than fold a possibly-stale member value. Promoting the
-    # fold to mutation-free bound locals is the deferred slice 3 (see ADR).
+    # Unlike {DataInstance}, a `Struct` instance is **mutable** — `s.x = v`, `s[:x] = v`, and escape can
+    # invalidate the member map. The folding tier therefore only projects member reads off a **fresh**
+    # instance (the transient receiver of a `.new(...).x` / `.with(...).x` chain, which provably cannot
+    # have been mutated between materialisation and the read); a read off a *stored* binding degrades to
+    # `Dynamic[top]` rather than fold a possibly-stale member value. Promoting the fold to mutation-free
+    # bound locals is the deferred slice 3 (see ADR).
     #
-    # That mutability-gating lives in the dispatch tier (`StructFolding`),
-    # not the carrier: the carrier itself just records the member map. Like
-    # {DataInstance}, non-folded methods project to the `Struct` nominal (or
-    # the tagged class) through {RbsDispatch}'s `receiver_descriptor`, so
-    # non-member calls resolve without mis-firing undefined-method.
+    # That mutability-gating lives in the dispatch tier (`StructFolding`), not the carrier: the carrier
+    # itself just records the member map. Like {DataInstance}, non-folded methods project to the
+    # `Struct` nominal (or the tagged class) through {RbsDispatch}'s `receiver_descriptor`, so non-member
+    # calls resolve without mis-firing undefined-method.
     #
-    # Equality and hashing are structural over the (member -> type) map and
-    # the class name.
+    # Equality and hashing are structural over the (member -> type) map and the class name.
     #
     # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
     class StructInstance
@@ -67,9 +62,8 @@ module Rigor
         "#{class_name || 'Struct'}(#{rendered.join(', ')})"
       end
 
-      # Erases to the tagging class nominal (conservative: the structural
-      # members are not RBS-expressible as a class instance). The
-      # anonymous case erases to the `Struct` supertype.
+      # Erases to the tagging class nominal (conservative: the structural members are not RBS-expressible
+      # as a class instance). The anonymous case erases to the `Struct` supertype.
       def erase_to_rbs
         name = class_name
         return "Struct" if name.nil?

data/lib/rigor/type/tuple.rb

@@ -7,30 +7,25 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A heterogeneous, fixed-arity array shape. Inhabitants are exactly
-    # the Ruby `Array` instances whose length matches `elements.size`
-    # and whose element at position `i` inhabits `elements[i]`.
+    # A heterogeneous, fixed-arity array shape. Inhabitants are exactly the Ruby `Array` instances whose
+    # length matches `elements.size` and whose element at position `i` inhabits `elements[i]`.
     #
-    # In RBS this corresponds to the tuple form `[A, B, C]`. A tuple
-    # is always a subtype of `Array[union(elements)]`; method dispatch
-    # therefore degrades to the underlying `Nominal[Array, [union]]`
-    # while acceptance keeps the per-position precision.
+    # In RBS this corresponds to the tuple form `[A, B, C]`. A tuple is always a subtype of
+    # `Array[union(elements)]`; method dispatch therefore degrades to the underlying `Nominal[Array,
+    # [union]]` while acceptance keeps the per-position precision.
     #
-    # Slice 5 phase 1 introduces the carrier and surfaces it from the
-    # `ArrayNode` literal handler when every element is a non-splat
-    # value. Tuple-aware refinements (`tuple[0]`, `tuple.first`,
-    # destructuring) are implemented in `ShapeDispatch`, which runs
-    # above {Rigor::Inference::MethodDispatcher::RbsDispatch}.
+    # Slice 5 phase 1 introduces the carrier and surfaces it from the `ArrayNode` literal handler when
+    # every element is a non-splat value. Tuple-aware refinements (`tuple[0]`, `tuple.first`,
+    # destructuring) are implemented in `ShapeDispatch`, which runs above
+    # {Rigor::Inference::MethodDispatcher::RbsDispatch}.
     #
-    # Equality and hashing are structural across an ordered, frozen
-    # element list. The empty Tuple `Tuple[]` is permitted; the array
-    # literal handler keeps `[]` as raw `Nominal[Array]` (no element
-    # evidence to lock the arity), but external constructors MAY build
-    # `Tuple[]` directly when the zero-arity discipline is intended.
+    # Equality and hashing are structural across an ordered, frozen element list. The empty Tuple
+    # `Tuple[]` is permitted; the array literal handler keeps `[]` as raw `Nominal[Array]` (no element
+    # evidence to lock the arity), but external constructors MAY build `Tuple[]` directly when the
+    # zero-arity discipline is intended.
     #
     # See docs/type-specification/rbs-compatible-types.md (tuple) and
-    # docs/type-specification/rigor-extensions.md (hash-shape and
-    # tuple kin).
+    # docs/type-specification/rigor-extensions.md (hash-shape and tuple kin).
     class Tuple
       attr_reader :elements
 

data/lib/rigor/type/union.rb

@@ -6,12 +6,11 @@ require_relative "acceptance_router"
 
 module Rigor
   module Type
-    # A normalized non-empty union of two or more distinct types. Unions are
-    # constructed exclusively through Rigor::Type::Combinator.union, which
-    # flattens nested unions, deduplicates structurally-equal members, and
-    # collapses single-member or empty results to the appropriate scalar
-    # type. Direct calls to .new are an internal contract: callers MUST pass
-    # an already-normalized members array.
+    # A normalized non-empty union of two or more distinct types. Unions are constructed exclusively
+    # through Rigor::Type::Combinator.union, which flattens nested unions, deduplicates
+    # structurally-equal members, and collapses single-member or empty results to the appropriate scalar
+    # type. Direct calls to .new are an internal contract: callers MUST pass an already-normalized
+    # members array.
     #
     # See docs/type-specification/normalization.md.
     class Union
@@ -26,22 +25,19 @@ module Rigor
         freeze
       end
 
-      # Display-only adoption of two concise RBS spellings for the
-      # union (see docs/type-specification/normalization.md § "Interaction
-      # with display" and rbs-compatible-types.md § "Optionals"). Both are
-      # purely cosmetic: `@members` keeps every carrier verbatim, so the
-      # underlying type identity, RBS erasure, and round-trip are unchanged
-      # — only the human-facing rendering reads like the RBS the user wrote.
+      # Display-only adoption of two concise RBS spellings for the union (see
+      # docs/type-specification/normalization.md § "Interaction with display" and rbs-compatible-types.md
+      # § "Optionals"). Both are purely cosmetic: `@members` keeps every carrier verbatim, so the
+      # underlying type identity, RBS erasure, and round-trip are unchanged — only the human-facing
+      # rendering reads like the RBS the user wrote.
       #
-      #   * `true | false`           → `bool`   (the RBS boolean alias). The
-      #     `bool` token leads the rendering, so `false | Foo | true` reads
-      #     as `bool | Foo` rather than burying the pair mid-list.
-      #   * `T | nil`                → `T?`     (the RBS optional sugar). Only
-      #     applied when exactly one *logical* member remains beside `nil`,
-      #     matching the rbs gem's own `to_s`: a multi-member union such as
-      #     `Integer | String | nil` stays explicit rather than gaining a
-      #     parenthesised `(Integer | String)?`. The two collapses compose,
-      #     so `false | true | nil` reads as `bool?`.
+      #   * `true | false`           → `bool`   (the RBS boolean alias). The `bool` token leads the
+      #     rendering, so `false | Foo | true` reads as `bool | Foo` rather than burying the pair
+      #     mid-list.
+      #   * `T | nil`                → `T?`     (the RBS optional sugar). Only applied when exactly one
+      #     *logical* member remains beside `nil`, matching the rbs gem's own `to_s`: a multi-member
+      #     union such as `Integer | String | nil` stays explicit rather than gaining a parenthesised
+      #     `(Integer | String)?`. The two collapses compose, so `false | true | nil` reads as `bool?`.
       def describe(verbosity = :short)
         return "#{optional_inner(verbosity)}?" if optional?
 
@@ -53,22 +49,16 @@ module Rigor
         end
       end
 
-      # ADR-1 § "RBS round-trip is lossless" + the value-lattice
-      # rule `untyped | T = untyped` (every `T` is gradually
-      # consistent with `untyped`). When any union member erases
-      # to `"untyped"`, the whole union erases to `"untyped"` —
-      # the RBS surface has no carrier for "Dynamic-origin
-      # alongside a static facet", and the gradual-consistency
-      # contract guarantees the substitution is sound at every
+      # ADR-1 § "RBS round-trip is lossless" + the value-lattice rule `untyped | T = untyped` (every `T`
+      # is gradually consistent with `untyped`). When any union member erases to `"untyped"`, the whole
+      # union erases to `"untyped"` — the RBS surface has no carrier for "Dynamic-origin alongside a
+      # static facet", and the gradual-consistency contract guarantees the substitution is sound at every
       # call site.
       #
-      # Post-erasure dedupe removes `String | String` artefacts
-      # that arise when two structurally-distinct `Constant`
-      # carriers (e.g. `Constant<"Alice">` / `Constant<"Bob">`)
-      # share an RBS-erased envelope. The members themselves
-      # are already structurally deduped at construction by
-      # `Type::Combinator.union`, but the post-erase strings
-      # can collide.
+      # Post-erasure dedupe removes `String | String` artefacts that arise when two structurally-distinct
+      # `Constant` carriers (e.g. `Constant<"Alice">` / `Constant<"Bob">`) share an RBS-erased envelope.
+      # The members themselves are already structurally deduped at construction by
+      # `Type::Combinator.union`, but the post-erase strings can collide.
       def erase_to_rbs
         erased = members.map(&:erase_to_rbs)
         return "untyped" if erased.include?("untyped")
@@ -100,9 +90,8 @@ module Rigor
 
       private
 
-      # Both `true` and `false` literals are present, so the pair can
-      # render as `bool`. A union carrying only one of them stays a
-      # plain literal (`true` / `false`) — that asymmetry is meaningful.
+      # Both `true` and `false` literals are present, so the pair can render as `bool`. A union carrying
+      # only one of them stays a plain literal (`true` / `false`) — that asymmetry is meaningful.
       def boolean_pair?
         members.any? { |m| boolean_literal?(m, true) } &&
           members.any? { |m| boolean_literal?(m, false) }
@@ -121,10 +110,9 @@ module Rigor
         member.is_a?(Constant) && member.value.nil?
       end
 
-      # `nil` is present and, once the `bool` pair is treated as a
-      # single logical member, exactly one non-`nil` member remains —
-      # so the whole union renders as `T?`. Counting the bool pair as
-      # one is what lets `false | true | nil` reach `bool?`.
+      # `nil` is present and, once the `bool` pair is treated as a single logical member, exactly one
+      # non-`nil` member remains — so the whole union renders as `T?`. Counting the bool pair as one is
+      # what lets `false | true | nil` reach `bool?`.
       def optional?
         return false unless members.any? { |m| nil_literal?(m) }
 

data/lib/rigor/type_node/generic.rb

@@ -9,20 +9,13 @@ module Rigor
     # sequence of type-argument nodes already produced by the
     # parser at one level of depth.
     #
-    # Args are themselves {TypeNode::Identifier} or
-    # {TypeNode::Generic}. Nested generics ride the same shape:
-    # `Pick<Address, "name" | "surname">` reaches the resolver as
-    # `Generic("Pick", [Identifier("Address"), Generic("Union", [...])])`
-    # — actually the union spelling depends on the parser's
-    # eventual convention (slice 3 pins it); for now the field
-    # set is the only public commitment.
+    # Args are themselves {TypeNode::Identifier} or {TypeNode::Generic}. Nested generics ride the same
+    # shape: `Pick<Address, "name" | "surname">` reaches the resolver as
+    # `Generic("Pick", [Identifier("Address"), Union([...])])`.
     #
-    # The carrier is intentionally permissive about `args.size`.
-    # The grammar-level rule "no brackets ⇒ Identifier; brackets ⇒
-    # Generic" lives on the parser side; nothing here forbids a
-    # zero-arg Generic so plugins can synthesise nodes for
-    # diagnostic or testing purposes without the parser fighting
-    # back.
+    # The carrier is intentionally permissive about `args.size`. The grammar-level rule "no brackets ⇒
+    # Identifier; brackets ⇒ Generic" lives on the parser side; nothing here forbids a zero-arg Generic
+    # so plugins can synthesise nodes for diagnostic or testing purposes without the parser fighting back.
     class Generic < Data.define(:head, :args)
       def initialize(head:, args:)
         unless head.is_a?(String) && !head.empty?
@@ -38,10 +31,9 @@ module Rigor
                 "TypeNode::IntegerLiteral, got #{args.inspect}"
         end
 
-        # Freeze the String head + Array args so the Data
-        # object is `Ractor.shareable?`. Each `a` is already a
-        # shareable TypeNode value object (checked above), so
-        # freezing the wrapping Array is sufficient.
+        # Freeze the String head + Array args so the Data object is `Ractor.shareable?`. Each `a` is
+        # already a shareable TypeNode value object (checked above), so freezing the wrapping Array
+        # is sufficient.
         frozen_head = head.frozen? ? head : head.dup.freeze
         frozen_args = args.frozen? ? args : args.dup.freeze
         super(head: frozen_head, args: frozen_args)
@@ -49,15 +41,11 @@ module Rigor
 
       private
 
-      # ADR-13 slice 3 expanded the accepted set to include
-      # {IntegerLiteral} so the parser can emit a uniform AST for
-      # `int<5, 10>` (angle bounds) and `int_mask[1, 2, 4]`
-      # (square-bracketed bitflag union). The follow-up further
-      # admits {SymbolLiteral} / {StringLiteral} / {IndexedAccess}
-      # / {Union} so `Pick[T, :a | "b"]` carries through to the
-      # resolver as a uniform AST. Slice 1 originally accepted
-      # only `Identifier` / `Generic`; every later addition stays
-      # additive — every slice-1-shape Generic remains valid.
+      # ADR-13 slice 3 expanded the accepted set to include {IntegerLiteral} so the parser can emit a
+      # uniform AST for `int<5, 10>` (angle bounds) and `int_mask[1, 2, 4]` (square-bracketed bitflag
+      # union). The follow-up further admits {SymbolLiteral} / {StringLiteral} / {IndexedAccess} /
+      # {Union} so `Pick[T, :a | "b"]` carries through to the resolver as a uniform AST. Every addition
+      # stays additive — every earlier-shape Generic remains valid.
       def valid_arg?(arg)
         arg.is_a?(Identifier) || arg.is_a?(Generic) || arg.is_a?(IntegerLiteral) ||
           arg.is_a?(SymbolLiteral) || arg.is_a?(StringLiteral) ||