rigortype 0.4.7 → 0.4.8

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet.rb

@@ -344,19 +344,96 @@ module Rigor
         when Rigor::Type::Singleton
           chain_lookup(self_type.class_name, method_name, anchor_kind: :singleton, mixin_kind: :extend)
         when Rigor::Type::Nominal
-          chain_lookup(self_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include)
+          chain_lookup(self_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include) ||
+            struct_prop_lookup(self_type.class_name, method_name, scope)
         end
       rescue StandardError
         nil
       end
 
+      # Issue #2541 — after the sig catalog (the class and its mixins) declines an instance-side call, a
+      # `prop` / `const` accessor the class or a superclass declares under a `T::Struct`-family root.
+      # The accessor's type is translated here rather than at harvest: a relative constant in it resolves the
+      # way Ruby's lexical lookup would from the declaring class body — under each enclosing namespace,
+      # innermost first, then at the top level — against the classes the walk declared and the RBS
+      # environment. A constant that resolves nowhere reads `Dynamic[top]`, never a guessed class.
+      def struct_prop_lookup(class_name, method_name, scope)
+        signature = @catalog.lookup_struct_prop(class_name: class_name, method_name: method_name)
+        return signature if signature.nil?
+
+        source, nesting = @catalog.struct_prop_type(signature)
+        return signature if source.nil?
+
+        signature.with(return_type: struct_prop_type(source, nesting, signature.class_name, scope))
+      end
+
+      def struct_prop_type(source, nesting, class_name, scope)
+        @struct_prop_types ||= {}
+        @struct_prop_types[[source, nesting, class_name, scope.nil?]] ||= begin
+          node = Prism.parse(source).value.statements&.body&.first
+          resolve = ->(name) { resolve_struct_constant(name, nesting, class_name, scope) }
+          TypeTranslator.translate(node, resolve)
+        end
+      end
+
+      # Ruby's lookup for a relative constant in the class body: the lexical nesting, innermost first; then
+      # the class's ancestors; then the top level. The nesting step answers a class it finds, and declines
+      # (nil, so the constant reads `Dynamic[top]`) when it meets a constant that is not a declared class.
+      # Ancestry is not modelled precisely: a class or constant of that name under any ancestor declines.
+      # The top level answers only when the struct's ancestry is closed — no class on its walked superclass
+      # chain `include`s or `prepend`s anything, whose constants could shadow it — and no other walked
+      # `*::<name>` exists.
+      def resolve_struct_constant(name, nesting, class_name, scope)
+        environment = scope&.environment
+        return name.delete_prefix("::") if name.start_with?("::")
+
+        nesting.size.downto(1) do |depth|
+          candidate = "#{nesting.first(depth).join('::')}::#{name}"
+          return candidate if struct_constant_class?(candidate, environment)
+          return nil if struct_constant_bound?(candidate, scope)
+        end
+        @catalog.constant_ancestry(class_name).each do |ancestor|
+          candidate = "#{ancestor}::#{name}"
+          return nil if struct_constant_class?(candidate, environment) || struct_constant_bound?(candidate, scope)
+        end
+        return nil if struct_constant_elsewhere?(name)
+        return nil if @catalog.mixes_in_ancestry?(class_name)
+
+        struct_constant_class?(name, environment) ? name : nil
+      end
+
+      def struct_constant_class?(name, environment)
+        @catalog.namespace?(name) || !environment&.nominal_for_name(name).nil?
+      end
+
+      # A walked constant write, or any constant the engine types at the rooted path `::<name>` — an RBS
+      # constant declaration included. The probe goes through the plugin-facing `Scope#type_of` on a parsed
+      # constant-path node; a name nothing declares types as `Dynamic[top]` and is not bound.
+      def struct_constant_bound?(name, scope)
+        return true if @catalog.constant?(name)
+        return false if scope.nil?
+
+        node = Prism.parse("::#{name}").value.statements&.body&.first
+        type = scope.type_of(node)
+        !(type.nil? || type.is_a?(Rigor::Type::Dynamic))
+      rescue StandardError
+        true
+      end
+
+      def struct_constant_elsewhere?(name)
+        @struct_constant_names ||= @catalog.declared_constant_names
+        suffix = "::#{name}"
+        @struct_constant_names.any? { |declared| declared.end_with?(suffix) }
+      end
+
       def instance_chain_lookup(receiver_node, method_name, scope)
         return nil if scope.nil?
 
         receiver_type = scope.type_of(receiver_node)
         return nil unless receiver_type.is_a?(Rigor::Type::Nominal)
 
-        chain_lookup(receiver_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include)
+        chain_lookup(receiver_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include) ||
+          struct_prop_lookup(receiver_type.class_name, method_name, scope)
       rescue StandardError
         # `scope.type_of` can raise on unrecognised synthetic nodes; degrade to "no contribution" rather
         # than bubbling the failure into the dispatcher.
@@ -548,7 +625,7 @@ module Rigor
                         catalog
                       end
 
-        errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path)
+        errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path, struct_catalog: catalog)
         # ADR-88 WD2 — store Marshal-clean `{kind:, line:, column:}` tuples, not the `ParseError` (it holds a
         # live Prism node the producer bundle could not serialise). `diagnostics_for_file` rebuilds the
         # diagnostic from the tuple, at the same 1-based line / `start_column + 1` position `from_node` gave.

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_collector.rb

@@ -2,15 +2,15 @@
 
 require "prism"
 
-require "rigor/inference/declaration_walk"
+require "rigor/reflection"
 
 require_relative "serializer_index"
 
 module Rigor
   module Plugin
     class Typelizer < Rigor::Plugin::Base
-      # A {Rigor::Inference::DeclarationWalk} collector over one file: the classes it declares, and whether each
-      # one's own body says `include Typelizer::DSL` / `extend Typelizer::DSL`.
+      # A collector over one file, built on {Rigor::Reflection.class_declarations_in}: the classes it declares, and
+      # whether each one's own body says `include Typelizer::DSL` / `extend Typelizer::DSL`.
       #
       # A `module` that includes the DSL is deliberately not recorded: typelizer registers the module's own
       # name and `target_serializers` then calls `.descendants` on it, which a plain Module lacks. A class that
@@ -22,8 +22,6 @@ module Rigor
       # `included do include Typelizer::DSL end` and a `def` that includes it credit nothing to the lexical
       # class. A `class << self` body is a different node and is not entered either.
       class SerializerCollector
-        include Rigor::Inference::DeclarationWalk::Collector
-
         DSL_MODULE = "Typelizer::DSL"
         DSL_CALLS = %i[include extend].freeze
 
@@ -33,17 +31,10 @@ module Rigor
           @dsl = {}
         end
 
-        def on_declaration(node, context, body_context)
-          return Rigor::Inference::DeclarationWalk::DESCEND unless node.is_a?(Prism::ClassNode)
-
-          name = body_context.prefix.join("::")
-          unless name.empty?
-            superclass = superclass_name(node.superclass)
-            @entries[name] = superclass if superclass || !@entries.key?(name)
-            @nestings[name] = context.nesting || []
-            @dsl[name] = true if dsl_in?(node.body) && !body_context.singleton_cref
-          end
-          Rigor::Inference::DeclarationWalk::DESCEND
+        # Walks `root` (a parsed file's `Prism::Node`) and records what it finds; answers the collector itself.
+        def collect(root)
+          Rigor::Reflection.class_declarations_in(root).each { |declaration| record(declaration) }
+          self
         end
 
         # The classes this file declares, as {SerializerIndex::ClassEntry} values.
@@ -58,6 +49,15 @@ module Rigor
 
         private
 
+        def record(declaration)
+          name = declaration.name
+          node = declaration.node
+          superclass = superclass_name(node.superclass)
+          @entries[name] = superclass if superclass || !@entries.key?(name)
+          @nestings[name] = declaration.nesting
+          @dsl[name] = true if dsl_in?(node.body)
+        end
+
         # Whether a statement reachable without entering a def, block, lambda or nested declaration is a
         # receiverless `include` / `extend` of the DSL module.
         def dsl_in?(node)

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_discoverer.rb

@@ -2,8 +2,6 @@
 
 require "prism"
 
-require "rigor/inference/declaration_walk"
-
 require_relative "serializer_collector"
 require_relative "serializer_index"
 
@@ -30,10 +28,7 @@ module Rigor
             parsed = Prism.parse(contents)
             next unless parsed.success?
 
-            collector = SerializerCollector.new
-            Rigor::Inference::DeclarationWalk.run(
-              parsed.value, [collector], Rigor::Inference::DeclarationWalk::Context.root(nesting: [])
-            )
+            collector = SerializerCollector.new.collect(parsed.value)
             in_dirs = dir_files.include?(path)
             entries.concat(collector.class_entries.map { |entry| entry.with(in_dirs: in_dirs) })
           end

data/sig/rigor/analysis/check_rules/rule_walk.rbs

@@ -0,0 +1,6 @@
+module Rigor::Analysis::CheckRules::RuleWalk
+end
+
+class Rigor::Analysis::CheckRules::RuleWalk::CollectorDriver
+  def initialize: (untyped) -> void
+end

data/sig/rigor/analysis/fact_store.rbs

@@ -2,9 +2,8 @@ module Rigor
   module Analysis
     module CheckRules
       def self?.diagnose: (path: String, root: untyped, scope_index: Hash[untyped, Scope]) -> Array[Diagnostic]
-      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root) -> Hash[Symbol, untyped]
-      # authored: returns Rigor::Analysis::CheckRules::RuleWalk::CollectorDriver, which has no RBS declaration yet (#2404); stays `untyped` until it is declared
-      def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> untyped
+      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root, ?plugin_api_surface: bool) -> Hash[Symbol, untyped]
+      def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> Rigor::Analysis::CheckRules::RuleWalk::CollectorDriver
       def self?.shadow_verify_converged_collectors: (String path, untyped root, untyped scope_index, Hash[Symbol, untyped]? collectors) -> void
       def self?.filter_suppressed: (Array[Diagnostic] diagnostics, comments: untyped, disabled_rules: Array[String]) -> Array[Diagnostic]
     end

data/sig/rigor/cache/descriptor.rbs

@@ -0,0 +1,14 @@
+class Rigor::Cache::Descriptor::PluginEntry
+  def initialize: (id: untyped, version: untyped, ?config_hash: untyped) -> void
+  def to_h: () -> Hash[String, untyped]
+end
+
+class Rigor::Cache::Descriptor
+  def initialize: (?files: untyped, ?gems: untyped, ?plugins: untyped, ?configs: untyped, ?dependencies: untyped, ?globs: untyped) -> void
+  def self.compose: (*untyped) -> Rigor::Cache::Descriptor
+  def cache_key_for: (producer_id: untyped, ?params: untyped) -> String
+  def to_canonical_bytes: () -> String
+  def to_canonical_hash: () -> Hash[String, untyped]
+  def ==: (untyped) -> (false | true)
+  def hash: () -> Integer
+end

data/sig/rigor/environment.rbs

@@ -19,7 +19,9 @@ module Rigor
     def hkt_scan_failure: () -> [String, String, String?, Symbol]?
 
     def self.default: () -> Environment
-    def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?) -> Environment
+    def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?, ?eager: bool) -> Environment
+    # authored: the return is the `signature_paths:` argument's type (authored intent) or the default ["sig"]; sig-gen types the `||` fallback untyped.
+    def self.project_signature_root_candidates: (Array[String | _ToPath]? signature_paths) -> Array[String | _ToPath]
     # authored: the return is the `signature_paths:` argument's type (authored intent) or the default [Pathname]; sig-gen types the `||` fallback untyped.
     def self.project_signature_roots: (Array[String | _ToPath]? signature_paths, ?root: String) -> Array[String | _ToPath]
 
@@ -36,6 +38,7 @@ module Rigor
     def rbs_module?: (String | Symbol name) -> bool
     def singleton_extended_modules: (String | Symbol name) -> Array[String]
     def class_ordering: (String | Symbol lhs, String | Symbol rhs) -> ordering
+    def prepare_for_typing!: () -> Environment
     def reflection: () -> untyped?
     def missing_rbs_gem_owner: (String | Symbol root_constant_name) -> String?
 

data/sig/rigor/plugin/base.rbs

@@ -4,9 +4,20 @@
 # declared surface and give plugin subclasses (once they enter a check
 # target) method resolution for the DSL + hook surface.
 #
-# Collaborators that have no RBS yet (Diagnostic, Cache::Descriptor,
-# FlowContribution, NodeContext, Prism nodes) are typed `untyped`; the
-# precision ceiling is the sparse `sig/` tree, not this file.
+# ADR-128 WD2 — every hook position takes a plugin-facing interface
+# (`sig/rigor/plugin/interfaces.rbs`), a concrete Prism node class, a
+# `Rigor::Type::t` or a core type, instead of `untyped`. A hook's `scope`
+# is non-nil where every engine call site passes one: the per-file hooks
+# receive the seeded `Scope.empty(...)`, `MethodDispatcher#try_plugin_contribution`
+# returns before consulting a plugin when its scope is nil, and
+# `StatementEvaluator#apply_plugin_assertions` has already read its own. The
+# existing `scope.nil?` guards in plugin source stay valid either way.
+#
+# Collaborators that have no RBS yet (FlowContribution) stay `untyped`;
+# the precision ceiling is the sparse `sig/` tree. A parameter row stays
+# lenient even where its type IS declared — `cache_for`'s `?descriptor:` and
+# `IoBoundary#replay` both take a `Cache::Descriptor` and both read `untyped`
+# — by ADR-107 clause 2, not for want of a declaration.
 class Rigor::Plugin::Base
   # --- class-level declaration DSLs ---------------------------------
 
@@ -17,16 +28,32 @@ class Rigor::Plugin::Base
   def self.producer: (untyped id, ?watch: untyped, ?serialize: untyped, ?deserialize: untyped, ?generation_cap: untyped) { (untyped params) -> untyped } -> Symbol
   def self.producers: () -> Hash[Symbol, untyped]
 
-  def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> Class
+  # One overload per node class the bundled plugins name, so the block's `node` is that class; `Prism::Node` is the
+  # fallback for any other (RBS cannot write `singleton(N)` over a type variable). The block runs `instance_exec`'d
+  # on the plugin: `file_context` is whatever the `node_file_context` block returned (plugin-defined), and a rule
+  # may answer one diagnostic, an array of them, or nil.
+  def self.node_rule: (singleton(::Prism::CallNode) node_type) { (::Prism::CallNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::CallNode)
+                    | (singleton(::Prism::ClassNode) node_type) { (::Prism::ClassNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::ClassNode)
+                    | (singleton(::Prism::ProgramNode) node_type) { (::Prism::ProgramNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::ProgramNode)
+                    | (singleton(::Prism::Node) node_type) { (::Prism::Node node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::Node)
   def self.node_rules: () -> Array[untyped]
 
-  def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> void
-  def self.node_file_context_block: () -> (^(untyped root, untyped scope) -> untyped)?
+  def self.node_file_context: () { (::Prism::ProgramNode root, Rigor::Plugin::_Scope scope) -> untyped } -> void
+  def self.node_file_context_block: () -> (^(::Prism::ProgramNode root, Rigor::Plugin::_Scope scope) -> untyped)?
 
-  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(untyped path) -> Array[untyped])?) { (untyped call_node, untyped scope) -> untyped } -> nil
+  # A rule with a static `methods:` Array only ever runs its block on a `CallNode`: the name gate
+  # (`Registry#build_name_gates`, `Base#dynamic_return_rule_applies?`) matches on the call's name, which
+  # none of the other nodes in the union below has, so the gate declines them (#2681, #2764). Every other
+  # declaration shape is offered the whole union. A callable `methods:` also only ever sees a `CallNode`
+  # at runtime, since the same gate declines the nameless nodes, but RBS cannot tell a callable from an
+  # Array argument by overload alone, so it keeps the union, which is sound.
+  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, methods: Array[untyped], ?file_methods: (^(String path) -> Array[untyped])?) { (::Prism::CallNode call_node, Rigor::Plugin::_Scope scope) -> Rigor::Type::t? } -> nil
+                         | (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(String path) -> Array[untyped])?) { (::Prism::CallNode | ::Prism::CallOperatorWriteNode | ::Prism::CallOrWriteNode | ::Prism::CallAndWriteNode | ::Prism::IndexOperatorWriteNode | ::Prism::IndexOrWriteNode | ::Prism::IndexAndWriteNode | ::Prism::BlockArgumentNode call_node, Rigor::Plugin::_Scope scope) -> Rigor::Type::t? } -> nil
   def self.dynamic_returns: () -> Array[untyped]
 
-  def self.narrowing_facts: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
+  # The block answers the facts that hold after the call returns normally, or nil. The element is a
+  # `Rigor::FlowContribution::Fact`, which has no RBS declaration yet, so it stays `untyped`.
+  def self.narrowing_facts: (methods: Array[untyped]) { (::Prism::CallNode call_node, Rigor::Plugin::_Scope scope) -> Array[untyped]? } -> nil
   # The engine-facing reader for the declared `narrowing_facts` rules. Named
   # `type_specifiers` before ADR-80; that spelling was removed in 0.3.0.
   def self.narrowing_facts_rules: () -> Array[untyped]
@@ -35,15 +62,16 @@ class Rigor::Plugin::Base
 
   # --- instance surface --------------------------------------------
 
-  attr_reader services: untyped
-  attr_reader config: untyped
+  attr_reader services: Rigor::Plugin::_Services
+  # Schema-driven per plugin, so the values stay `untyped` (ADR-128 WD2).
+  attr_reader config: Hash[String, untyped]
 
-  def initialize: (services: untyped, ?config: untyped) -> void
+  def initialize: (services: Rigor::Plugin::_Services, ?config: Hash[String, untyped]) -> void
 
   # Overridable lifecycle / extension hooks (default no-ops).
-  def init: (untyped services) -> nil
-  def prepare: (untyped services) -> nil
-  def diagnostics_for_file: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  def init: (Rigor::Plugin::_Services services) -> nil
+  def prepare: (Rigor::Plugin::_Services services) -> nil
+  def diagnostics_for_file: (path: String, scope: Rigor::Plugin::_Scope, root: ::Prism::ProgramNode) -> Array[Rigor::Analysis::Diagnostic]
   # authored: hook-contract widening — the element type comes from a plugin gem sig-gen never
   # sees, so no engine work would let it answer; the declared `Array[Rigor::Plugin::TemplateUnit]`
   # over a bare-`[]` default body is the author's contract.
@@ -54,12 +82,19 @@ class Rigor::Plugin::Base
   def declared_members: (untyped class_name) -> Array[untyped]
 
   # Engine-executed dispatch over the declared DSLs.
-  def node_rule_diagnostics: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  def node_rule_diagnostics: (path: String, scope: Rigor::Plugin::_Scope, root: ::Prism::ProgramNode) -> Array[untyped]
   # sig-gen gap: #1007 — the true `return result if result` branch (base.rb:594) flows through an
   # `instance_exec`'d, plugin-supplied Proc that sig-gen's inference does not fold into the return
   # join, so it proposes the literal fallback `nil` instead of the honest contract.
-  def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> Rigor::Type::t?
-  def narrowing_facts_for: (call_node: untyped, scope: untyped) -> Array[untyped]
+  # `call_node` is a `CallNode` except where the engine dispatches a compound write or a block argument. The
+  # compound writes (`x.attr op= v`, `x.attr ||= v`, `x.attr &&= v`, and the `x[i]` forms) reach a rule through
+  # `ExpressionTyper#attribute_compound_read_type`, `#call_operator_write_type_for` and `#index_read_dispatch`;
+  # the `&:symbol` block arguments through `ExpressionTyper#symbol_block_return_type` and `#apply_hash_block`.
+  # A rule the name gate does not screen out (a `receivers:`-only rule, for one) is offered those nodes, so the
+  # `dynamic_return` block union above is the full set. A rule that reads a `CallNode`-only member (`receiver`,
+  # `name`, `arguments`) must guard with `call_node.is_a?(::Prism::CallNode)` first (#2717).
+  def dynamic_return_type: (call_node: ::Prism::CallNode | ::Prism::CallOperatorWriteNode | ::Prism::CallOrWriteNode | ::Prism::CallAndWriteNode | ::Prism::IndexOperatorWriteNode | ::Prism::IndexOrWriteNode | ::Prism::IndexAndWriteNode | ::Prism::BlockArgumentNode, scope: Rigor::Plugin::_Scope, receiver_type: Rigor::Type::t) -> Rigor::Type::t?
+  def narrowing_facts_for: (call_node: ::Prism::CallNode, scope: Rigor::Plugin::_Scope) -> Array[untyped]
 
   # Authoring helpers.
   def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> Rigor::Analysis::Diagnostic
@@ -84,6 +119,5 @@ class Rigor::Plugin::Base
   def effect_ancestry: () -> Array[Rigor::Plugin::EffectAncestry]
   def io_boundary: () -> Rigor::Plugin::IoBoundary
   def cache_for: (untyped producer_id, ?params: untyped, ?descriptor: untyped) -> Proc
-  # authored: returns Rigor::Cache::Descriptor::PluginEntry, which has no RBS declaration yet (#2404); stays `untyped` until it is declared
-  def plugin_entry: () -> untyped
+  def plugin_entry: () -> Rigor::Cache::Descriptor::PluginEntry
 end

data/sig/rigor/plugin/interfaces.rbs

@@ -0,0 +1,51 @@
+# ADR-128 — the plugin-facing structural interfaces: what a hook may call on the engine objects it receives.
+#
+# The criterion (ADR-128): a method is public plugin API only if it is declared on `Plugin::Base`, on one of the
+# interfaces below, or in a namespace `docs/internal-spec/public-api.md` lists as public. Being reachable at
+# runtime does not make a method public. `spec/rigor/plugin_boundary_spec.rb` gates the bundled plugins against
+# these member lists, so adding a member here is an API promise, and `public_api_drift_spec.rb` pins the sets.
+#
+# Each interface is backed by a concrete engine class (the `BACKING` table in `spec/support/plugin_boundary.rb`).
+# Engine signatures keep those concrete classes (ADR-128 WD5); an interface appears only at a plugin-facing
+# position, in `base.rbs`.
+module Rigor
+  module Plugin
+    # The scope a hook receives. Backed by `Rigor::Scope`, which has far more members (about 200); only these are
+    # promised. `environment` is non-nil, matching `Scope#environment`.
+    interface _Scope
+      def type_of: (::Prism::Node node) -> Rigor::Type::t
+      def self_type: () -> Rigor::Type::t?
+      def local: (String | Symbol name) -> Rigor::Type::t?
+      def source_path: () -> String?
+      def with_local: (String | Symbol name, Rigor::Type::t type) -> Rigor::Plugin::_Scope
+      def environment: () -> Rigor::Plugin::_Environment
+    end
+
+    # The project's RBS and class-registry handle, backed by `Rigor::Environment`.
+    interface _Environment
+      def nominal_for_name: (String | Symbol name) -> Rigor::Type::Nominal?
+      def rbs_module?: (String | Symbol name) -> bool
+    end
+
+    # The services container `Plugin::Base#init` / `#prepare` receive, backed by `Rigor::Plugin::Services`.
+    # `reflection` and `type` are public namespaces (`Rigor::Reflection`, `Rigor::Type::Combinator`) that a plugin
+    # also reaches by constant, so they are typed as those modules rather than narrowed to an interface.
+    interface _Services
+      def fact_store: () -> Rigor::Plugin::_FactStore
+      def configuration: () -> Rigor::Plugin::_Configuration
+      def reflection: () -> singleton(Rigor::Reflection)
+      def type: () -> singleton(Rigor::Type::Combinator)
+    end
+
+    # The per-run cross-plugin fact store, backed by `Rigor::Plugin::FactStore`.
+    interface _FactStore
+      def publish: (plugin_id: String | Symbol, name: Symbol, value: untyped) -> nil
+      def read: (plugin_id: String | Symbol, name: Symbol) -> untyped
+    end
+
+    # The project configuration, backed by `Rigor::Configuration`.
+    interface _Configuration
+      def paths: () -> Array[String]
+    end
+  end
+end

data/sig/rigor/plugin/io_boundary.rbs

@@ -14,8 +14,7 @@ class Rigor::Plugin::IoBoundary
   # whose parameter is undeclared.
   def refusal_summary: () -> { count: Integer, first_path: String?, nearest_root: String? }?
   def open_url: (untyped url) -> String
-  # Returns a frozen `Rigor::Cache::Descriptor` (no RBS yet -> untyped).
-  # authored: returns Rigor::Cache::Descriptor, which has no RBS declaration yet (#2404); stays `untyped` until it is declared
-  def cache_descriptor: () -> untyped
+  # The returned descriptor is frozen.
+  def cache_descriptor: () -> Rigor::Cache::Descriptor
   def replay: (untyped descriptor) -> nil
 end

data/sig/rigor/plugin/node_context.rbs

@@ -0,0 +1,21 @@
+module Rigor
+  module Plugin
+    # ADR-37 slice 1d — the lexical context of a node, the fifth argument of a `node_rule` block.
+    class NodeContext
+      EMPTY: nil
+
+      attr_reader ancestors: Array[::Prism::Node]
+
+      def initialize: (Array[::Prism::Node] ancestors) -> void
+      # The three finders return the innermost ancestor of a given kind: a `DefNode`, a `ClassNode` or
+      # `ModuleNode`, and a `CallNode` respectively. `enclosing_def` is sig-gen's proposal (#2719, #2914); the other
+      # two blocks (`||`, `&&`) are not a single class test, so their bodies still infer `Prism::Node?`. A narrower
+      # declaration would be an unmarked sig-gen divergence (ADR-107).
+      # Known Steep 2.0.0 limitation (surfaced by `library "prism"`, #2718): it does not narrow `rfind` through an
+      # `is_a?` block, so it warns that the body is `Prism::Node?`; the declaration keeps the precise shape.
+      def enclosing_def: () -> (Prism::DefNode | nil)
+      def enclosing_module: () -> ::Prism::Node?
+      def enclosing_block: (Symbol method_name) -> ::Prism::Node?
+    end
+  end
+end

data/sig/rigor/reflection.rbs

@@ -19,5 +19,42 @@ module Rigor
     def self?.class_type_param_names: (String | Symbol class_name, ?scope: Scope) -> Array[Symbol]
     def self?.discovered_class?: (String | Symbol class_name, ?scope: Scope) -> bool
     def self?.discovered_method?: (String | Symbol class_name, String | Symbol method_name, ?kind: Symbol, ?scope: Scope) -> bool
+    def self?.project_method_defined: (String | Symbol? class_name, String | Symbol method_name, kind: :instance | :singleton, source: :def | :discovered | :either, scope: Scope) -> Trinary
+    def self?.rbs_method_defined: (String | Symbol? class_name, String | Symbol method_name, kind: :instance | :singleton, scope: Scope) -> Trinary
+    def self?.ancestry_reaches: (String | Symbol? class_name, Array[String | Symbol] ancestor_names, kind: :instance | :singleton, scope: Scope) -> Trinary
+    # sig-gen gap: #2302 — the collector's `@classes = []` is grown by `<<`, so sig-gen reads the array as `Array[untyped]`.
+    def self?.class_declarations_in: (Prism::Node root) ?{ (DeclaredCall call) -> void } -> Array[ClassDeclaration]
+
+    # One `class` header of a parsed file, as `class_declarations_in` reports it.
+    class ClassDeclaration < Data
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so sig-gen proposes `untyped`; the shape is hand-written.
+      attr_reader name: String
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so sig-gen proposes `untyped`; the shape is hand-written.
+      attr_reader nesting: Array[String]
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so sig-gen proposes `untyped`; the shape is hand-written.
+      attr_reader node: Prism::ClassNode
+
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so the constructor's keywords are `untyped` in sig-gen.
+      def self.new: (name: String, nesting: Array[String], node: Prism::ClassNode) -> instance
+                  | (String name, Array[String] nesting, Prism::ClassNode node) -> instance
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so the constructor's keywords are `untyped` in sig-gen.
+      def self.[]: (name: String, nesting: Array[String], node: Prism::ClassNode) -> instance
+                 | (String name, Array[String] nesting, Prism::ClassNode node) -> instance
+    end
+
+    # One call `class_declarations_in` yields: the `Prism::CallNode` and the class or module it lexically sits in.
+    class DeclaredCall < Data
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so sig-gen proposes `untyped`; the shape is hand-written.
+      attr_reader node: Prism::CallNode
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so sig-gen proposes `untyped`; the shape is hand-written.
+      attr_reader owner: String?
+
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so the constructor's keywords are `untyped` in sig-gen.
+      def self.new: (node: Prism::CallNode, owner: String?) -> instance
+                  | (Prism::CallNode node, String? owner) -> instance
+      # sig-gen gap: #1150 — `Data.define` members carry no type, so the constructor's keywords are `untyped` in sig-gen.
+      def self.[]: (node: Prism::CallNode, owner: String?) -> instance
+                 | (Prism::CallNode node, String? owner) -> instance
+    end
   end
 end

data/sig/rigor/scope.rbs

@@ -30,7 +30,7 @@ module Rigor
     attr_reader struct_fold_safe_locals: Set[Symbol]
     attr_reader opaque_block_self: bool
     # Issue #1759 — `:refinement` (REFINEMENT_BLOCK_SELF) directly in a `refine X do … end` block body.
-    attr_reader block_self_unknown: bool | :refinement
+    attr_reader block_self_unknown: bool | :refinement | :preserved
     attr_reader singleton_class_body: bool
     attr_reader lexical_nesting: Array[String]?
     # Issue #1429 — a guard's narrowing of a constant reference, keyed by its spelling.
@@ -100,6 +100,12 @@ module Rigor
     def run_generation: () -> Object?
     def record_dynamic_origin: (untyped node, Symbol cause) -> Scope
     def record_optimistic_origin: (untyped node, Symbol cause) -> Scope
+    # sig-gen gap: #2840 — the reader returns through a sentinel `equal?` guard over `Hash#fetch`; sig-gen emits nothing.
+    def dynamic_origin: (untyped node) -> Symbol?
+    # sig-gen gap: #2840 — the reader returns through a sentinel `equal?` guard over `Hash#fetch`; sig-gen emits nothing.
+    def optimistic_origin: (untyped node) -> Symbol?
+    # sig-gen gap: #2840 — the reader returns through a sentinel `equal?` guard over `Hash#fetch`; sig-gen emits nothing.
+    def void_origin: (untyped node) -> Inference::VoidOrigin?
 
     def record_void_origin: (untyped node, Inference::VoidOrigin origin) -> Scope
 
@@ -219,12 +225,16 @@ module Rigor
 
     def self.empty: (?environment: Environment, ?source_path: String?) -> Scope
 
-    def initialize: (environment: Environment, locals: Hash[Symbol, Type::t], ?fact_store: Analysis::FactStore, ?self_type: Type::t?, ?ivars: Hash[Symbol, Type::t], ?cvars: Hash[Symbol, Type::t], ?globals: Hash[Symbol, Type::t], ?discovery: DiscoveryIndex, ?source_path: String?, ?opaque_block_self: bool, ?block_self_unknown: bool | :refinement, ?singleton_class_body: bool, ?dynamic_origins: Hash[untyped, Symbol], ?indexed_narrowings: Hash[IndexedKey, Type::t], ?method_chain_narrowings: Hash[ChainKey, Type::t], ?declaration_sourced: Set[[Symbol, Symbol] | [Symbol, Symbol, Symbol]], ?published_constant_sourced: Set[[Symbol, Symbol]], ?struct_fold_safe_locals: Set[Symbol], ?lexical_nesting: Array[String]?, ?local_origins: Hash[Symbol, Symbol], ?ivar_origins: Hash[Symbol, Symbol], ?void_origins: Hash[untyped, Inference::VoidOrigin], ?plugin_typed_calls: Hash[untyped, bool], ?optimistic_origins: Hash[untyped, Symbol], ?optimistic_locals: Hash[Symbol, Symbol | Inference::OptimisticOrigin::BoundMark], ?optimistic_ivars: Hash[Symbol, Symbol | Inference::OptimisticOrigin::BoundMark], ?construction_facts: Hash[Symbol, Set[Symbol]], ?repeated_or_writes: Hash[untyped, bool], ?match_frame: untyped, ?constant_narrowings: Hash[String, Type::t], ?guard_records: Hash[[Symbol, Symbol | String], Type::t], ?bot_guard_classes: Hash[[Symbol, Symbol | String], Array[String]], ?declared_refinements: Array[String | Symbol]) -> void
+    def initialize: (environment: Environment, locals: Hash[Symbol, Type::t], ?fact_store: Analysis::FactStore, ?self_type: Type::t?, ?ivars: Hash[Symbol, Type::t], ?cvars: Hash[Symbol, Type::t], ?globals: Hash[Symbol, Type::t], ?discovery: DiscoveryIndex, ?source_path: String?, ?opaque_block_self: bool, ?block_self_unknown: bool | :refinement | :preserved, ?singleton_class_body: bool, ?dynamic_origins: Hash[untyped, Symbol], ?indexed_narrowings: Hash[IndexedKey, Type::t], ?method_chain_narrowings: Hash[ChainKey, Type::t], ?declaration_sourced: Set[[Symbol, Symbol] | [Symbol, Symbol, Symbol]], ?published_constant_sourced: Set[[Symbol, Symbol]], ?struct_fold_safe_locals: Set[Symbol], ?lexical_nesting: Array[String]?, ?local_origins: Hash[Symbol, Symbol], ?ivar_origins: Hash[Symbol, Symbol], ?void_origins: Hash[untyped, Inference::VoidOrigin], ?plugin_typed_calls: Hash[untyped, bool], ?optimistic_origins: Hash[untyped, Symbol], ?optimistic_locals: Hash[Symbol, Symbol | Inference::OptimisticOrigin::BoundMark], ?optimistic_ivars: Hash[Symbol, Symbol | Inference::OptimisticOrigin::BoundMark], ?construction_facts: Hash[Symbol, Set[Symbol]], ?repeated_or_writes: Hash[untyped, bool], ?match_frame: untyped, ?constant_narrowings: Hash[String, Type::t], ?guard_records: Hash[[Symbol, Symbol | String], Type::t], ?bot_guard_classes: Hash[[Symbol, Symbol | String], Array[String]], ?declared_refinements: Array[String | Symbol]) -> void
     def with_source_path: (String? path) -> Scope
     def with_struct_fold_safe: (Set[Symbol] locals) -> Scope
     def with_lexical_nesting: (Array[String]? chain) -> Scope
     def struct_fold_safe?: (String | Symbol name) -> bool
+    def entering_block_without_gradual_marks: (Prism::Node block_node) -> Scope
     def entering_opaque_block: () -> Scope
+    PRESERVED_BLOCK_SELF: :preserved
+    def entering_self_preserving_block: () -> Scope
+    def walked_block_self_unknown?: () -> bool
     def block_self_unknown?: () -> bool
     REFINEMENT_BLOCK_SELF: :refinement
     def refinement_block_self?: () -> bool
@@ -297,6 +307,9 @@ module Rigor
     def with_inferred_param_mark: (String | Symbol name) -> Scope
     def without_inferred_param_mark: (String | Symbol name) -> Scope
     def inferred_param?: (String | Symbol name) -> bool
+    def with_gradual_narrowing_mark: (String | Symbol name) -> Scope
+    def gradual_narrowing?: (String | Symbol name) -> bool
+    def gradual_narrowing_names: () -> Array[Symbol]
     def forget_match_globals: () -> Scope
     def untyped_match_globals: () -> Scope
     def match_globals_bound?: () -> bool
@@ -321,8 +334,13 @@ module Rigor
     def def_node_slot: (untyped class_name, untyped method_name, ?Symbol kind) -> untyped
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> ::Prism::DefNode?
     def user_def_through_ancestors: (String | Symbol class_name, String | Symbol method_name, ?name_memo: Hash[untyped, untyped]) -> ([::Prism::DefNode, String] | [nil, nil])
+    # Returns `[opaque_flag, recorder_keys]`. Steep 2.0.0 cannot verify a tuple through the
+    # `Array#freeze` on the returned literal and reports a MethodBodyTypeMismatch warning; the
+    # declaration keeps the precise shape because `rigor sig-gen` proves it.
     def subclassing_opacity: () -> [false | true, Array[untyped]]
-    def user_instance_def_owners: (untyped) -> Array[untyped]
+    # authored: each owner is a frozen `[class_name, open_to_override]` pair. sig-gen types the lazily built
+    # `(owners ||= []) <<` array as `Array[untyped]`; the body keeps it to avoid `Hash#filter_map`'s per-entry pair.
+    def user_instance_def_owners: (untyped) -> Array[Array[untyped]]
     def discovered_method_through_ancestors?: (String | Symbol? class_name, String | Symbol method_name, Symbol kind, ?name_memo: Hash[untyped, untyped]) -> bool
     def external_ancestor_name_candidates: (String | Symbol class_name, ?name_memo: Hash[untyped, untyped]) -> Array[Array[String]]
     def enqueue_ancestors: (String current, Array[String] queue, Hash[untyped, untyped] name_memo, ?mixins: bool) -> void
@@ -357,6 +375,7 @@ module Rigor
     def data_member_layout: (String | Symbol class_name) -> Array[Symbol]?
     def struct_member_layout: (String | Symbol class_name) -> { members: Array[Symbol], keyword_init: bool }?
     def includes_of: (String | Symbol class_name) -> Array[String]
+    def prepends_of: (String | Symbol class_name) -> Array[String]
     # sig-gen gap: #2302 — `names = []` grown by `concat` reads `Array[untyped]`, so the element type is
     # hand-written, matching {#includes_of}.
     def singleton_extends_of: (String | Symbol class_name) -> Array[String]

data/sig/rigor/trinary.rbs

@@ -22,6 +22,7 @@ module Rigor
     def and: (Trinary other) -> Trinary
     def or: (Trinary other) -> Trinary
     def ==: (untyped other) -> bool
+    alias eql? ==
     def hash: () -> Integer
     def to_s: () -> String
     def inspect: () -> String

data/sig/rigor/type.rbs

@@ -56,8 +56,8 @@ module Rigor
     end
 
     class Dynamic
-      attr_reader static_facet: Type::t
-      def initialize: (Type::t static_facet) -> void
+      attr_reader static_facet: Type::t | Interface
+      def initialize: (Type::t | Interface static_facet) -> void
       def describe: (?Symbol verbosity) -> String
       def erase_to_rbs: () -> "untyped"
       def top: () -> Trinary
@@ -169,6 +169,11 @@ module Rigor
       def inspect: () -> String
     end
 
+    # ADR-130 — a `Rigor::Plugin` interface, carried only as a `Dynamic`'s facet (`Dynamic[Rigor::Plugin::_Scope]`), so
+    # it is not a member of `Type::t`. Declared for that name only; its members are read from the source.
+    class Interface
+    end
+
     class Union
       attr_reader members: Array[Type::t]
       def initialize: (Array[Type::t] members) -> void
@@ -446,7 +451,8 @@ module Rigor
       def self?.top: () -> Top
       def self?.bot: () -> Bot
       def self?.untyped: () -> Dynamic
-      def self?.dynamic: (Type::t static_facet) -> Dynamic
+      def self?.untyped?: (Type::t? type) -> bool
+      def self?.dynamic: (Type::t | Interface static_facet) -> Dynamic
       def self?.nominal_of: (Module | String class_name_or_object, ?type_args: Array[Type::t]) -> Nominal
       def self?.singleton_of: (Module | String class_name_or_object) -> Singleton
       def self?.constant_of: (untyped value) -> Constant

data/sig/rigor.rbs

@@ -165,8 +165,9 @@ module Rigor
       # sig-gen gap: #1008 — `result` is populated by `collect_return_summaries` mutating it by
       # reference from a sibling method; sig-gen folds only the `{}` seed and the empty-memo early
       # return, so it proposes the seed shape instead of the honest, usually-non-empty contract.
-      # Keys are `[path, "Class#method"]` pairs; values are `{ keys:, returns:, effects: }` bundles.
-      def return_summaries: () -> Hash[[String, String], Hash[Symbol, untyped]]
+      # Keys are `[path, "Class#method"]` pairs; values are `{ keys:, returns:, effects: }` bundles, or
+      # nil for a def whose keys the run cannot list. nil for a pool run, which harvests none (#3160).
+      def return_summaries: () -> Hash[[String, String], Hash[Symbol, untyped]?]?
       # ADR-67 — `[class_name, method_name, kind] => { param_name => Type }`.
       def param_inferred_types: () -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
       def collect_param_inference_table: (untyped files) -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]