rigortype 0.4.7 → 0.4.8

data/lib/rigor/analysis/check_rules.rb

@@ -12,11 +12,13 @@ require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
 require_relative "check_rules/rule_ids"
+require_relative "check_rules/call_facts"
 require_relative "check_rules/inferred_param_guard"
 require_relative "check_rules/declaration_sourced_guard"
 require_relative "check_rules/published_constant_guard"
 require_relative "check_rules/dead_version_guard_arms"
 require_relative "check_rules/rule_walk"
+require_relative "check_rules/always_raises_shield"
 require_relative "check_rules/always_truthy_condition_collector"
 require_relative "check_rules/unreachable_clause_collector"
 require_relative "check_rules/shadowed_rescue_collector"
@@ -33,7 +35,8 @@ require_relative "check_rules/rebinding_block_callees"
 require_relative "check_rules/rbs_receiver_surface"
 require_relative "check_rules/special_global_setters"
 require_relative "check_rules/ruby_deprecations"
-require_relative "../run_scoped_slots"
+require_relative "check_rules/plugin_api_surface"
+require_relative "../typing_state"
 
 module Rigor
   module Analysis
@@ -110,7 +113,8 @@ module Rigor
         diagnostics = collectors[:main_pass].results.dup
         diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
         COLLECTOR_DIAGNOSTIC_BUILDERS.each do |role, builder|
-          diagnostics.concat(send(builder, path, collectors[role].results))
+          collector = OPTIONAL_COLLECTOR_ROLES.include?(role) ? collectors[role] : collectors.fetch(role)
+          diagnostics.concat(send(builder, path, collector.results)) if collector
         end
         # ADR-47 WD5 — the dead arm of a decidable version guard (#627) reports nothing: it cannot run on
         # the Ruby being checked with, so a diagnostic there is a false positive. Applied before
@@ -141,18 +145,25 @@ module Rigor
         ivar_writes: :ivar_write_mismatch_diagnostics,
         dead_assignments: :dead_assignment_diagnostics,
         duplicate_hash_keys: :duplicate_hash_key_diagnostics,
-        return_in_ensure: :return_in_ensure_diagnostics
+        return_in_ensure: :return_in_ensure_diagnostics,
+        plugin_api_surface: :plugin_api_surface_diagnostics
       }.freeze
       private_constant :COLLECTOR_DIAGNOSTIC_BUILDERS
 
+      # The roles {.build_node_collectors} builds only on request: `plugin_api_surface`, when the rule is active
+      # ({PluginApiSurface.active?}). {.diagnose} skips an absent optional role; every other role is required, and a
+      # missing one raises.
+      OPTIONAL_COLLECTOR_ROLES = %i[plugin_api_surface].freeze
+
       # The verbatim per-node dispatch of the former inline main pass
       # (`diagnose`'s `Source::NodeWalker.each` `case`), now invoked by
       # {MainPassCollector} on the shared {RuleWalk}. Returns the
       # diagnostics for one node, in the same emission order as before.
-      def main_pass_node_diagnostics(path, node, scope_index, eval_ranges = nil, lexical_sites = nil)
+      def main_pass_node_diagnostics(path, node, scope_index, eval_ranges = nil, lexical_sites = nil,
+                                     raise_shield = nil)
         case node
         when Prism::CallNode
-          call_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites)
+          call_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites, raise_shield)
         when Prism::DefNode
           [
             refinement_aware_return_type_mismatch(path, node, scope_index, lexical_sites),
@@ -174,7 +185,8 @@ module Rigor
       # check in the body stands. The refine-body test runs only once a mismatch would report, so a file pays the
       # {LexicalMethodSites} walk only then.
       def refinement_aware_return_type_mismatch(path, node, scope_index, lexical_sites)
-        diagnostic = return_type_mismatch_diagnostic(path, node, scope_index)
+        replaced = lexical_sites&.replaced_singleton_defs(scope_index)
+        diagnostic = return_type_mismatch_diagnostic(path, node, scope_index, replaced)
         return diagnostic if diagnostic.nil? || lexical_sites.nil?
 
         lexical_sites.refinements.refinement_def?(node) ? nil : diagnostic
@@ -187,11 +199,17 @@ module Rigor
       # traversal, and hand the populated set back to {.diagnose} as
       # `node_collectors:`. The main pass needs `path` because its per-node
       # diagnostics carry it (ADR-53 B3c hosts it on the same walk).
-      def build_node_collectors(path, scope_index, root = nil)
+      #
+      # `plugin_api_surface:` adds the `plugin.api-surface` collector, which the runner asks for only when the rule
+      # resolves to a reporting severity ({PluginApiSurface.active?}).
+      def build_node_collectors(path, scope_index, root = nil, plugin_api_surface: false)
         eval_ranges = receiver_eval_block_ranges(root)
         lexical_sites = LexicalMethodSites.new(root, stamped_refinements(scope_index, root))
-        main_pass = ->(node) { main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites) }
-        {
+        raise_shield = root && AlwaysRaisesShield.new(root)
+        main_pass = lambda do |node|
+          main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites, raise_shield)
+        end
+        collectors = {
           main_pass: MainPassCollector.new(main_pass),
           void_value_use: VoidValueUseCollector.new(scope_index),
           always_truthy: AlwaysTruthyConditionCollector.new(scope_index),
@@ -202,6 +220,8 @@ module Rigor
           duplicate_hash_keys: DuplicateHashKeyCollector.new(scope_index),
           return_in_ensure: ReturnInEnsureCollector.new(scope_index)
         }
+        collectors[:plugin_api_surface] = PluginApiSurface::Collector.new(scope_index) if plugin_api_surface
+        collectors
       end
 
       # A {RuleWalk::CollectorDriver} over a built-in collector set, for a
@@ -279,8 +299,11 @@ module Rigor
         diagnostics = []
         eval_ranges = receiver_eval_block_ranges(root)
         lexical_sites = LexicalMethodSites.new(root, stamped_refinements(scope_index, root))
+        raise_shield = AlwaysRaisesShield.new(root)
         Source::NodeWalker.each(root) do |node|
-          diagnostics.concat(main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites))
+          diagnostics.concat(
+            main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites, raise_shield)
+          )
         end
         diagnostics
       end
@@ -300,18 +323,22 @@ module Rigor
         shadow_verify_node_collectors(path, root, scope_index, collectors)
       end
 
-      def call_node_diagnostics(path, node, scope_index, eval_ranges = nil, lexical_sites = nil)
+      # Issue #2786 — the rules that type the call's receiver read it from one {CallFacts}, so the receiver chain is
+      # typed once per call node rather than once per rule.
+      def call_node_diagnostics(path, node, scope_index, eval_ranges = nil, lexical_sites = nil,
+                                raise_shield = nil)
+        facts = CallFacts.new(node, scope_index)
         [
-          undefined_method_diagnostic(path, node, scope_index, lexical_sites),
+          undefined_method_diagnostic(path, node, facts, lexical_sites),
           unresolved_toplevel_diagnostic(path, node, scope_index, eval_ranges, lexical_sites),
-          wrong_arity_diagnostic(path, node, scope_index, lexical_sites),
-          argument_type_diagnostic(path, node, scope_index, lexical_sites),
-          nil_receiver_diagnostic(path, node, scope_index, lexical_sites),
+          wrong_arity_diagnostic(path, node, facts, lexical_sites),
+          argument_type_diagnostic(path, node, facts, lexical_sites),
+          nil_receiver_diagnostic(path, node, facts, lexical_sites),
           dump_type_diagnostic(path, node, scope_index),
           assert_type_diagnostic(path, node, scope_index),
-          always_raises_diagnostic(path, node, scope_index, lexical_sites),
+          always_raises_diagnostic(path, node, facts, lexical_sites, raise_shield),
           raise_non_exception_diagnostic(path, node, scope_index),
-          visibility_mismatch_diagnostic(path, node, scope_index, lexical_sites)
+          visibility_mismatch_diagnostic(path, node, facts, lexical_sites)
         ].compact
       end
 
@@ -407,6 +434,11 @@ module Rigor
         end
       end
 
+      # ADR-128 WD6 / ADR-130 slice 2 — `plugin.api-surface`, from its collector's results.
+      def plugin_api_surface_diagnostics(path, results)
+        PluginApiSurface.diagnostics(path, results)
+      end
+
       # ADR-100 WD2 — `static.value-use.void`. Its value-context slot inspection rides the shared per-node
       # {RuleWalk} like the other collectors, so the file is not re-traversed for it. Each result is a
       # value-context use of a call whose author-declared `-> void` return the engine recovered to `top`.
@@ -740,10 +772,10 @@ module Rigor
       class << self
         private
 
-        def undefined_method_diagnostic(path, call_node, scope_index, lexical_sites = nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def undefined_method_diagnostic(path, call_node, facts, lexical_sites = nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           return nil if call_node.receiver.nil?
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return nil if scope.nil?
 
           # The exemptions that hold whatever shape the receiver has. Ahead of the receiver-shape
@@ -776,7 +808,7 @@ module Rigor
           # below — preserving that keeps `&.` from newly firing on the
           # non-nil constituent (which, for a cross-file project def, would
           # be a working-code false positive).
-          receiver_type = safe_navigation_receiver(call_node, scope)
+          receiver_type = safe_navigation_receiver(call_node, facts.receiver_type)
 
           # #320 — the private-singleton-object idiom (`class << Merger = Object.new`). The body's methods
           # are recorded on the constant's own name, but the receiver reads back as `Object`, so the
@@ -973,16 +1005,268 @@ module Rigor
                                                             call_node: call_node)
           return true if module_mixin_receiver?(receiver_type, scope)
           return true if mixin_self_class_receiver?(call_node, scope)
-          return true if unknown_mixin_includer?(class_name, scope)
+          return true if unknown_mixin_includer?(class_name, scope, kind)
           return true if object_mixin_may_define?(receiver_type, class_name, call_node.name, scope)
           return true if ancestry_declares_method?(scope, class_name, call_node.name, kind)
+          return true if open_names_through_ancestors?(scope, class_name, kind)
+          return true if foreign_singleton_through_ancestors?(scope, class_name, call_node.name, kind)
 
           rbs_ancestor_may_answer?(class_name, call_node.name, scope, kind)
         end
 
+        # Issue #2793 — the class, or a project class or module on its chain, carries
+        # `Scope::DiscoveryIndex::ENVELOPE_OPEN_NAMES_MARK`: a macro there defines methods under names its syntax
+        # does not spell (`def_delegators :@x, *NAMES`), so no name is provably missing. A chain cut at its budget
+        # never reaches here: {#ancestry_declares_method?} reads the same chain first and declines on the cut.
+        # A non-literal `define_method` records its own side's twin of the mark instead, read beside it here.
+        OPEN_NAMES_MARKS = {
+          instance: [Scope::DiscoveryIndex::ENVELOPE_OPEN_NAMES_MARK,
+                     Scope::DiscoveryIndex::ENVELOPE_OPEN_INSTANCE_NAMES_MARK].freeze,
+          singleton: [Scope::DiscoveryIndex::ENVELOPE_OPEN_NAMES_MARK,
+                      Scope::DiscoveryIndex::ENVELOPE_OPEN_SINGLETON_NAMES_MARK].freeze
+        }.freeze
+        private_constant :OPEN_NAMES_MARKS
+
+        def open_names_through_ancestors?(scope, class_name, kind)
+          side = kind == :singleton ? :singleton : :instance
+          marks = OPEN_NAMES_MARKS.fetch(side)
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s, side, :methods)
+          # A project class with no `def` of its own is held as an external entry (#2094), so an external's
+          # candidate names are asked too.
+          found = chain.search(scope) do |entry|
+            names = entry.external? ? entry.candidates : [entry.name]
+            names.any? do |name|
+              bucket = scope.parameter_envelopes_of(name)
+              marks.any? { |mark| bucket.key?(mark) } ||
+                (side == :instance && (computed_definer_called?(scope, name, bucket) ||
+                                       hook_block_macro_defines?(scope, name)))
+            end
+          end
+          !found.nil?
+        end
+
+        # Issue #3018 — a class object's singleton method that `def Foo.x`, `Foo.define_singleton_method(:x)` or a
+        # `Foo.singleton_class.class_eval` def defines outside `Foo`'s body records no `:singleton` row, only an
+        # envelope entry. The class-object path reads the definer's own entry
+        # (`Scope::DiscoveryIndex::ENVELOPE_OBJECT_SINGLETON_KIND`) on the chain's class-object entries, the class and
+        # its superclasses, so a subclass inherits it. An extended module's entry is instance-side: `extend M` adds
+        # `M`'s instance methods, not a `def M.x`. It does not read the opaque `[:singleton, x]` entry beside it, which
+        # a name-rewriting class-body macro (`my_attr :x`) files too without defining `x` on the class object.
+        def foreign_singleton_through_ancestors?(scope, class_name, method_name, kind)
+          return false unless kind == :singleton
+
+          key = [Scope::DiscoveryIndex::ENVELOPE_OBJECT_SINGLETON_KIND, method_name.to_sym]
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s, :singleton, :methods)
+          found = chain.search(scope, side: :singleton) do |entry|
+            names = entry.external? ? entry.candidates : [entry.name]
+            names.any? { |name| scope.parameter_envelopes_of(name).key?(key) }
+          end
+          !found.nil?
+        end
+
+        # Issue #2901 — the body of `name` calls, on `self`, a method its singleton chain resolves to a computed
+        # definer (`Scope::DiscoveryIndex::ENVELOPE_COMPUTED_DEFINER_KIND`): a class macro of its own, a
+        # superclass's or an extended module's, which runs `define_method` under a name no table holds. The first
+        # entry on that chain carrying the macro's definer entry answers; a closer override that defines nothing is
+        # not looked for, so it leaves the class open.
+        #
+        # Issue #2975 — the definer entry carries its side: the class's own singleton entry answers with a singleton
+        # method (`def self.my_attr`), an extended module's entry with an instance method, so an instance `def my_attr`
+        # of the class itself opens nothing. A macro patched onto `Module` (or `Class`, `Object`, `Kernel`,
+        # `BasicObject`) as an instance method is on every class object's singleton chain past its own classes.
+        def computed_definer_called?(scope, name, bucket)
+          macros = bucket.each_key.filter_map do |key|
+            key.last if key.is_a?(Array) && key.first == Scope::DiscoveryIndex::ENVELOPE_BODY_CALL_KIND
+          end
+          return false if macros.empty?
+
+          chain = Scope::ResolutionChain.for(scope, name.to_s, :singleton, :methods)
+          found = macros.any? do |macro|
+            !chain.search(scope) { |entry| macro_entry_defines?(scope, entry, macro) }.nil? ||
+              universal_macro_defines?(scope, macro)
+          end
+          found || hook_extended_macro_defines?(scope, name, macros)
+        end
+
+        # Issue #2975 — a module that a class on `name`'s superclass chain includes or prepends directly, and whose
+        # `included` / `prepended` hook extends its includer with a module (`def self.included(base) =
+        # base.extend(ClassMethods)`), puts that module's instance methods on `name`'s singleton chain, which records no
+        # edge for it. Ruby runs the hook for the direct includer only, so a module included through another module does
+        # not count; the chain's levels flatten a class's transitive mixins, so each level class's own mixin list is
+        # read, one hop, never followed further. Each mixin and each extended constant resolves to the first candidate
+        # the project declares, the innermost cref first, whether or not RBS declares the modules; a concern's
+        # `ClassMethods` resolves as `const_get` does instead (#2986).
+        def hook_extended_macro_defines?(scope, name, macros)
+          definers = macro_definers(macros)
+          direct_hook_mixins(scope, name).any? { |mixin, _edges| hook_extension_defines?(scope, mixin, definers) }
+        end
+
+        # Issue #2986 — an ActiveSupport::Concern's `included do … end` block runs in the class body of a class that
+        # includes the concern directly, and its `prepended do … end` block in one that prepends it, so a macro call
+        # in the block is read as that class's own, against the module the concern extends it with. A call in the
+        # concern's own module body is no includer's: Ruby raises there as the module loads.
+        #
+        # Issue #2992 — Ruby runs the block in every direct includer, a module included, so the read is made for each
+        # entry of the receiver's chain (`owner`) against that entry's own mixins, one hop. A concern included into a
+        # concern after its `extend ActiveSupport::Concern` runs no block there: `Concern#append_features` records it as
+        # a dependency, and the outer concern's final includer includes it, on that includer's own edge
+        # ({#with_concern_dependencies}). Only a mixin whose one `include` / `prepend` statement is such a dependency
+        # is left out of `owner`'s own read: one written ahead of the `extend`, or again in a reopening that may load
+        # first, is an ordinary include there.
+        def hook_block_macro_defines?(scope, owner)
+          own_mixin_edges(scope, owner, deferred: true).any? do |mixin, edges|
+            macros = scope.parameter_envelopes_of(mixin).each_key.filter_map do |key|
+              key[2] if key.is_a?(Array) && key.first == Scope::DiscoveryIndex::ENVELOPE_HOOK_BODY_CALL_KIND &&
+                        edges.include?(Scope::ResolutionChain.effective_hook(scope.discovery, mixin, key[1]))
+            end
+            !macros.empty? && hook_extension_defines?(scope, mixin, macro_definers(macros))
+          end
+        end
+
+        def macro_definers(macros)
+          macros.map { |macro| [Scope::DiscoveryIndex::ENVELOPE_COMPUTED_DEFINER_KIND, :instance, macro] }
+        end
+
+        # Each module a class on `name`'s superclass chain includes or prepends directly, resolved, with the hook
+        # blocks its edges run: `:included` for an `include`, `:prepended` for a `prepend`; a concern's dependencies
+        # follow it on the same edges.
+        def direct_hook_mixins(scope, name)
+          chain = Scope::ResolutionChain.for(scope, name.to_s, :instance, :methods)
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          chain.level_classes.compact.flat_map { |klass| own_mixin_edges(scope, klass) }
+        end
+
+        # The modules `owner` itself includes or prepends, as {#direct_hook_mixins} gives them. With `deferred:`, a
+        # provable dependency of a concern `owner` is left out ({#hook_block_macro_defines?}).
+        def own_mixin_edges(scope, owner, deferred: false)
+          mixins = scope.includes_of(owner)
+          prepends = scope.prepends_of(owner)
+          deferred_mixins = deferred ? deferred_dependencies(scope, owner, mixins) : NO_DEFERRED
+          mixins.uniq.flat_map do |raw|
+            mixin = declared_constant(scope, owner, raw)
+            next [] unless mixin
+
+            edges = []
+            edges << :prepended if prepends.include?(raw)
+            edges << :included if mixins.count(raw) > prepends.count(raw)
+            next [] if deferred_mixins.include?(raw)
+
+            with_concern_dependencies(scope, mixin).map { |member| [member, edges] }
+          end
+        end
+
+        NO_DEFERRED = [].freeze
+        private_constant :NO_DEFERRED
+
+        # The spellings among `owner`'s mixins that name a concern dependency of `owner`, when `owner` is declared in
+        # one file: a reopening may write the same `include` without the `extend`, and load first.
+        def deferred_dependencies(scope, owner, mixins)
+          sites = scope.discovery.discovered_class_sources[owner.to_s]
+          return NO_DEFERRED if sites.nil? || sites.size > 1
+
+          resolver = Scope::ResolutionChain.resolver_for(scope, :methods)
+          dependencies = Scope::ResolutionChain.concern_dependencies(scope.discovery, resolver, owner)
+          return NO_DEFERRED if dependencies.empty?
+
+          Scope::ResolutionChain.dependency_spellings(scope.discovery, owner).select do |raw|
+            mixins.include?(raw) && dependencies.include?(resolver.resolve_declared(owner, raw))
+          end
+        end
+
+        # Issue #2992 — `mixin` and, when it is a concern, the concerns it includes or prepends, at any depth through
+        # concerns ({Scope::ResolutionChain.concern_dependencies}): `Concern#append_features` (or `prepend_features`)
+        # includes (or prepends) each of them into the final includer ahead of `mixin` itself, on the includer's own
+        # edge to `mixin`, whatever edge each was given. A reader files each one's sites as it reads its envelopes.
+        def with_concern_dependencies(scope, mixin)
+          resolver = Scope::ResolutionChain.resolver_for(scope, :methods)
+          [mixin, *Scope::ResolutionChain.concern_dependencies(scope.discovery, resolver, mixin)]
+        end
+
+        def hook_extension_defines?(scope, mixin, definers)
+          hook_extends(scope, mixin).any? do |written, lookup|
+            target = if lookup == :const_get then const_get_constant(scope, mixin, written)
+                     else declared_constant(scope, mixin, written)
+                     end
+            record_hook_target_edges(scope, mixin, written, lookup) if Analysis::DependencyRecorder.active?
+            target && definers.any? { |definer| scope.parameter_envelopes_of(target).key?(definer) }
+          end
+        end
+
+        # Issue #2992 — the read depends on the extended module's files whether or not it resolved: an empty
+        # `module ClassMethods; end` is no project class yet, and the edit that gives it the definer makes it one. So
+        # every name the lookup tried files its declaring sites, and the constant's last segment its negative class
+        # edge, which a NEW file declaring it fires.
+        def record_hook_target_edges(scope, mixin, written, lookup)
+          candidates = if lookup == :const_get
+                         chain = Scope::ResolutionChain.for(scope, mixin, :instance, :methods)
+                         chain.entries.flat_map { |entry| entry.external? ? entry.candidates : [entry.name] }
+                              .map { |name| "#{name}::#{written}" } << written
+                       else
+                         own = written.start_with?("::") ? [] : ["#{mixin}::#{written}"]
+                         own + scope.ancestor_name_candidates(mixin, written)
+                       end
+          candidates.each { |candidate| Scope::ResolutionChain.record_class(scope, candidate.delete_prefix("::")) }
+          Analysis::DependencyRecorder.read_last_segment(:class, written)
+        end
+
+        # The constant `raw`, written in `owner`'s body, as the first candidate the project declares: `Owner::Raw`
+        # first, since `owner` is the innermost cref there, then the enclosing namespaces. Nil when none is declared.
+        def declared_constant(scope, owner, raw)
+          candidates = scope.ancestor_name_candidates(owner, raw)
+          candidates = ["#{owner}::#{raw}", *candidates] unless raw.start_with?("::")
+          candidates.find { |candidate| scope.known_user_class?(candidate) }
+        end
+
+        # Issue #2986 — `owner.const_get(raw)`, as `Concern#append_features` looks `ClassMethods` up: `owner` and its
+        # ancestors, then `Object`, never the namespaces enclosing `owner`. Issue #2997 — a `class_methods` block's
+        # `Name::ClassMethods` counts only for a concern `Name` ({Scope::ResolutionChain.const_get_candidate?}).
+        def const_get_constant(scope, owner, raw)
+          chain = Scope::ResolutionChain.for(scope, owner, :instance, :methods)
+          found = chain.search(scope) do |entry|
+            names = entry.external? ? entry.candidates : [entry.name]
+            names.map { |name| [name, "#{name}::#{raw}"] }.find do |name, candidate|
+              scope.known_user_class?(candidate) &&
+                Scope::ResolutionChain.const_get_candidate?(scope.discovery, name, candidate)
+            end&.last
+          end
+          found || (raw if scope.known_user_class?(raw))
+        end
+
+        # The `[written, lookup]` pairs of a module's hook-extend entries; `lookup` is `:const_get` for a concern's.
+        # Issue #3005 — a gated concern-block entry counts only for a concern `owner`.
+        def hook_extends(scope, owner)
+          scope.parameter_envelopes_of(owner).each_key.filter_map do |key|
+            next unless key.is_a?(Array) && key.first == Scope::DiscoveryIndex::ENVELOPE_HOOK_EXTEND_KIND
+            next unless Scope::ResolutionChain.effective_hook(scope.discovery, owner, key[2])
+
+            key[1, 2]
+          end
+        end
+
+        # A macro's owner holds the macro's `def`, so it is never an external entry.
+        def macro_entry_defines?(scope, entry, macro)
+          !entry.external? &&
+            scope.parameter_envelopes_of(entry.name).key?([Scope::DiscoveryIndex::ENVELOPE_COMPUTED_DEFINER_KIND,
+                                                           entry.side, macro])
+        end
+
+        # The classes past a class object's own singleton chain, whose instance methods it answers. A module's chain
+        # does not reach `Class`, but a module body calling a `Class` macro raises as it loads, so it is not told apart.
+        UNIVERSAL_MACRO_OWNERS = %w[Class Module Object Kernel BasicObject].freeze
+        private_constant :UNIVERSAL_MACRO_OWNERS
+
+        def universal_macro_defines?(scope, macro)
+          definer = [Scope::DiscoveryIndex::ENVELOPE_COMPUTED_DEFINER_KIND, :instance, macro]
+          UNIVERSAL_MACRO_OWNERS.any? { |owner| scope.parameter_envelopes_of(owner).key?(definer) }
+        end
+
         # Issue #1722 — a `method_missing`, or a project mixin, on one of the class's RBS ancestors
         # ({RbsReceiverSurface}). Last for {#ancestry_declares_method?}'s reason: it walks the class graph.
+        # Issue #2792 — a `method_missing` RBS declares on the class or an ancestor, other than the universal one.
         def rbs_ancestor_may_answer?(class_name, method_name, scope, kind)
+          side = kind == :singleton ? :singleton : :instance
+          return true if RbsReceiverSurface.rbs_missing_hook?(scope, class_name, side)
+
           if kind == :singleton
             RbsReceiverSurface.singleton_hook?(scope, class_name) ||
               RbsReceiverSurface.singleton_mixin_may_answer?(scope, class_name, method_name)
@@ -1376,13 +1660,19 @@ module Rigor
         # answers, that never reaches a verdict — depend on `Widget`'s declaring file.
         # `dependency_recorder_spec` caught it here exactly as it caught #723's walk.
         #
-        # The receiver's OWN includes only. A project ancestor's unknown include makes the surface just as
-        # unknown; walking the chain is a deliberate deferral rather than an oversight.
-        def unknown_mixin_includer?(class_name, scope)
+        # A constant the environment does not know is read off the receiver's OWN includes only. Issue #2991 — a
+        # mixin no name spells (`include(*MODS)`, `include helper`) opens the receiver when it sits anywhere on its
+        # instance-side chain, its own level or an ancestor's: the chain marks it (`ResolutionChain#unnamed_mixin?`),
+        # and any name may come from the unlisted module (a hook's `base.include M` is read so too). `self.include M`
+        # and a receiverless `send(:include, M)` are recorded as `include M` is (#2995), so the ordinary lookup reads
+        # `M`. A mixin whose ORDER alone is unknown (`include M; prepend M`) has its module recorded, so it opens
+        # nothing. A class-object receiver reads its singleton chain instead ({#singleton_mixin_may_answer?}).
+        def unknown_mixin_includer?(class_name, scope, kind)
           includes = scope.includes_of(class_name)
-          return false if includes.empty?
+          return true if includes.any? { |raw| !known_mixin?(raw, class_name, scope) }
+          return false if kind == :singleton
 
-          includes.any? { |raw| !known_mixin?(raw, class_name, scope) }
+          Scope::ResolutionChain.for(scope, class_name.to_s, :instance, :methods).unnamed_mixin?
         end
 
         def known_mixin?(raw_name, class_name, scope)
@@ -1494,8 +1784,8 @@ module Rigor
         # as a per-instance singleton method and answers the rest through a private `method_missing` (ostruct 0.6), so
         # no signature can enumerate its surface. The only other declaration in the environment is json's add-on
         # reopening (`json_create` / `as_json` / `to_json`), which made the class read as fully declared and every
-        # field access a `call.undefined-method`. `data/core_overlay/ostruct.rbs` declares that `method_missing`, and
-        # an RBS-declared `method_missing` does not by itself open a receiver here, so the class is named. No load
+        # field access a `call.undefined-method`. `data/core_overlay/ostruct.rbs` declares that `method_missing`; since
+        # #2792 that alone keeps `call.undefined-method` silent, but the rules below still need the class named. No load
         # gate is needed: the core overlay loads into every environment that has RBS at all, so the list is active
         # whenever the declaration it protects is. Both sides of the class are open, as with
         # {GEM_OVERLAY_OPEN_RECEIVERS}, and an inherited Object / Kernel signature stops deciding `call.wrong-arity`
@@ -1636,38 +1926,51 @@ module Rigor
           registry.open_receiver?(class_name)
         end
 
-        # Whether THIS run's RBS environment actually includes one of Rigor's OWN partial declarations of the
-        # overlaid gem — {GEM_OVERLAY_OPEN_RECEIVERS} membership alone must not grant the exemption (see that
-        # constant's comment). `RbsLoader#signature_paths` is the same list `Environment.for_project` builds
-        # from `resolved_paths + plugin_sig_paths + gem_sig_paths + collection_paths + overlay_paths`, and
-        # two of its members can carry that declaration:
+        # Whether THIS run's RBS environment actually includes Rigor's OWN partial declaration of
+        # ACTIVESUPPORT — {GEM_OVERLAY_OPEN_RECEIVERS} membership alone must not grant the exemption (see
+        # that constant's comment), and both members of that list are `ActiveSupport` classes, so the gate
+        # asks for the activesupport overlay specifically. Issue #2857 added a SECOND bundled overlay
+        # (`addressable`, eligible under `:rbs_collection` coverage), and a collection project can load it
+        # while the activesupport overlay stays unloaded — keying on "any `data/gem_overlay/` directory"
+        # would then silence `ActiveSupport::Duration#bar`, the ADR-26 false negative this gate exists to
+        # prevent.
         #
-        # - a `data/gem_overlay/<gem>/` directory, which is a member if and only if `gem_overlay_paths`
-        #   picked it (the gem is locked, `:missing` coverage, and its plugin twin is NOT reachable —
-        #   ADR-72), so the `RbsLoader.under_gem_overlay_root?` prefix match is exact: no other signature
-        #   source lives under that root;
-        # - the bundled plugin twin's own `sig/`, when a project wires it through `signature_paths:` instead
-        #   of `plugins:`. Before #672 that route loaded BOTH halves and `Duration` collapsed outright, so
-        #   nothing fired and nothing needed protecting; now the overlay stands down and the twin's
-        #   declaration is the one that loads — with no manifest behind it, so `open_receiver?` above stays
-        #   false and this is the only thing standing between a real `Duration` receiver and a false
-        #   `call.undefined-method` on every member the declaration omits.
+        # `RbsLoader#signature_paths` is the same list `Environment.for_project` builds from
+        # `resolved_paths + plugin_sig_paths + gem_sig_paths + collection_paths + overlay_paths`, and
+        # two of its members can carry the activesupport declaration:
         #
-        # When the PLUGIN itself is loaded the first arm goes false (the overlay stands down) and the second
-        # goes true — its `sig/` rides in as a plugin signature path — but nothing here decides that case:
-        # `open_receiver?`'s manifest-driven check short-circuits above it. The two answers agree, which is
-        # the point; this predicate asks only whether a Rigor-authored partial declaration is in the
-        # environment, never how the project asked for it.
+        # - `data/gem_overlay/activesupport/` itself — a member if and only if `gem_overlay_paths` picked
+        #   it (the gem is locked, its coverage source admits the overlay — `:missing` for activesupport —
+        #   and its plugin twin is NOT reachable, ADR-72). {RbsLoader.gem_overlay_sig_paths} rebuilds the
+        #   exact Pathname `for_project` appended, so a plain `include?` is the test: no other signature
+        #   source can occupy that path;
+        # - the bundled activesupport plugin twin's own `sig/`, when a project wires it through
+        #   `signature_paths:` instead of `plugins:`. Before #672 that route loaded BOTH halves and
+        #   `Duration` collapsed outright, so nothing fired and nothing needed protecting; now the overlay
+        #   stands down and the twin's declaration is the one that loads — with no manifest behind it, so
+        #   `open_receiver?` above stays false and this is the only thing standing between a real
+        #   `Duration` receiver and a false `call.undefined-method` on every member the declaration
+        #   omits. {RbsLoader.gem_overlay_twin_signatures_loaded?} enumerates `GEM_OVERLAY_PLUGIN_IDS`'
+        #   values, which today is only the activesupport twin; a second overlay twin would need the same
+        #   per-gem keying this method now applies to the directory arm.
         #
-        # The two arms are asked in that order, over the WHOLE list each time, rather than interleaved per
-        # path: the overlay arm is a string prefix and the twin arm canonicalises paths on the filesystem,
-        # so the overwhelmingly common overlay-only run never reaches a syscall here.
+        # When the PLUGIN itself is loaded the first arm goes false (the overlay stands down) and the
+        # second goes true — its `sig/` rides in as a plugin signature path — but nothing here decides
+        # that case: `open_receiver?`'s manifest-driven check short-circuits above it. The two answers
+        # agree, which is the point; this predicate asks only whether the Rigor-authored activesupport
+        # declaration is in the environment, never how the project asked for it.
+        #
+        # The two arms are asked in that order, over the WHOLE list each time, rather than interleaved
+        # per path: the overlay arm is a Pathname comparison (plus the two `File.directory?` probes
+        # {RbsLoader.gem_overlay_sig_paths} needs to rebuild the path) and the twin arm canonicalises
+        # paths on the filesystem, so an overlay-only run pays the cheaper arm first.
         def gem_overlay_loaded?(scope)
           loader = scope.environment&.rbs_loader
           return false if loader.nil? || !loader.respond_to?(:signature_paths)
 
           paths = loader.signature_paths
-          paths.any? { |path| Rigor::Environment::RbsLoader.under_gem_overlay_root?(path) } ||
+          activesupport_overlay = Rigor::Environment::RbsLoader.gem_overlay_sig_paths(["activesupport"])
+          paths.any? { |path| activesupport_overlay.include?(path) } ||
             Rigor::Environment::RbsLoader.gem_overlay_twin_signatures_loaded?(paths)
         end
 
@@ -1750,6 +2053,16 @@ module Rigor
           method_def
         end
 
+        # Issue #2786 — {#trustworthy_signature} on the call's receiver as {CallFacts} types it, resolved once per
+        # call node: `call.wrong-arity` and `call.argument-type-mismatch` both ask it with that receiver type and its
+        # concrete class.
+        def receiver_signature(facts)
+          facts.receiver_signature do
+            receiver_type = facts.receiver_type
+            trustworthy_signature(receiver_type, concrete_class_name(receiver_type), facts.call_node, facts.scope)
+          end
+        end
+
         def unauthoritative_inherited_signature?(class_name, method_def, scope)
           return false unless unbounded_receiver_surface?(class_name, scope)
           return true unless method_def.respond_to?(:defined_in)
@@ -1942,18 +2255,18 @@ module Rigor
         # it returns nil when the call's receiver / RBS coverage /
         # call shape disqualifies the rule.
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        def wrong_arity_diagnostic(path, call_node, scope_index, lexical_sites = nil)
+        def wrong_arity_diagnostic(path, call_node, facts, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           return nil unless plain_positional_call?(call_node)
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return nil if scope.nil?
 
           # ADR-67 WD6b — an inferred-parameter receiver's type is an open-call-site lower bound; a wrong-arity
           # firing against it is an FP by construction. Decline.
           return nil if inferred_param_receiver?(call_node, scope)
 
-          receiver_type = scope.type_of(call_node.receiver)
+          receiver_type = facts.receiver_type
           class_name = concrete_class_name(receiver_type)
           return nil if class_name.nil?
 
@@ -1974,7 +2287,7 @@ module Rigor
           # false positive. Skip arity-checking the chained position.
           return nil if anonymous_struct_new_call?(call_node, class_name, kind)
 
-          arity_envelope = arity_envelope_for(receiver_type, class_name, call_node, scope, kind)
+          arity_envelope = arity_envelope_for(facts, class_name, kind)
           return nil if arity_envelope.nil?
 
           actual = (call_node.arguments&.arguments || []).size
@@ -2005,11 +2318,14 @@ module Rigor
         # declaration. `trustworthy_signature` is the same lookup `argument_type_diagnostic` treats as
         # authoritative over a source `def` (see its own comment beside that call), and the two rules must agree
         # on whose contract binds, so a declared method is checked against its declaration.
-        def arity_envelope_for(receiver_type, class_name, call_node, scope, kind)
+        def arity_envelope_for(facts, class_name, kind)
+          receiver_type = facts.receiver_type
+          call_node = facts.call_node
+          scope = facts.scope
           if Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
             return nil unless definition_available?(receiver_type, class_name, scope)
 
-            method_def = trustworthy_signature(receiver_type, class_name, call_node, scope)
+            method_def = receiver_signature(facts)
             if method_def && !Rigor::RbsExtended.inferred_signature?(method_def)
               return nil if undeclared_constructor?(class_name, call_node, kind, method_def)
 
@@ -2194,7 +2510,7 @@ module Rigor
         # and union receivers where every member already
         # disqualifies the call (avoid duplicating the
         # undefined-method diagnostic).
-        def nil_receiver_diagnostic(path, call_node, scope_index, lexical_sites = nil)
+        def nil_receiver_diagnostic(path, call_node, facts, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           # Safe-navigation calls (`recv&.method`) already
           # short-circuit on nil at runtime, so a nil-bearing
@@ -2208,7 +2524,7 @@ module Rigor
           # produce false positives we cannot suppress.
           return nil unless call_node.receiver.is_a?(Prism::LocalVariableReadNode)
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return nil if scope.nil?
 
           # ADR-58 WD1 — a receiver whose `nil` constituent is purely
@@ -2234,7 +2550,7 @@ module Rigor
           # construction. Decline.
           return nil if scope.inferred_param?(call_node.receiver.name)
 
-          receiver_type = scope.type_of(call_node.receiver)
+          receiver_type = facts.receiver_type
           return nil unless receiver_type.is_a?(Type::Union)
 
           # The rule only fires when the analyzer has access to
@@ -2243,7 +2559,7 @@ module Rigor
           return nil unless Rigor::Reflection.rbs_class_known?("NilClass", scope: scope)
 
           return nil unless nil_bearing_union_witnesses?(receiver_type, call_node.name, scope)
-          return nil if nil_receiver_withheld?(call_node, receiver_type, scope, scope_index, lexical_sites)
+          return nil if nil_receiver_withheld?(call_node, receiver_type, scope, facts.scope_index, lexical_sites)
 
           build_nil_receiver_diagnostic(path, call_node)
         end
@@ -2282,8 +2598,7 @@ module Rigor
         # nil so the rule bails (silent). Every other receiver (including a
         # `T | nil` union, which already has no single concrete class) flows
         # through unchanged.
-        def safe_navigation_receiver(call_node, scope)
-          receiver_type = scope.type_of(call_node.receiver)
+        def safe_navigation_receiver(call_node, receiver_type)
           return receiver_type unless call_node.safe_navigation?
           return receiver_type unless nil_member?(receiver_type)
 
@@ -2605,22 +2920,24 @@ module Rigor
         INTEGER_RAISING_OPERATORS = %i[/ % div modulo divmod].freeze
         private_constant :INTEGER_RAISING_OPERATORS
 
-        def always_raises_diagnostic(path, call_node, scope_index, lexical_sites = nil)
-          return nil unless integer_zero_division?(call_node, scope_index)
+        def always_raises_diagnostic(path, call_node, facts, lexical_sites = nil, raise_shield = nil)
+          return nil unless integer_zero_division?(call_node, facts)
 
           # ADR-121 WD7 — a refinement of `Integer`'s operator (or one Rigor cannot read) in effect may not raise.
-          scope = scope_index[call_node]
-          return nil if refined_method_in_effect?("Integer", call_node, scope, :instance, lexical_sites)
+          return nil if refined_method_in_effect?("Integer", call_node, facts.scope, :instance, lexical_sites)
+
+          # Issue #3036 — a raise an enclosing `begin` / `def … rescue` catches flows to the handler.
+          return nil if raise_shield&.rescued?(call_node, facts.scope)
 
           build_always_raises_diagnostic(path, call_node)
         end
 
-        def integer_zero_division?(call_node, scope_index)
+        def integer_zero_division?(call_node, facts)
           return false unless raising_call_shape?(call_node)
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return false if scope.nil?
-          return false unless integer_rooted_for_diagnostic?(scope.type_of(call_node.receiver))
+          return false unless integer_rooted_for_diagnostic?(facts.receiver_type)
 
           arg = single_argument(call_node)
           arg && integer_zero_constant?(scope.type_of(arg))
@@ -3132,17 +3449,17 @@ module Rigor
         # - Issue #1984 — Ruby hands a private call to `method_missing`, so a `method_missing` or
         #   `respond_to_missing?` a project entry on the receiver's chain records, on the side the call reaches,
         #   declines the rule ({#missing_hook_on_chain?}).
-        def visibility_mismatch_diagnostic(path, call_node, scope_index, lexical_sites = nil)
+        def visibility_mismatch_diagnostic(path, call_node, facts, lexical_sites = nil)
           return nil unless explicit_non_self_receiver?(call_node.receiver)
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return nil if scope.nil?
 
           # ADR-67 WD6b — an inferred-parameter receiver's nominal type is an open-call-site lower bound; a
           # private-method visibility firing against it is an FP by construction. Decline.
           return nil if inferred_param_receiver?(call_node, scope)
 
-          receiver_type = scope.type_of(call_node.receiver)
+          receiver_type = facts.receiver_type
           case receiver_type
           when Type::Nominal then instance_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
           when Type::Singleton then singleton_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
@@ -3187,7 +3504,14 @@ module Rigor
           build_visibility_mismatch_diagnostic(path, call_node, "singleton(#{class_name})")
         end
 
-        PRIVATE_NAMES_MEMO = RunScopedSlots.register(:rigor_check_rules_private_singleton_names)
+        # ADR-129 WD1 — a run-scoped Memo: one `[discovery, names]` slot keyed on the discovery index's identity, the
+        # only input the name set reads.
+        PRIVATE_NAMES_MEMO = TypingState.memo(
+          :check_rules_private_singleton_names,
+          run_scoped: true, audit: "private singleton names",
+          reason: "one [discovery, names] slot keyed on the discovery index's identity; the name " \
+                  "set reads only its method-visibility tables"
+        )
         private_constant :PRIVATE_NAMES_MEMO
 
         # Issue #1984 — the table-only gate the singleton side asks before it reads a chain, as the instance side asks
@@ -3198,12 +3522,23 @@ module Rigor
         def private_singleton_candidate?(scope, name)
           DependencyRecorder.read_visibility("*", name) if DependencyRecorder.active?
           discovery = scope.discovery
-          slot = Thread.current[PRIVATE_NAMES_MEMO]
+          if Inference::MemoAudit.enabled? && Inference::MemoAudit.suspended?
+            return private_recorded_names(discovery.discovered_method_visibilities).include?(name.to_sym)
+          end
+
+          state = TypingState.current
+          slot = state[PRIVATE_NAMES_MEMO]
           unless slot && slot[0].equal?(discovery)
-            slot = [discovery, private_recorded_names(discovery.discovered_method_visibilities)]
-            Thread.current[PRIVATE_NAMES_MEMO] = slot
+            names = Inference::MemoAudit.key_audit("private singleton names") do
+              private_recorded_names(discovery.discovered_method_visibilities)
+            end
+            slot = [discovery, names]
+            state[PRIVATE_NAMES_MEMO] = slot
+            return slot[1].include?(name.to_sym)
           end
-          slot[1].include?(name.to_sym)
+          Inference::MemoAudit.check("private singleton names", slot[1], name) do
+            private_recorded_names(discovery.discovered_method_visibilities)
+          end.include?(name.to_sym)
         end
 
         def private_recorded_names(tables)
@@ -3512,15 +3847,15 @@ module Rigor
         COERCE_DISPATCH_METHODS = %i[+ - * / % ** & | ^ << >> < > <= >=].to_set.freeze
         private_constant :COERCE_DISPATCH_METHODS
 
-        def argument_type_diagnostic(path, call_node, scope_index, lexical_sites = nil)
+        def argument_type_diagnostic(path, call_node, facts, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           return nil if UNIVERSAL_EQUALITY_METHODS.include?(call_node.name)
           return nil unless plain_positional_call?(call_node)
 
-          scope = scope_index[call_node]
+          scope = facts.scope
           return nil if scope.nil?
 
-          receiver_type = scope.type_of(call_node.receiver)
+          receiver_type = facts.receiver_type
           class_name = concrete_class_name(receiver_type)
           return nil if class_name.nil?
 
@@ -3533,11 +3868,11 @@ module Rigor
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
           return nil unless definition_available?(receiver_type, class_name, scope)
 
-          method_def = trustworthy_signature(receiver_type, class_name, call_node, scope)
+          method_def = receiver_signature(facts)
           return nil if method_def.nil?
 
           param_overrides = Rigor::RbsExtended.param_type_override_map(method_def, environment: scope.environment)
-          mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides, scope_index)
+          mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides, facts.scope_index)
           return nil if mismatch.nil?
           return nil if argument_report_withheld?(receiver_type, class_name, call_node, mismatch, scope, lexical_sites)
 
@@ -3685,12 +4020,36 @@ module Rigor
         # The non-nil channel (ADR-64 WD2/WD3): a single-concrete-class
         # argument no overload admits, on a non-coerce method.
         def non_nil_arg_overload_mismatch(arg, arg_type, params, param_overrides, scope)
+          return class_object_overload_mismatch(arg, arg_type, params, param_overrides, scope) if
+            arg_type.is_a?(Type::Singleton)
           return nil unless single_concrete_arg_class?(arg_type, scope)
           return nil if params.any? { |param| param_accepts_arg_class?(param, arg_type, param_overrides, scope) }
 
           { node: arg, name: nil, expected: overload_param_expected_label(params), actual: arg_type }
         end
 
+        # Issue #2828 — the class-object twin of the non-nil channel. A `singleton(T)` overload the `resolv` overlay
+        # prepends turned `getresources(d, String)`'s one-overload check (`expected singleton(Resolv::DNS::Query)`)
+        # into this multi-overload one, which declined every class object. It fires only when every overload's
+        # parameter at the position is a `singleton(...)` (a `singleton(T)` read through its class bound, see
+        # `SingletonTypeParams.selection_param`) that provably refuses the argument's class; any other parameter
+        # shape admits.
+        def class_object_overload_mismatch(arg, arg_type, params, param_overrides, scope)
+          return nil unless Rigor::Reflection.rbs_class_known?(arg_type.class_name, scope: scope)
+          return nil unless params.all? do |param|
+            !param_overrides[param.name] && param.type.is_a?(RBS::Types::ClassSingleton)
+          end
+          return nil unless params.all? { |param| class_singleton_refuses?(param.type, arg_type, scope) }
+
+          expected = params.map { |param| param.type.to_s.sub("singleton(::", "singleton(") }.uniq.join(" | ")
+          { node: arg, name: nil, expected: expected, actual: arg_type }
+        end
+
+        def class_singleton_refuses?(rbs_type, arg_type, scope)
+          translated = translate_param_type(rbs_type, scope.environment)
+          translated.is_a?(Type::Singleton) && Inference::Acceptance.accepts(translated, arg_type, mode: :gradual).no?
+        end
+
         # The matching positional RBS param across every overload, or nil when
         # any overload has no param at `index` (arity divergence — the
         # wrong-arity rule's concern, not this one's).
@@ -3711,6 +4070,7 @@ module Rigor
         # Load-bearing since rbs 4.1 rewrote core signatures into this form
         # (`Array#fetch`'s block overload is `[I < _ToInt, T] (I index) { … }`).
         def resolve_param_bounds(param, method_type)
+          param = Inference::MethodDispatcher::SingletonTypeParams.selection_param(param, method_type)
           bounded = method_type.type_params.select(&:upper_bound)
           return param if bounded.empty?
 
@@ -3997,6 +4357,7 @@ module Rigor
           param_type = param_overrides[param.name] || translate_param_type(param.type, scope.environment)
           return nil if param_type.is_a?(Type::Dynamic) || param_type.is_a?(Type::Top)
           return nil if arg_type.is_a?(Type::Dynamic) || arg_type.is_a?(Type::Top)
+          return nil if gradual_narrowing_accepted?(arg, arg_type, param_type, scope)
           return nil unless argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
           # Issue #1362 — a value that mixes such a global with something else (`c ? $stdout : StringIO.new`) is judged
           # without the declared members the file never writes, as it was before the join.
@@ -4034,10 +4395,34 @@ module Rigor
           Inference::Acceptance.accepts(param_type, type, mode: :gradual).no?
         end
 
+        # Issue #2656 — a local a class guard narrowed from a `Dynamic` value
+        # ({DeclarationSourcedGuard.gradual_narrowed?}) is judged by its class, not by the literals the parameter
+        # names: `mode(x) if x.is_a?(String)` with `mode: ("r" | "w")` is accepted, as the gradual value was, while
+        # `num(x) if x.is_a?(String)` with `num: (1 | 2)` still reports, since no String is ever `1` or `2`. The
+        # parameter's value-pinned members are widened to their classes ({Type::Combinator.widen_value_pinned}) and
+        # the narrowed type is judged against that. The overload path ({#non_nil_arg_overload_mismatch}) already
+        # judges by class, so it needs no such reading.
+        #
+        # A literal member of the narrowed type did not come from the gradual value (`x = h[:m] || "r"` narrows to
+        # `"r" | String`), so it is judged against the parameter as written.
+        def gradual_narrowing_accepted?(arg, arg_type, param_type, scope)
+          return false unless DeclarationSourcedGuard.gradual_narrowed?(arg, scope)
+
+          members = arg_type.is_a?(Type::Union) ? arg_type.members : [arg_type]
+          literals, rest = members.partition { |member| member.is_a?(Type::Constant) }
+          if literals.any? { |member| Inference::Acceptance.accepts(param_type, member, mode: :gradual).no? }
+            return false
+          end
+          return true if rest.empty?
+
+          widened = Type::Combinator.widen_value_pinned(param_type)
+          !Inference::Acceptance.accepts(widened, Type::Combinator.union(*rest), mode: :gradual).no?
+        end
+
         # The parameter rejects the argument AND the rejection is not a
         # withheld declaration-sourced-nil case.
         def argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
-          return false unless Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual).no?
+          return false unless rejects_beyond_class_objects?(param_type, arg_type)
 
           # ADR-58 (N2 extension) — the same declaration-sourced-nil-is-not-
           # diagnostic-fuel criterion that governs `possible-nil-receiver`
@@ -4053,6 +4438,31 @@ module Rigor
           !declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
         end
 
+        # Issue #2855 — the parameter rejects the argument, and not only for its `Class` / `Module` members. An
+        # unparameterised `Class` or `Module` nominal ({Acceptance.class_or_module_nominal?}) against a parameter
+        # that admits class objects (`singleton(X)`, alone or in a union) is a class object whose identity inference
+        # lost — a `const_get` result kept by `is_a?(Class)`, an `is_a?(Module)` guard — so it is withheld. The rest
+        # of the argument is still judged: `Class | Integer` against `singleton(X)` reports for its `Integer`.
+        # Acceptance itself keeps answering `no`, so overload selection is unchanged.
+        def rejects_beyond_class_objects?(param_type, arg_type)
+          return false unless Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual).no?
+          return true unless admits_class_objects?(param_type)
+
+          members = arg_type.is_a?(Type::Union) ? arg_type.members : [arg_type]
+          rest = members.reject { |member| Inference::Acceptance.class_or_module_nominal?(member) }
+          return true if rest.size == members.size
+
+          Inference::Acceptance.accepts(param_type, Type::Combinator.union(*rest), mode: :gradual).no?
+        end
+
+        def admits_class_objects?(param_type)
+          case param_type
+          when Type::Singleton then true
+          when Type::Union then param_type.members.any?(Type::Singleton)
+          else false
+          end
+        end
+
         # True when `arg` is a declaration-sourced read whose rejection is
         # caused solely by its nil constituent: stripping nil from the argument
         # type yields a type the parameter accepts (gradual mode). Mirrors the
@@ -4068,7 +4478,12 @@ module Rigor
           non_nil = Type::Combinator.union(*arg_type.members.reject { |m| nil_member?(m) })
           return false if non_nil.is_a?(Type::Bot)
 
-          Inference::Acceptance.accepts(param_type, non_nil, mode: :gradual).yes?
+          result = Inference::Acceptance.accepts(param_type, non_nil, mode: :gradual)
+          # Issue #2855 — a `Class?` ivar against `singleton(X)` is withheld as its `Class` alone would be.
+          # Issue #2863 — a `maybe` (a project class the host process has not loaded, so its ancestry is unresolved:
+          # `singleton(Circle)` against `singleton(Shape)`) is not a rejection either: the non-nil part alone would not
+          # fire, so the nil is the only reason and it is withheld.
+          !result.no? || !rejects_beyond_class_objects?(param_type, non_nil)
         end
 
         # What this rule needs is that argument N binds to positional
@@ -4186,7 +4601,7 @@ module Rigor
         #     :no    → emit at :error (severity_profile may re-stamp; default `balanced` keeps the
         #              authored severity).
         #     :maybe → silent (see {#compare_return}; ADR-8's `strict` promotion is deferred).
-        def return_type_mismatch_diagnostic(path, def_node, scope_index)
+        def return_type_mismatch_diagnostic(path, def_node, scope_index, replaced_defs = nil)
           return nil if def_node.body.nil?
 
           last_expr = body_last_expression(def_node.body)
@@ -4195,7 +4610,7 @@ module Rigor
           inner_scope = scope_index[last_expr] || scope_index[def_node.body] || scope_index[def_node]
           return nil if inner_scope.nil?
 
-          declared = declared_return_type(def_node, scope_index)
+          declared = declared_return_type(def_node, scope_index, replaced_defs)
           return nil if declared.nil?
 
           # Issue #1362 — a body that ends on a builtin global still on its declared seed, or on a local copied from
@@ -4242,14 +4657,18 @@ module Rigor
         # `non-empty-array[Integer]`, etc. — are stricter than the underlying RBS class, so a body whose
         # inferred type the bare RBS sig would accept may still fail the refinement (e.g. `def name; "";
         # end` returns `Constant[""]`, accepted by `String` but rejected by `non-empty-string`).
-        def declared_return_type(def_node, scope_index)
+        def declared_return_type(def_node, scope_index, replaced_defs = nil)
           scope = scope_index[def_node]
           return nil if scope.nil?
 
           self_type = scope.self_type
           return nil unless self_type.respond_to?(:class_name)
 
-          side = def_node.receiver.nil? ? receiverless_def_side(scope, self_type.class_name, def_node) : :singleton
+          side = if def_node.receiver.nil?
+                   receiverless_def_side(scope, self_type.class_name, def_node)
+                 else
+                   receiver_def_side(scope, self_type.class_name, def_node)
+                 end
           return nil if side.nil?
 
           method_def =
@@ -4260,6 +4679,7 @@ module Rigor
             end
           return nil if method_def.nil?
           return nil unless defined_on?(method_def, self_type.class_name)
+          return nil if replaced_receiver_def?(def_node, replaced_defs)
 
           override = Rigor::RbsExtended.read_return_type_override(method_def, environment: scope.environment)
           return override if override
@@ -4282,6 +4702,30 @@ module Rigor
           nil
         end
 
+        # Issue #3155 — a singleton def a later certain def replaced ({ReplacedSingletonDefs}). Asked only once the def
+        # has a signature to answer to, so the file walk runs only then.
+        def replaced_receiver_def?(def_node, replaced_defs)
+          !def_node.receiver.nil? && replaced_defs&.replaced?(def_node)
+        end
+
+        # Issue #3155 — `def self.x`, or `def K.x` in `K`'s body, answers to K's singleton signature. A def on another
+        # object (`def String.q`, `def obj.q` in a class body) or `def self.x` in a `class << self` body (a method of
+        # the singleton class's own singleton) answers to none of K's: `nil`, and the caller declines.
+        # {#declared_return_type} also declines, once a signature is found, a singleton def a later certain def of the
+        # name in the same body replaced (`def K.w`; `def self.w`; {ReplacedSingletonDefs}). `def (self).x` reads as
+        # `def self.x`; `K = self; def K.x` is not read.
+        def receiver_def_side(scope, class_name, def_node)
+          receiver = ReplacedSingletonDefs.unparenthesized(def_node.receiver)
+          lexical_self = if receiver.is_a?(Prism::SelfNode)
+                           !scope.singleton_class_body?
+                         else
+                           Inference::ScopeIndexer.def_receiver_targets_lexical_self?(receiver, class_name.split("::"))
+                         end
+          return nil unless lexical_self
+
+          :singleton
+        end
+
         # The tables hold the live node or one re-resolved from a `DefHandle`, so identity is the name and span.
         def same_def_node?(recorded, def_node)
           recorded.is_a?(Prism::DefNode) && recorded.name == def_node.name &&
@@ -4425,8 +4869,10 @@ module Rigor
         # defined LATER under that name would change the answer; `DefinerResolution` files the negative class
         # edge of each external entry it tests.
         def overridden_ancestors_start(scope, class_name)
-          own = Scope::ResolutionChain.for(scope, class_name.to_s, :instance, :methods).index_of(class_name.to_s)
-          own && (own + 1)
+          # Issue #2979 — past the entries of the names bound to the same class (`K = Struct.new("Named", …)`):
+          # a `def` there redefines the class's method rather than overriding an ancestor's.
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s, :instance, :methods)
+          chain.ancestors_start(scope, class_name.to_s)
         end
 
         # `[defining_class, visibility]` for the nearest user-source ancestor that defines an instance
@@ -4521,6 +4967,7 @@ module Rigor
           parent_return = declared_return_union(parent_method, scope.environment, type_vars: parent_type_vars)
           return nil if override_return.nil? || parent_return.nil?
           return nil if dynamic_top?(parent_return) # untyped / unbound-generic parent contract
+          return nil if void_over_nil?(override_method, parent_return)
 
           return nil unless parent_return.accepts(override_return).no?
 
@@ -4529,22 +4976,42 @@ module Rigor
           )
         end
 
+        # A `-> void` override of a parent return of exactly `nil` (or `NilClass`) is exempt (#3046): both
+        # say "no useful value", and callers cannot use a void return. Keyed on the declared `void` of every
+        # arm (the translator reads `void` as top, so a `-> top` override still fires); any non-nil parent
+        # return still fires.
+        def void_over_nil?(override_method, parent_return)
+          return false unless nil_type?(parent_return)
+
+          override_method.method_types.all? { |mt| mt.type.return_type.is_a?(::RBS::Types::Bases::Void) }
+        end
+
+        # `nil`, or the nominal `NilClass`, whose only value it is.
+        def nil_type?(type)
+          return type.value.nil? if type.is_a?(Type::Constant)
+
+          type.is_a?(Type::Nominal) && type.class_name == "NilClass" && type.type_args.empty?
+        end
+
         # `[defining_class, RBS::Definition::Method]` for the nearest project-discovered ancestor whose
         # RBS declares `method_name` (not the starting class's own declaration), or nil.
         def nearest_ancestor_method_def(scope, class_name, method_name)
           from = overridden_ancestors_start(scope, class_name)
           return nil if from.nil?
 
+          passed_owners = []
           case Inference::DefinerResolution.resolve(scope, class_name, method_name, :instance,
                                                     question: :override, from: from) do |ancestor|
-                 method_def = safe_instance_method_definition(ancestor, method_name, scope)
-                 # The signature text is the answer two worlds compare: an `RBS::Definition::Method` has no
-                 # structural equality of its own.
-                 method_def.method_types.map(&:to_s) if method_def && !defined_on?(method_def, class_name)
+                 override_parent_answer(scope, ancestor, method_name, passed_owners)
                end
-          in Inference::DefinerResolution::Known(owner:)
-            method_def = safe_instance_method_definition(owner, method_name, scope)
-            method_def && [owner, method_def]
+          in Inference::DefinerResolution::Known(owner:, answer:)
+            # The nearest declaration must be the one that answers: an ancestor asked past for a project
+            # owner the walk never reached (one the Ruby chain does not hold) leaves the rule silent.
+            unless answer.last == RBS_ONLY_OWNER ||
+                   passed_owners.any? { |passed| passed != normalize_class_name(owner) }
+              method_def = safe_instance_method_definition(owner, method_name, scope)
+              method_def && [owner, method_def]
+            end
           in Inference::DefinerResolution::UNKNOWN # the case/in contract needs one arm per answer
             nil
           in Inference::DefinerResolution::ABSENT # rubocop:disable Lint/DuplicateBranch -- see above
@@ -4552,6 +5019,38 @@ module Rigor
           end
         end
 
+        # The answer an RBS-only owner gives the override walk: it ends the walk, and the rule stays silent.
+        RBS_ONLY_OWNER = :rbs_only_owner
+        private_constant :RBS_ONLY_OWNER
+
+        # One project ancestor's answer to the override walk. The signature text is the answer two worlds
+        # compare: an `RBS::Definition::Method` has no structural equality of its own. Only an ancestor whose
+        # own RBS declares the method answers with it (#3046). One that inherits the declaration from another
+        # project class or module is asked past, so that owner answers at its own entry; the owner is recorded
+        # in `passed_owners`, which the answering owner must match. One that inherits it from an RBS-only owner
+        # the project chain cannot see ends the walk silent ({RBS_ONLY_OWNER}): that owner is the nearest
+        # declaration, and RBS-only ancestors are #130's.
+        def override_parent_answer(scope, ancestor, method_name, passed_owners)
+          method_def = safe_instance_method_definition(ancestor, method_name, scope)
+          return nil if method_def.nil?
+          return method_def.method_types.map(&:to_s) if declared_by?(method_def, ancestor)
+
+          owner = method_def.implemented_in || method_def.defined_in
+          return RBS_ONLY_OWNER unless owner && scope.discovered_classes.key?(normalize_class_name(owner))
+
+          passed_owners << normalize_class_name(owner)
+          nil
+        end
+
+        # True when `ancestor`'s own RBS declares `method_def`: on its body, or through an interface it
+        # includes itself (RBS records the including class as `implemented_in`).
+        def declared_by?(method_def, ancestor)
+          return true if defined_on?(method_def, ancestor)
+          return false unless method_def.defined_in&.interface?
+
+          normalize_class_name(method_def.implemented_in) == normalize_class_name(ancestor)
+        end
+
         def safe_instance_method_definition(class_name, method_name, scope)
           Reflection.instance_method_definition(class_name, method_name, scope: scope)
         rescue StandardError