rigortype 0.1.3 → 0.1.5

data/lib/rigor/type/combinator.rb

@@ -13,6 +13,7 @@ require_relative "union"
 require_relative "difference"
 require_relative "refined"
 require_relative "intersection"
+require_relative "bound_method"
 
 module Rigor
   module Type
@@ -35,8 +36,14 @@ module Rigor
         Bot.instance
       end
 
+      # ADR-15 Phase 4b.x — read the eagerly-allocated
+      # `@untyped` ivar instead of `||=`. The singleton-class
+      # `@untyped = Dynamic.new(top)` initializer runs at module
+      # body (below) on the main Ractor at load time. Workers
+      # READ the populated ivar without performing the lazy
+      # write that non-main Ractors are forbidden from doing.
       def untyped
-        @untyped ||= Dynamic.new(top)
+        @untyped
       end
 
       # Wraps the static facet in a Dynamic[T] carrier. Idempotent on the
@@ -69,6 +76,14 @@ module Rigor
         Constant.new(value)
       end
 
+      # `Object#method(:name)` carrier. Stores the bound
+      # `(receiver, method_name)` pair so the dispatcher can
+      # substitute the original dispatch at `.call` / `.()` /
+      # `[]` time. See {Type::BoundMethod}.
+      def bound_method_of(receiver_type, method_name)
+        BoundMethod.new(receiver_type: receiver_type, method_name: method_name)
+      end
+
       # Bounded-integer carrier. Each bound is either an `Integer` or
       # one of `:neg_infinity` / `:pos_infinity` (sentinels exposed as
       # `IntegerRange::NEG_INFINITY` / `POS_INFINITY`).
@@ -347,7 +362,6 @@ module Rigor
       INT_MASK_UNION_LIMIT = 16
       private_constant :INT_MASK_FLAG_LIMIT, :INT_MASK_UNION_LIMIT
 
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def int_mask(flags)
         return nil unless flags.is_a?(Array) && flags.all?(Integer)
         return nil if flags.any?(&:negative?)
@@ -362,7 +376,6 @@ module Rigor
           integer_range(values.min, values.max)
         end
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # `int_mask_of[T]` — derives the int_mask closure from
       # a finite integer-literal type:
@@ -401,6 +414,99 @@ module Rigor
         end
       end
 
+      # `pick_of[T, K]` shape-projection — keeps only the entries
+      # of `T` whose key is in the literal-key set extracted from
+      # `K`. ADR-13 § "Shape projection / Restriction and removal".
+      #
+      # Phase A handles `Type::HashShape` (literal-key K).
+      # Phase B (slice 5) extends to `Type::Tuple` (integer-index
+      # K) — `pick_of[Tuple[A, B, C], 0 | 2]` evaluates to
+      # `Tuple[A, C]`. Non-shape inputs (`Type::Nominal`, etc.)
+      # return `type` unchanged ("lossy degradation"; the
+      # `dynamic.shape.lossy-projection` diagnostic that flags
+      # the boundary lands when caller-side diagnostic threading
+      # arrives).
+      def pick_of(type, keys)
+        case type
+        when HashShape then hash_shape_pick(type, keys)
+        when Tuple     then tuple_pick(type, keys)
+        else type
+        end
+      end
+
+      # `omit_of[T, K]` shape-projection — dual of {pick_of}.
+      # Drops the entries / positions whose key (or index, for a
+      # `Tuple`) is in the literal-key set extracted from `K`.
+      def omit_of(type, keys)
+        case type
+        when HashShape then hash_shape_omit(type, keys)
+        when Tuple     then tuple_omit(type, keys)
+        else type
+        end
+      end
+
+      # `partial_of[T]` shape-projection — flips every required
+      # entry of `T` to optional. ADR-13 § "Required-ness flips".
+      # Does NOT add `nil` to value types — Rigor's HashShape
+      # distinguishes "key absent" from "key present with nil
+      # value", so flipping required-ness is sufficient.
+      def partial_of(type)
+        return type unless type.is_a?(HashShape)
+
+        HashShape.new(
+          type.pairs,
+          required_keys: [],
+          optional_keys: type.pairs.keys,
+          read_only_keys: type.read_only_keys,
+          extra_keys: type.extra_keys
+        )
+      end
+
+      # `required_of[T]` shape-projection — inverse of
+      # {partial_of}; flips every optional entry to required.
+      def required_of(type)
+        return type unless type.is_a?(HashShape)
+
+        HashShape.new(
+          type.pairs,
+          required_keys: type.pairs.keys,
+          optional_keys: [],
+          read_only_keys: type.read_only_keys,
+          extra_keys: type.extra_keys
+        )
+      end
+
+      # `readonly_of[T]` shape-projection — marks every entry of
+      # `T` as read-only in the current view. View-level only —
+      # does NOT prove the underlying Ruby Hash is frozen.
+      def readonly_of(type)
+        return type unless type.is_a?(HashShape)
+
+        HashShape.new(
+          type.pairs,
+          required_keys: type.required_keys,
+          optional_keys: type.optional_keys,
+          read_only_keys: type.pairs.keys,
+          extra_keys: type.extra_keys
+        )
+      end
+
+      # Predicate that a shape-projection (`pick_of`, `omit_of`,
+      # `partial_of`, `required_of`, `readonly_of`) would degrade
+      # to "input unchanged" on this carrier. Callers consult
+      # this BEFORE invoking the projection so they can emit a
+      # `dynamic.shape.lossy-projection` diagnostic at the site
+      # where the projection was authored.
+      #
+      # `HashShape` and `Tuple` carry shape-level information
+      # the projections honour; every other carrier is lossy.
+      # Slice 5b wires diagnostic emission through `RbsExtended`
+      # / parser callers; this predicate stands alone in slice 5
+      # for unit-test coverage and future composition.
+      def shape_projection_lossy?(type)
+        !type.is_a?(HashShape) && !type.is_a?(Tuple)
+      end
+
       class << self # rubocop:disable Metrics/ClassLength
         private
 
@@ -480,6 +586,99 @@ module Rigor
           end
         end
 
+        # Literal-key set extraction for {pick_of} / {omit_of}.
+        # Accepts `Constant<Symbol|String>` or `Union[Constant…]`
+        # where every member is such a Constant. Returns `nil`
+        # when the shape can't be reduced to a finite key set
+        # (untyped, Top, Difference, Refined, mixed-kind union,
+        # etc.) — callers degrade to "input unchanged" per
+        # ADR-13's lossy-projection rule.
+        def extract_constant_key_set(type)
+          case type
+          when Constant then constant_key_set(type)
+          when Union    then union_key_set(type)
+          end
+        end
+
+        def constant_key_set(type)
+          literal_key?(type.value) ? [type.value] : nil
+        end
+
+        def union_key_set(type)
+          return nil unless type.members.all?(Constant)
+
+          values = type.members.map(&:value)
+          values.all? { |v| literal_key?(v) } ? values : nil
+        end
+
+        def literal_key?(value)
+          value.is_a?(Symbol) || value.is_a?(String)
+        end
+
+        # Rebuild a {HashShape} from the subset of `keys` the
+        # caller decided to keep. Preserves required / optional /
+        # read-only classification AND the extra-keys policy of
+        # the source shape; entries dropped from `pairs` also
+        # drop from each policy list. Used by both {pick_of}
+        # (intersection with K) and {omit_of} (set difference).
+        def rebuild_hash_shape_with_keys(shape, kept_keys)
+          HashShape.new(
+            shape.pairs.slice(*kept_keys),
+            required_keys: shape.required_keys.select { |k| kept_keys.include?(k) },
+            optional_keys: shape.optional_keys.select { |k| kept_keys.include?(k) },
+            read_only_keys: shape.read_only_keys.select { |k| kept_keys.include?(k) },
+            extra_keys: shape.extra_keys
+          )
+        end
+
+        def hash_shape_pick(type, keys)
+          key_set = extract_constant_key_set(keys)
+          return type if key_set.nil?
+
+          rebuild_hash_shape_with_keys(type, type.pairs.keys & key_set)
+        end
+
+        def hash_shape_omit(type, keys)
+          key_set = extract_constant_key_set(keys)
+          return type if key_set.nil?
+
+          rebuild_hash_shape_with_keys(type, type.pairs.keys - key_set)
+        end
+
+        # ADR-13 slice 5 — Tuple support. `K` MUST be a
+        # `Constant<Integer>` or `Union[Constant<Integer>, …]`;
+        # other K shapes (or non-integer Constants in a Union)
+        # return the input unchanged. Negative or out-of-range
+        # indices are dropped silently per slice 5's permissive
+        # take — surface diagnostics are slice 5b material.
+        def tuple_pick(type, keys)
+          index_set = extract_tuple_index_set(keys, type.elements.size)
+          return type if index_set.nil?
+
+          Tuple.new(index_set.map { |i| type.elements[i] })
+        end
+
+        def tuple_omit(type, keys)
+          index_set = extract_tuple_index_set(keys, type.elements.size)
+          return type if index_set.nil?
+
+          dropped = index_set.to_a
+          Tuple.new(type.elements.each_with_index.reject { |_, i| dropped.include?(i) }.map(&:first))
+        end
+
+        # Extracts a sorted, deduplicated set of in-range integer
+        # indices from a `Constant<Integer>` / `Union[Constant<Integer>, …]`
+        # carrier. Out-of-range indices are dropped silently; the
+        # caller decides whether an empty result still means
+        # "lossy projection" (current pick / omit just produce an
+        # empty Tuple).
+        def extract_tuple_index_set(type, size)
+          flags = extract_constant_int_set(type)
+          return nil if flags.nil?
+
+          flags.uniq.select { |i| i >= 0 && i < size }.sort
+        end
+
         def tuple_indexed_access(tuple, key)
           return top unless key.is_a?(Constant) && key.value.is_a?(Integer)
 
@@ -616,6 +815,11 @@ module Rigor
           members.sort_by { |m| m.describe(:short) }
         end
       end
+
+      # ADR-15 Phase 4b.x — eager-allocate the singleton
+      # `Dynamic[Top]` carrier on the main Ractor at load time.
+      # The `untyped` reader above just returns this ivar.
+      @untyped = Dynamic.new(Top.instance)
     end
   end
 end

data/lib/rigor/type/constant.rb

@@ -50,11 +50,24 @@ module Rigor
         value.inspect
       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.
       def erase_to_rbs
         case value
         when true then "true"
         when false then "false"
         when nil then "nil"
+        when Integer then value.to_s
+        when Symbol, String then value.inspect
         else value.class.name
         end
       end

data/lib/rigor/type/hash_shape.rb

@@ -22,7 +22,6 @@ module Rigor
     #
     # See docs/type-specification/rbs-compatible-types.md (records) and
     # docs/type-specification/rigor-extensions.md (hash shape).
-    # rubocop:disable Metrics/ClassLength
     class HashShape
       ALLOWED_KEY_CLASSES = [Symbol, String].freeze
       EXTRA_KEY_POLICIES = %i[open closed].freeze
@@ -241,6 +240,5 @@ module Rigor
         Type::Combinator.union(*key_types)
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/rigor/type/integer_range.rb

@@ -78,13 +78,13 @@ module Rigor
         Float::INFINITY
       end
 
-      ALIAS_NAMES = {
-        [NEG_INFINITY, POS_INFINITY] => "int",
-        [1, POS_INFINITY] => "positive-int",
-        [0, POS_INFINITY] => "non-negative-int",
-        [NEG_INFINITY, -1] => "negative-int",
-        [NEG_INFINITY, 0] => "non-positive-int"
-      }.freeze
+      ALIAS_NAMES = Ractor.make_shareable({
+                                            [NEG_INFINITY, POS_INFINITY] => "int",
+                                            [1, POS_INFINITY] => "positive-int",
+                                            [0, POS_INFINITY] => "non-negative-int",
+                                            [NEG_INFINITY, -1] => "negative-int",
+                                            [NEG_INFINITY, 0] => "non-positive-int"
+                                          })
 
       def describe(_verbosity = :short)
         ALIAS_NAMES[[min, max]] || generic_description

data/lib/rigor/type/refined.rb

@@ -165,18 +165,24 @@ module Rigor
       # kebab-case canonical name. Registered shapes print
       # through `describe`; unregistered combinations fall back
       # to the operator form.
-      CANONICAL_NAMES = {
-        ["String", :lowercase] => "lowercase-string",
-        ["String", :not_lowercase] => "non-lowercase-string",
-        ["String", :uppercase] => "uppercase-string",
-        ["String", :not_uppercase] => "non-uppercase-string",
-        ["String", :numeric] => "numeric-string",
-        ["String", :not_numeric] => "non-numeric-string",
-        ["String", :decimal_int] => "decimal-int-string",
-        ["String", :octal_int] => "octal-int-string",
-        ["String", :hex_int] => "hex-int-string",
-        ["String", :literal_string] => "literal-string"
-      }.freeze
+      #
+      # 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",
+                                                ["String", :uppercase] => "uppercase-string",
+                                                ["String", :not_uppercase] => "non-uppercase-string",
+                                                ["String", :numeric] => "numeric-string",
+                                                ["String", :not_numeric] => "non-numeric-string",
+                                                ["String", :decimal_int] => "decimal-int-string",
+                                                ["String", :octal_int] => "octal-int-string",
+                                                ["String", :hex_int] => "hex-int-string",
+                                                ["String", :literal_string] => "literal-string"
+                                              })
       private_constant :CANONICAL_NAMES
 
       # Bidirectional `predicate_id ↔ complement_predicate_id`

data/lib/rigor/type/top.rb

@@ -7,10 +7,11 @@ module Rigor
     # The top of the value lattice: contains every value, including untyped
     # boundaries. See docs/type-specification/special-types.md.
     class Top
+      # ADR-15 Phase 4b.x — eager singleton (see Bot.rb).
+      @instance = new.freeze
+
       class << self
-        def instance
-          @instance ||= new.freeze
-        end
+        attr_reader :instance
 
         private :new
       end

data/lib/rigor/type/union.rb

@@ -28,8 +28,27 @@ module Rigor
         members.map { |m| m.describe(verbosity) }.join(" | ")
       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
+      # 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.
       def erase_to_rbs
-        members.map(&:erase_to_rbs).join(" | ")
+        erased = members.map(&:erase_to_rbs)
+        return "untyped" if erased.include?("untyped")
+
+        erased.uniq.join(" | ")
       end
 
       def top

data/lib/rigor/type.rb

@@ -23,5 +23,6 @@ require_relative "type/union"
 require_relative "type/difference"
 require_relative "type/refined"
 require_relative "type/intersection"
+require_relative "type/bound_method"
 require_relative "type/accepts_result"
 require_relative "type/combinator"

data/lib/rigor/type_node/generic.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeNode
+    # A parameterised named-type reference (`Pick<T, K>`,
+    # `non-empty-array[Integer]`, `pick_of[T, "name" | "email"]`,
+    # …) in an RBS::Extended payload. The `head` is the parser-
+    # observed name (no bracket type); `args` is the ordered
+    # 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.
+    #
+    # 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?
+          raise ArgumentError,
+                "TypeNode::Generic head must be a non-empty String, " \
+                "got #{head.inspect}"
+        end
+
+        unless args.is_a?(Array) && args.all? { |a| valid_arg?(a) }
+          raise ArgumentError,
+                "TypeNode::Generic args must be an Array of " \
+                "TypeNode::Identifier / TypeNode::Generic / " \
+                "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.
+        frozen_head = head.frozen? ? head : head.dup.freeze
+        frozen_args = args.frozen? ? args : args.dup.freeze
+        super(head: frozen_head, args: frozen_args)
+      end
+
+      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.
+      def valid_arg?(arg)
+        arg.is_a?(Identifier) || arg.is_a?(Generic) || arg.is_a?(IntegerLiteral) ||
+          arg.is_a?(SymbolLiteral) || arg.is_a?(StringLiteral) ||
+          arg.is_a?(IndexedAccess) || arg.is_a?(Union)
+      end
+    end
+  end
+end

data/lib/rigor/type_node/identifier.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeNode
+    # A bare named-type reference in an RBS::Extended payload. The
+    # `name` is the head as the parser saw it — kebab-case for
+    # built-in refinement names (`"non-empty-string"`),
+    # PascalCase for class-like names (`"String"`, `"Pick"`),
+    # `lower_snake` for type-function-shaped names without
+    # arguments (rare).
+    #
+    # The resolver dispatch path treats an `Identifier` as the
+    # no-arg form: if a plugin recognises `Pick` as a TS-utility
+    # name, it MAY still return `Dynamic[top]` for the bare
+    # `Identifier("Pick")` since TypeScript's `Pick` is only
+    # meaningful with two type arguments. The `Generic` carrier
+    # is what plugin resolvers normally key on.
+    class Identifier < Data.define(:name)
+      def initialize(name:)
+        unless name.is_a?(String) && !name.empty?
+          raise ArgumentError,
+                "TypeNode::Identifier name must be a non-empty String, " \
+                "got #{name.inspect}"
+        end
+
+        # Freeze the String field so the resulting Data object
+        # is `Ractor.shareable?` regardless of whether the
+        # caller passed a `# frozen_string_literal: true`
+        # constant or a dynamically built String. The same
+        # discipline applies to every other TypeNode value
+        # object — they live in the parser's hot path and are
+        # the natural carriers to flow through future Ractor
+        # boundaries (see CURRENT_WORK Open Items #8).
+        super(name: name.frozen? ? name : name.dup.freeze)
+      end
+    end
+  end
+end

data/lib/rigor/type_node/indexed_access.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeNode
+    # AST wrapper for the trailing `T[K]` indexed-access projection
+    # chain. The parser emits a left-associative chain by wrapping
+    # the receiver AST in successive `IndexedAccess` nodes
+    # (`Tuple[A, B][1][0]` parses to
+    # `IndexedAccess(IndexedAccess(Generic(Tuple, [A, B]), 1), 0)`).
+    #
+    # `receiver` and `key` are themselves any AST node — the
+    # indexed-access chain is applied at resolution time, after the
+    # receiver has been resolved to a {Rigor::Type} carrier and the
+    # key has been resolved (typically to a `Constant<Integer>` or
+    # a constant String/Symbol singleton).
+    class IndexedAccess < Data.define(:receiver, :key)
+      def initialize(receiver:, key:)
+        unless valid_node?(receiver)
+          raise ArgumentError,
+                "TypeNode::IndexedAccess receiver must be a TypeNode " \
+                "node, got #{receiver.inspect}"
+        end
+
+        unless valid_node?(key)
+          raise ArgumentError,
+                "TypeNode::IndexedAccess key must be a TypeNode " \
+                "node, got #{key.inspect}"
+        end
+
+        super
+      end
+
+      private
+
+      def valid_node?(node)
+        node.is_a?(Identifier) || node.is_a?(Generic) ||
+          node.is_a?(IntegerLiteral) || node.is_a?(IndexedAccess)
+      end
+    end
+  end
+end

data/lib/rigor/type_node/integer_literal.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeNode
+    # Integer-literal AST node. Used as a {Generic#args} entry for
+    # parametric forms whose arguments are bare integers — namely
+    # `int<5, 10>` (angle-bracketed integer bounds for
+    # {Type::IntegerRange}) and `int_mask[1, 2, 4]` (square-
+    # bracketed bitflag union for {Type::Combinator.int_mask}).
+    #
+    # ADR-13 slice 3 introduces this node so the parser can emit a
+    # uniform AST regardless of bracket flavour: the resolver pass
+    # then dispatches to the appropriate built-in builder by head
+    # name. Plugin resolvers receive the same shape and MAY treat
+    # integer literals as input to custom carriers (e.g. an
+    # opinionated `port_number<8000>` plugin).
+    class IntegerLiteral < Data.define(:value)
+      def initialize(value:)
+        unless value.is_a?(Integer)
+          raise ArgumentError,
+                "TypeNode::IntegerLiteral value must be an Integer, " \
+                "got #{value.inspect}"
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/rigor/type_node/name_scope.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeNode
+    # Companion context handed to every {Rigor::Plugin::TypeNodeResolver}
+    # invocation. ADR-13 § "`Plugin::TypeNodeResolver` shape".
+    #
+    # Three slots:
+    #
+    # - `resolver`: re-entry point so a plugin can recursively
+    #   resolve its own arguments. Any object responding to
+    #   `#resolve(node, scope)`. Slice 3 uses {ResolverChain} as
+    #   the concrete implementation; tests may pass a stub that
+    #   answers `resolve` directly.
+    # - `class_context`: the surrounding class / module name, if
+    #   any (`String` or `nil`). Plugins use this to resolve
+    #   `self`-relative type references or to scope nominal-name
+    #   lookups.
+    # - `type_alias_table`: a frozen read-only view of the
+    #   project's RBS type aliases for forward references. Slice
+    #   3 lands the slot with a default empty Hash; the
+    #   populated table is wired from {Rigor::Environment} in a
+    #   later slice once plugin authors ask for it.
+    class NameScope < Data.define(:resolver, :class_context, :type_alias_table)
+      def initialize(resolver:, class_context: nil, type_alias_table: {})
+        unless resolver.respond_to?(:resolve)
+          raise ArgumentError,
+                "TypeNode::NameScope resolver must respond to #resolve(node, scope), " \
+                "got #{resolver.inspect}"
+        end
+
+        unless class_context.nil? || class_context.is_a?(String)
+          raise ArgumentError,
+                "TypeNode::NameScope class_context must be nil or a String, " \
+                "got #{class_context.inspect}"
+        end
+
+        unless type_alias_table.is_a?(Hash)
+          raise ArgumentError,
+                "TypeNode::NameScope type_alias_table must be a Hash, " \
+                "got #{type_alias_table.inspect}"
+        end
+
+        super(
+          resolver: resolver,
+          class_context: class_context.nil? ? nil : class_context.dup.freeze,
+          type_alias_table: type_alias_table.dup.freeze
+        )
+      end
+    end
+  end
+end