rigortype 0.2.7 → 0.2.8

data/lib/rigor/type/constant.rb

@@ -7,15 +7,13 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A literal carrier under ADR-3 OQ1 Option C (Hybrid). Wraps a Ruby
-    # literal value of one of the supported immutable-ish classes. Compound
-    # literal shapes (Tuple, HashShape, Record) get dedicated classes in
-    # later slices; Range is carried only when both static endpoints are
-    # known enough for tuple slicing.
+    # A literal carrier under ADR-3 OQ1 Option C (Hybrid). Wraps a Ruby literal value of one of the
+    # supported immutable-ish classes. Compound literal shapes (Tuple, HashShape, Record) get dedicated
+    # classes in later slices; Range is carried only when both static endpoints are known enough for
+    # tuple slicing.
     #
-    # See docs/adr/4-type-inference-engine.md for the tentative answer to
-    # the open question and docs/type-specification/rigor-extensions.md for
-    # the refinement neighbourhood this carrier lives in.
+    # See docs/adr/4-type-inference-engine.md for the tentative answer to the open question and
+    # docs/type-specification/rigor-extensions.md for the refinement neighbourhood this carrier lives in.
     class Constant
       SCALAR_CLASSES = [
         Integer,
@@ -28,10 +26,9 @@ module Rigor
         Regexp,
         Pathname,
         ::Set,
-        # `Date` covers `DateTime` (a subclass). `Time` is core.
-        # Both arise only from deterministic constructor folding
-        # (`Date.new` / `Time.utc`) — there is no Date / Time
-        # literal node — so a `Constant` carrier is always sound.
+        # `Date` covers `DateTime` (a subclass). `Time` is core. Both arise only from deterministic
+        # constructor folding (`Date.new` / `Time.utc`) — there is no Date / Time literal node — so a
+        # `Constant` carrier is always sound.
         Date,
         Time,
         TrueClass,
@@ -56,22 +53,18 @@ module Rigor
         freeze
       end
 
-      # Mutable-ish carriers are stored as a frozen copy so a later
-      # in-place mutation cannot rewrite the literal under us. `Time`
-      # joins `String` / `Set` here: `Time#localtime` mutates the
-      # receiver's zone in place, so the carrier holds a frozen copy
-      # (the catalog also blocklists the mutators). `Date` is already
-      # immutable, but is duped-and-frozen for symmetry.
+      # Mutable-ish carriers are stored as a frozen copy so a later in-place mutation cannot rewrite the
+      # literal under us. `Time` joins `String` / `Set` here: `Time#localtime` mutates the receiver's
+      # zone in place, so the carrier holds a frozen copy (the catalog also blocklists the mutators).
+      # `Date` is already immutable, but is duped-and-frozen for symmetry.
       def freezable_carrier?(value)
         value.is_a?(String) || value.is_a?(::Set) ||
           value.is_a?(Date) || value.is_a?(Time)
       end
 
-      # `Date#inspect` / `DateTime#inspect` spell out the internal
-      # astronomical-Julian-day representation, which is unreadable
-      # in a diagnostic. ISO-8601 is the compact, deterministic
-      # form. `Time#inspect` is already compact (`2026-01-01
-      # 00:00:00 UTC`), so it keeps the default.
+      # `Date#inspect` / `DateTime#inspect` spell out the internal astronomical-Julian-day representation,
+      # which is unreadable in a diagnostic. ISO-8601 is the compact, deterministic form. `Time#inspect`
+      # is already compact (`2026-01-01 00:00:00 UTC`), so it keeps the default.
       def describe(_verbosity = :short)
         case value
         when Date then value.iso8601
@@ -79,17 +72,13 @@ module Rigor
         end
       end
 
-      # RBS supports `Literal` types for booleans, nil, integer
-      # literals (positive and negative), symbol literals, and
-      # string literals. Erasing to these preserves the
-      # carrier's precision at the RBS boundary — `Constant<64>`
-      # round-trips as `64`, not as `Integer` — and
-      # `RbsTypeTranslator#translate_literal` already maps the
-      # parsed RBS Literal back to `Constant`. Scalar carriers
-      # without RBS Literal support (Float, Range, Rational,
-      # Complex, Regexp, Pathname) keep their pre-existing
-      # widen-to-class-name behaviour because RBS rejects their
-      # literal spellings as syntax errors.
+      # RBS supports `Literal` types for booleans, nil, integer literals (positive and negative), symbol
+      # literals, and string literals. Erasing to these preserves the carrier's precision at the RBS
+      # boundary — `Constant<64>` round-trips as `64`, not as `Integer` — and
+      # `RbsTypeTranslator#translate_literal` already maps the parsed RBS Literal back to `Constant`.
+      # Scalar carriers without RBS Literal support (Float, Range, Rational, Complex, Regexp, Pathname)
+      # keep their pre-existing widen-to-class-name behaviour because RBS rejects their literal spellings
+      # as syntax errors.
       def erase_to_rbs
         case value
         when true then "true"

data/lib/rigor/type/data_class.rb

@@ -7,23 +7,18 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # The class object produced by `Data.define(:x, :y)` (ADR-48). Models
-    # the *class*, not an instance — the value bound to `Point` in
-    # `Point = Data.define(:x, :y)` or the anonymous superclass in
-    # `class Point < Data.define(:x, :y)`. Parameterised by the ordered
-    # member-name list so that `Point.new(...)` can materialise a precise
-    # {DataInstance}.
+    # The class object produced by `Data.define(:x, :y)` (ADR-48). Models the *class*, not an instance —
+    # the value bound to `Point` in `Point = Data.define(:x, :y)` or the anonymous superclass in `class
+    # Point < Data.define(:x, :y)`. Parameterised by the ordered member-name list so that `Point.new(...)`
+    # can materialise a precise {DataInstance}.
     #
-    # `class_name` carries the binding name when known (the named-subclass
-    # form, ADR-48 slice 3) and is `nil` for the anonymous result of a bare
-    # `Data.define(...)` before it is assigned to a constant. It tags the
-    # instances `.new` produces; it does not change the carrier's folding
-    # behaviour.
+    # `class_name` carries the binding name when known (the named-subclass form, ADR-48 slice 3) and is
+    # `nil` for the anonymous result of a bare `Data.define(...)` before it is assigned to a constant. It
+    # tags the instances `.new` produces; it does not change the carrier's folding behaviour.
     #
-    # Equality and hashing are structural over the member list and the
-    # class name. Two distinct `Data.define(:x)` results are equal *as
-    # types* — they describe the same shape; the engine distinguishes the
-    # constants they are bound to by the binding, not by the carrier.
+    # Equality and hashing are structural over the member list and the class name. Two distinct
+    # `Data.define(:x)` results are equal *as types* — they describe the same shape; the engine
+    # distinguishes the constants they are bound to by the binding, not by the carrier.
     #
     # See docs/adr/48-data-struct-value-folding.md.
     class DataClass

data/lib/rigor/type/data_instance.rb

@@ -7,26 +7,21 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A `Data.define` value instance (ADR-48) — `Point.new(1, 2)`. Models a
-    # closed, total, class-tagged member map (member name -> value type).
-    # HashShape-shaped, but nominal: a `DataInstance` tagged `Point` is a
-    # different type from one tagged `Line` even with identical members,
-    # and it erases to its class nominal rather than an RBS record.
+    # A `Data.define` value instance (ADR-48) — `Point.new(1, 2)`. Models a closed, total, class-tagged
+    # member map (member name -> value type). HashShape-shaped, but nominal: a `DataInstance` tagged
+    # `Point` is a different type from one tagged `Line` even with identical members, and it erases to
+    # its class nominal rather than an RBS record.
     #
-    # `Data` instances are frozen, so the member map is sound for the
-    # instance's whole lifetime — the reason `Data` is the first target
-    # (a `Struct` instance can be mutated through a setter or `[]=`, which
-    # would invalidate the map; that follow-up is deferred — see ADR-48).
+    # `Data` instances are frozen, so the member map is sound for the instance's whole lifetime — the
+    # reason `Data` is the first target (a `Struct` instance can be mutated through a setter or `[]=`,
+    # which would invalidate the map; that follow-up is deferred — see ADR-48).
     #
-    # Member reads fold to the member's type (`Point.new(1, 2).x` ->
-    # `Constant[1]`); `[]`, `to_h`, `deconstruct`, `deconstruct_keys`,
-    # `members`, and `with` project precisely. Methods this carrier does
-    # not fold project to the `Data` nominal (or the tagged class) through
-    # {RbsDispatch}'s `receiver_descriptor`, so non-member calls resolve
-    # without mis-firing undefined-method.
+    # Member reads fold to the member's type (`Point.new(1, 2).x` -> `Constant[1]`); `[]`, `to_h`,
+    # `deconstruct`, `deconstruct_keys`, `members`, and `with` project precisely. Methods this carrier
+    # does not fold project to the `Data` 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.
     class DataInstance
@@ -65,9 +60,8 @@ module Rigor
         "#{class_name || 'Data'}(#{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 `Data` 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 `Data` supertype.
       def erase_to_rbs
         name = class_name
         return "Data" if name.nil?

data/lib/rigor/type/difference.rb

@@ -6,35 +6,26 @@ require_relative "acceptance_router"
 
 module Rigor
   module Type
-    # `Difference[base, removed]` — the value set of `base` minus
-    # the value set of `removed`. Implements the point-removal
-    # half of the OQ3 refinement-carrier strategy
-    # ([ADR-3](docs/adr/3-type-representation.md), Working
-    # Decision Option C):
+    # `Difference[base, removed]` — the value set of `base` minus the value set of `removed`. Implements
+    # the point-removal half of the OQ3 refinement-carrier strategy ([ADR-3](docs/adr/3-type-representation.md),
+    # Working Decision Option C):
     #
     #   non-empty-string   = Difference[Nominal[String], Constant[""]]
     #   non-zero-int       = Difference[Nominal[Integer], Constant[0]]
     #   non-empty-array[T] = Difference[Nominal[Array, [T]], Tuple[]]
     #   non-empty-hash[K,V] = Difference[Nominal[Hash, [K,V]], HashShape{}]
     #
-    # The carrier itself is structural: it stores `base` and
-    # `removed` as inner `Type` references and answers projection
-    # / acceptance / display questions by composing those inner
-    # answers per the lattice algebra in
-    # [`value-lattice.md`](docs/type-specification/value-lattice.md).
-    # The canonical-name registry (display side) lives in
-    # `Rigor::Type::Combinator` and prints kebab-case names like
-    # `non-empty-string` for the recognised shapes; unrecognised
-    # differences fall back to the raw `base - removed`
-    # operator form per [`type-operators.md`](docs/type-specification/type-operators.md).
+    # The carrier itself is structural: it stores `base` and `removed` as inner `Type` references and
+    # answers projection / acceptance / display questions by composing those inner answers per the
+    # lattice algebra in [`value-lattice.md`](docs/type-specification/value-lattice.md). The
+    # canonical-name registry (display side) lives in `Rigor::Type::Combinator` and prints kebab-case
+    # names like `non-empty-string` for the recognised shapes; unrecognised differences fall back to the
+    # raw `base - removed` operator form per [`type-operators.md`](docs/type-specification/type-operators.md).
     #
-    # Construction goes through `Type::Combinator.difference` /
-    # `Combinator.non_empty_string` etc. — direct `.new` calls
-    # are an internal contract; callers MUST ensure both bounds
-    # are valid `Rigor::Type` values and that `removed` is a
-    # subtype-or-equal of `base` (otherwise the difference does
-    # not narrow anything and a normalisation upstream should
-    # collapse to `base`).
+    # Construction goes through `Type::Combinator.difference` / `Combinator.non_empty_string` etc. —
+    # direct `.new` calls are an internal contract; callers MUST ensure both bounds are valid
+    # `Rigor::Type` values and that `removed` is a subtype-or-equal of `base` (otherwise the difference
+    # does not narrow anything and a normalisation upstream should collapse to `base`).
     class Difference
       attr_reader :base, :removed
 
@@ -51,8 +42,8 @@ module Rigor
         "#{base.describe(verbosity)} - #{removed.describe(verbosity)}"
       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
@@ -81,15 +72,13 @@ module Rigor
 
       private
 
-      # Renders the kebab-case shorthand for recognised
-      # imported-built-in shapes. Parameterised bases keep their
-      # type-args in the canonical form (`non-empty-array[T]`,
-      # `non-empty-hash[K, V]`) so element-precision survives the
-      # display round-trip. Unrecognised shapes fall back to the
-      # raw `base - removed` operator form.
+      # Renders the kebab-case shorthand for recognised imported-built-in shapes. Parameterised bases
+      # keep their type-args in the canonical form (`non-empty-array[T]`, `non-empty-hash[K, V]`) so
+      # element-precision survives the display round-trip. Unrecognised shapes fall back to the raw
+      # `base - removed` operator form.
       #
-      # The recognised set is kept in sync with the imported-built-in
-      # catalogue ([`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md)).
+      # The recognised set is kept in sync with the imported-built-in catalogue
+      # ([`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md)).
       def canonical_name
         return nil unless base.is_a?(Nominal)
 

data/lib/rigor/type/dynamic.rb

@@ -6,11 +6,9 @@ require_relative "acceptance_router"
 
 module Rigor
   module Type
-    # The dynamic-origin wrapper: marks values whose type came from an
-    # unchecked source. Carries a static facet that records the analyzer's
-    # best static knowledge. See docs/type-specification/value-lattice.md
-    # for the algebra and docs/type-specification/special-types.md for the
-    # untyped/Dynamic[T] relationship.
+    # The dynamic-origin wrapper: marks values whose type came from an unchecked source. Carries a static
+    # facet that records the analyzer's best static knowledge. See docs/type-specification/value-lattice.md
+    # for the algebra and docs/type-specification/special-types.md for the untyped/Dynamic[T] relationship.
     #
     # Construct via Rigor::Type::Combinator.dynamic(static_facet).
     class Dynamic

data/lib/rigor/type/hash_shape.rb

@@ -7,20 +7,16 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A hash shape with statically known keys. Inhabitants are Ruby
-    # `Hash` instances whose known entries inhabit the corresponding
-    # value types. RBS records correspond to the exact closed subset;
-    # Rigor extends that carrier with optional keys, read-only entry
-    # views, and an open/closed extra-key policy.
+    # A hash shape with statically known keys. Inhabitants are Ruby `Hash` instances whose known entries
+    # inhabit the corresponding value types. RBS records correspond to the exact closed subset; Rigor
+    # extends that carrier with optional keys, read-only entry views, and an open/closed extra-key policy.
     #
-    # Keys are restricted to Symbol and String values. Exact closed
-    # symbol-keyed shapes erase to the RBS record syntax
-    # `{ a: Integer, ?b: String }`; all other shapes degrade to
-    # `Hash[K, V]` or raw `Hash` when no useful bounds are available.
+    # Keys are restricted to Symbol and String values. Exact closed symbol-keyed shapes erase to the RBS
+    # record syntax `{ a: Integer, ?b: String }`; all other shapes degrade to `Hash[K, V]` or raw `Hash`
+    # when no useful bounds are available.
     #
-    # Equality and hashing are structural over the (key -> Rigor::Type)
-    # pair set and policy fields. Hash insertion order is preserved by
-    # the underlying storage but does NOT affect equality (matching
+    # Equality and hashing are structural over the (key -> Rigor::Type) pair set and policy fields. Hash
+    # insertion order is preserved by the underlying storage but does NOT affect equality (matching
     # Ruby's `Hash#==`).
     #
     # See docs/type-specification/rbs-compatible-types.md (records) and
@@ -29,6 +25,9 @@ module Rigor
       ALLOWED_KEY_CLASSES = [Symbol, String].freeze
       EXTRA_KEY_POLICIES = %i[open closed].freeze
       POLICY_KEYWORDS = %i[required_keys optional_keys read_only_keys extra_keys].freeze
+      # A Symbol whose text matches renders as a bare RBS record key (`lang:`) in {#erase_to_rbs};
+      # anything else must be quoted with a fat arrow (`"data-contrast" =>`). See {#erase_key_prefix}.
+      BARE_RECORD_KEY = /\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/
 
       attr_reader :pairs, :required_keys, :optional_keys, :read_only_keys, :extra_keys
 
@@ -65,15 +64,14 @@ module Rigor
         "{ #{rendered.join(', ')} }"
       end
 
-      # Erases to the RBS record form `{ a: Integer, ?b: String }`
-      # for exact closed symbol-keyed shapes. Open shapes and
-      # string-keyed closed shapes degrade to a generic Hash bound.
+      # Erases to the RBS record form `{ a: Integer, ?b: String }` for exact closed symbol-keyed shapes.
+      # Open shapes and string-keyed closed shapes degrade to a generic Hash bound.
       def erase_to_rbs
         return "{}" if pairs.empty? && closed?
         return hash_erasure unless closed?
         return hash_erasure if pairs.each_key.any? { |k| !k.is_a?(Symbol) }
 
-        rendered = pairs.map { |k, v| "#{record_key(k)}: #{v.erase_to_rbs}" }
+        rendered = pairs.map { |k, v| "#{erase_key_prefix(k)} #{v.erase_to_rbs}" }
         "{ #{rendered.join(', ')} }"
       end
 
@@ -196,6 +194,9 @@ module Rigor
         "#{prefix.join(' ')} #{value.describe(verbosity)}"
       end
 
+      # `describe` is a human-facing display contract (it feeds diagnostic messages, never a parser),
+      # so it keeps the compact `"a":` form for a quoted key. The RBS-erasure path uses
+      # {#erase_key_prefix} instead, which must emit a parseable key.
       def render_key(key)
         case key
         when Symbol then key.to_s
@@ -203,8 +204,21 @@ module Rigor
         end
       end
 
-      def record_key(key)
-        optional_key?(key) ? "?#{key}" : key.to_s
+      # An RBS record entry's key + separator, for the {#erase_to_rbs} path (which only ever sees
+      # Symbol keys — string-keyed shapes degrade to `Hash[...]` before reaching here). A Symbol whose
+      # text is a plain identifier is a bare key with a colon (`lang:`); a hyphenated / punctuated
+      # Symbol MUST use the quoted `"data-contrast" =>` form, because RBS rejects both a bare
+      # non-identifier (`data-contrast:`) and a quoted key with a colon (`"data-contrast":`). Getting
+      # this wrong made sig-gen emit an unparseable Mastodon `html_attributes` shape that crashed the
+      # whole RBS env build. Valid identifier keys (incl. Ruby keywords like `class`) keep the colon
+      # form, so only genuinely non-identifier keys change. Optional keys carry a leading `?`.
+      def erase_key_prefix(key)
+        optional = optional_key?(key) ? "?" : ""
+        if BARE_RECORD_KEY.match?(key.to_s)
+          "#{optional}#{key}:"
+        else
+          "#{optional}#{key.to_s.inspect} =>"
+        end
       end
 
       def hash_erasure

data/lib/rigor/type/integer_range.rb

@@ -7,23 +7,19 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # A bounded integer range carrier. Each bound is either an `Integer`
-    # or one of the symbolic infinities `:neg_infinity` / `:pos_infinity`.
-    # Inspired by PHPStan's `int<min, max>` family — the named aliases
-    # `positive-int` (1..), `non-negative-int` (0..), `negative-int`
-    # (..-1), `non-positive-int` (..0) all surface through this single
-    # carrier and are recovered in `describe` for human-friendly output.
+    # A bounded integer range carrier. Each bound is either an `Integer` or one of the symbolic
+    # infinities `:neg_infinity` / `:pos_infinity`. Inspired by PHPStan's `int<min, max>` family — the
+    # named aliases `positive-int` (1..), `non-negative-int` (0..), `negative-int` (..-1),
+    # `non-positive-int` (..0) all surface through this single carrier and are recovered in `describe`
+    # for human-friendly output.
     #
     # Constraints on construction:
-    # - both bounds must be either `Integer` or one of the two infinity
-    #   sentinels;
+    # - both bounds must be either `Integer` or one of the two infinity sentinels;
     # - if both bounds are concrete, `min <= max` must hold;
-    # - the universal case `(-∞, +∞)` is structurally distinct from
-    #   `Nominal[Integer]` — it carries no extra information today but
-    #   keeps the carrier closed under range narrowing.
+    # - the universal case `(-∞, +∞)` is structurally distinct from `Nominal[Integer]` — it carries no
+    #   extra information today but keeps the carrier closed under range narrowing.
     #
-    # Erasure to RBS is always "Integer": RBS itself does not natively
-    # express bounded integer ranges.
+    # Erasure to RBS is always "Integer": RBS itself does not natively express bounded integer ranges.
     class IntegerRange
       NEG_INFINITY = :neg_infinity
       POS_INFINITY = :pos_infinity
@@ -64,9 +60,8 @@ module Rigor
         int.between?(lower, upper)
       end
 
-      # Returns the lower bound as a numeric (with `-Float::INFINITY` for
-      # `:neg_infinity`). Use this in arithmetic comparisons; never compare
-      # `:neg_infinity` directly with an `Integer`.
+      # Returns the lower bound as a numeric (with `-Float::INFINITY` for `:neg_infinity`). Use this in
+      # arithmetic comparisons; never compare `:neg_infinity` directly with an `Integer`.
       def lower
         m = min
         return m if m.is_a?(Integer)

data/lib/rigor/type/intersection.rb

@@ -7,36 +7,28 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # `Intersection[M1, M2, …]` — value set is the meet of every
-    # member's value set. The carrier composes refinements that
-    # share a base, in particular the catalogued
-    # `non-empty-lowercase-string` (= `Difference[String, ""] &
-    # Refined[String, :lowercase]`) and
-    # `non-empty-uppercase-string` shapes from
-    # [`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md).
-    # See [ADR-3](docs/adr/3-type-representation.md) for the
-    # OQ3 working decision and the rationale for keeping
-    # Intersection a thin wrapper rather than per-shape carriers.
+    # `Intersection[M1, M2, …]` — value set is the meet of every member's value set. The carrier composes
+    # refinements that share a base, in particular the catalogued `non-empty-lowercase-string` (=
+    # `Difference[String, ""] & Refined[String, :lowercase]`) and `non-empty-uppercase-string` shapes
+    # from [`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md). See
+    # [ADR-3](docs/adr/3-type-representation.md) for the OQ3 working decision and the rationale for
+    # keeping Intersection a thin wrapper rather than per-shape carriers.
     #
-    # Construction MUST go through `Type::Combinator.intersection`
-    # (or the per-name factories
-    # `Combinator.non_empty_lowercase_string` /
-    # `Combinator.non_empty_uppercase_string`). The factory:
+    # Construction MUST go through `Type::Combinator.intersection` (or the per-name factories
+    # `Combinator.non_empty_lowercase_string` / `Combinator.non_empty_uppercase_string`). The factory:
     #
     # - flattens nested intersections,
     # - drops `Top` members (Top is the identity of intersection),
     # - collapses to `Bot` if any member is `Bot` (Bot is absorbing),
     # - deduplicates structurally-equal members,
-    # - sorts the surviving members by `describe(:short)` so two
-    #   structurally-equal intersections built in different orders
-    #   compare equal,
+    # - sorts the surviving members by `describe(:short)` so two structurally-equal intersections built
+    #   in different orders compare equal,
     # - returns `Top` for the empty intersection,
-    # - returns the lone member for a 1-element intersection (so
-    #   the carrier is never inhabited by a degenerate single-member
-    #   shape).
+    # - returns the lone member for a 1-element intersection (so the carrier is never inhabited by a
+    #   degenerate single-member shape).
     #
-    # Direct `.new` callers MUST pass an already-normalised member
-    # list and are expected to be tests or the combinator itself.
+    # Direct `.new` callers MUST pass an already-normalised member list and are expected to be tests or
+    # the combinator itself.
     class Intersection
       attr_reader :members
 
@@ -52,13 +44,10 @@ module Rigor
         members.map { |m| m.describe(verbosity) }.join(" & ")
       end
 
-      # An intersection of refinements over the same base type
-      # erases to that base. We use the first member's erasure
-      # because the v0.0.4 catalogue (`non-empty-lowercase-string`
-      # etc.) is restricted to same-base composition; richer
-      # cross-base intersections will need a stricter erasure
-      # rule (likely "lowest common ancestor" via the inference
-      # engine's class hierarchy).
+      # An intersection of refinements over the same base type erases to that base. We use the first
+      # member's erasure because the v0.0.4 catalogue (`non-empty-lowercase-string` etc.) is restricted
+      # to same-base composition; richer cross-base intersections will need a stricter erasure rule
+      # (likely "lowest common ancestor" via the inference engine's class hierarchy).
       def erase_to_rbs
         members.first.erase_to_rbs
       end
@@ -77,15 +66,13 @@ module Rigor
 
       private
 
-      # Maps a structurally-recognised composite shape to its
-      # kebab-case canonical name. The recognised set is kept in
-      # sync with the imported-built-in catalogue
+      # Maps a structurally-recognised composite shape to its kebab-case canonical name. The recognised
+      # set is kept in sync with the imported-built-in catalogue
       # ([`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md)).
       #
-      # Detection is order-independent — `Combinator.intersection`
-      # sorts the canonical member list, but reading the registry
-      # the other way around (a user-authored Intersection built
-      # in any order) MUST still print in its canonical spelling.
+      # Detection is order-independent — `Combinator.intersection` sorts the canonical member list, but
+      # reading the registry the other way around (a user-authored Intersection built in any order) MUST
+      # still print in its canonical spelling.
       def canonical_name
         return nil unless members.size == 2
 
@@ -99,12 +86,10 @@ module Rigor
         end
       end
 
-      # Returns a stable role tag for the recognised composite
-      # members so `canonical_name` can pattern-match on a sorted
-      # role pair regardless of construction order. Returns nil
-      # when the member is not part of any catalogued composite —
-      # any nil contribution disqualifies the canonical-name path
-      # and the operator-form fallback kicks in.
+      # Returns a stable role tag for the recognised composite members so `canonical_name` can
+      # pattern-match on a sorted role pair regardless of construction order. Returns nil when the
+      # member is not part of any catalogued composite — any nil contribution disqualifies the
+      # canonical-name path and the operator-form fallback kicks in.
       def canonical_role(member)
         case member
         when Difference

data/lib/rigor/type/nominal.rb

@@ -7,23 +7,18 @@ require_relative "plain_lattice"
 
 module Rigor
   module Type
-    # An instance type for a Ruby class or module. The class is identified by
-    # its fully-qualified Ruby name; the registry attached to the
-    # environment owns the class lookup.
+    # An instance type for a Ruby class or module. The class is identified by its fully-qualified Ruby
+    # name; the registry attached to the environment owns the class lookup.
     #
-    # Slice 4 phase 2d adds `type_args`: an ordered, frozen array of
-    # `Rigor::Type` values that carry the receiver's generic
-    # instantiation. The empty array is the canonical "raw" form
-    # (`Nominal[Array]`); a non-empty array represents an applied
-    # generic (`Nominal[Array, [Integer]]`). Two Nominals are
-    # structurally equal only when their `class_name` AND `type_args`
-    # match, so the raw form and any applied form are intentionally
-    # distinct values. Acceptance routes treat the raw form leniently
-    # for backward compatibility with phase 2b call sites that have not
-    # yet learned to carry generics.
+    # Slice 4 phase 2d adds `type_args`: an ordered, frozen array of `Rigor::Type` values that carry the
+    # receiver's generic instantiation. The empty array is the canonical "raw" form (`Nominal[Array]`); a
+    # non-empty array represents an applied generic (`Nominal[Array, [Integer]]`). Two Nominals are
+    # structurally equal only when their `class_name` AND `type_args` match, so the raw form and any
+    # applied form are intentionally distinct values. Acceptance routes treat the raw form leniently for
+    # backward compatibility with phase 2b call sites that have not yet learned to carry generics.
     #
-    # Type arguments MUST be `Rigor::Type` instances. The constructor
-    # freezes the array; callers MUST NOT mutate it after construction.
+    # Type arguments MUST be `Rigor::Type` instances. The constructor freezes the array; callers MUST NOT
+    # mutate it after construction.
     #
     # See docs/type-specification/rbs-compatible-types.md.
     class Nominal

data/lib/rigor/type/plain_lattice.rb

@@ -4,22 +4,18 @@ require_relative "../trinary"
 
 module Rigor
   module Type
-    # Supplies the lattice-membership trio for the "plain" carriers — the
-    # concrete value types that are neither a lattice extreme (`Top` /
-    # `Bot` / `Dynamic`) nor a wrapper that computes membership from an
-    # inner type.
+    # Supplies the lattice-membership trio for the "plain" carriers — the concrete value types that are
+    # neither a lattice extreme (`Top` / `Bot` / `Dynamic`) nor a wrapper that computes membership from
+    # an inner type.
     #
-    # Every such carrier answers `top` / `bot` / `dynamic` with the same
-    # `Trinary.no` ("this value is not that lattice point"), so the trio
-    # lived as a byte-identical copy in a dozen carriers. The extremes
-    # override the relevant member (`Top#top` / `Bot#bot` /
-    # `Dynamic#dynamic` answer `Trinary.yes`) and the delegators (`App`,
-    # `Difference`, `Refined`, `Union`) compute `dynamic` from their inner
+    # Every such carrier answers `top` / `bot` / `dynamic` with the same `Trinary.no` ("this value is not
+    # that lattice point"), so the trio lived as a byte-identical copy in a dozen carriers. The extremes
+    # override the relevant member (`Top#top` / `Bot#bot` / `Dynamic#dynamic` answer `Trinary.yes`) and
+    # the delegators (`App`, `Difference`, `Refined`, `Union`) compute `dynamic` from their inner
     # type(s); none of those include this module.
     #
-    # Mirrors the existing {AcceptanceRouter} / `ValueSemantics` mixins —
-    # narrow trait sharing, never carrier inheritance (which the type-object
-    # contract forbids).
+    # Mirrors the existing {AcceptanceRouter} / `ValueSemantics` mixins — narrow trait sharing, never
+    # carrier inheritance (which the type-object contract forbids).
     module PlainLattice
       def top
         Trinary.no