rigortype 0.1.18 → 0.2.0

data/lib/rigor/analysis/check_rules.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../reflection"
 require_relative "../source/node_walker"
+require_relative "../source/constant_path"
 require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
@@ -12,41 +13,35 @@ require_relative "check_rules/always_truthy_condition_collector"
 require_relative "check_rules/unreachable_clause_collector"
 require_relative "check_rules/dead_assignment_collector"
 require_relative "check_rules/ivar_write_collector"
+require_relative "check_rules/main_pass_collector"
 require_relative "check_rules/self_closedness_scanner"
 
 module Rigor
   module Analysis
-    # First-preview catalogue of `rigor check` diagnostic rules.
+    # Catalogue of `rigor check` diagnostic rules.
     #
-    # The rules are intentionally narrow: they fire ONLY when the
-    # engine is confident enough to make a useful claim, and they
-    # MUST NOT raise on unrecognised AST shapes, RBS gaps, or
-    # missing scope information. Each rule consumes the per-node
-    # scope index produced by
+    # Rules fire ONLY when the engine is confident enough to make a
+    # useful claim and MUST NOT raise on unrecognised AST shapes,
+    # RBS gaps, or missing scope information. Each rule consumes
+    # the per-node scope index produced by
     # `Rigor::Inference::ScopeIndexer.index` and yields zero or
     # more `Rigor::Analysis::Diagnostic` values.
     #
-    # The first shipped rule, `UndefinedMethodOnTypedReceiver`,
-    # flags an explicit-receiver `Prism::CallNode` whose receiver
-    # statically resolves to a `Type::Nominal` or `Type::Singleton`
-    # known to the analyzer's RBS environment AND whose method
-    # name does not appear on that class's instance / singleton
-    # method table. This is the canonical "type check" signal
-    # ("Foo has no method bar"), but it explicitly does NOT fire
-    # for:
+    # The primary rule (`call.undefined-method`) flags an
+    # explicit-receiver `Prism::CallNode` whose receiver statically
+    # resolves to a class known to the RBS environment and whose
+    # method name does not appear on that class's method table.
+    # It does NOT fire for:
     #
     # - implicit-self calls (no `node.receiver`) — too noisy
     #   without per-method RBS for every helper in the class.
     # - dynamic / unknown receivers (`Dynamic[T]`, `Top`, `Union`)
     #   — by definition we cannot enumerate the method set.
-    # - shape carriers (`Tuple`, `HashShape`, `Constant`) — their
-    #   dispatch goes through `ShapeDispatch` / `ConstantFolding`
-    #   which the rule does not yet model.
+    # - shape carriers: `Tuple` → "Array", `HashShape` → "Hash",
+    #   `Constant` → the constant's class — `concrete_class_name`
+    #   resolves these to their runtime class for dispatch.
     # - receivers whose class name is NOT registered in the
     #   loader (RBS-blind environments, unknown stdlib).
-    #
-    # The above list is the deliberate conservative envelope of
-    # the first preview; later slices broaden it.
     # rubocop:disable Metrics/ModuleLength
     module CheckRules
       # Canonical identifiers for each rule. Per ADR-8 §
@@ -163,59 +158,149 @@ module Rigor
       # @param root [Prism::Node]
       # @param scope_index [Hash{Prism::Node => Rigor::Scope}]
       # @return [Array<Rigor::Analysis::Diagnostic>]
-      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [])
-        diagnostics = []
-        Source::NodeWalker.each(root) do |node|
-          case node
-          when Prism::CallNode
-            diagnostics.concat(call_node_diagnostics(path, node, scope_index))
-          when Prism::DefNode
-            return_diagnostic = return_type_mismatch_diagnostic(path, node, scope_index)
-            diagnostics << return_diagnostic if return_diagnostic
-            override_vis = override_visibility_diagnostic(path, node, scope_index)
-            diagnostics << override_vis if override_vis
-            override_return = override_return_widened_diagnostic(path, node, scope_index)
-            diagnostics << override_return if override_return
-            override_param = override_param_narrowed_diagnostic(path, node, scope_index)
-            diagnostics << override_param if override_param
-          when Prism::IfNode, Prism::UnlessNode
-            unreachable = unreachable_branch_diagnostic(path, node, scope_index)
-            diagnostics << unreachable if unreachable
-          end
-        end
+      #
+      # ADR-53 B4 — when `node_collectors` is supplied, the converged
+      # {Plugin::NodeRuleWalk} traversal has already populated the built-in
+      # collectors (including the main pass) in one shared walk with the
+      # plugin node-rules, so they are consumed as-is. When it is nil (a
+      # direct caller with no plugin walk, e.g. a unit test), the standalone
+      # {RuleWalk} walk runs here instead, so `diagnose` stays correct
+      # without the converged path.
+      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [],
+                   node_collectors: nil)
+        collectors = node_collectors || run_node_collectors(path, root, scope_index)
+        diagnostics = collectors[:main_pass].results.dup
         diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
-        always_truthy_results, unreachable_clause_results = flow_collector_results(root, scope_index)
-        diagnostics.concat(always_truthy_condition_diagnostics(path, always_truthy_results))
-        diagnostics.concat(unreachable_clause_diagnostics(path, unreachable_clause_results))
-        diagnostics.concat(ivar_write_mismatch_diagnostics(path, root, scope_index))
-        diagnostics.concat(dead_assignment_diagnostics(path, root, scope_index))
+        diagnostics.concat(always_truthy_condition_diagnostics(path, collectors[:always_truthy].results))
+        diagnostics.concat(unreachable_clause_diagnostics(path, collectors[:unreachable_clauses].results))
+        diagnostics.concat(ivar_write_mismatch_diagnostics(path, collectors[:ivar_writes].results))
+        diagnostics.concat(dead_assignment_diagnostics(path, collectors[:dead_assignments].results))
         filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
       end
 
-      # ADR-53 Track B (slice B2) — both flow collectors ride one
-      # {RuleWalk} traversal instead of walking the file once each.
-      # Under `RIGOR_SHADOW_RULE_WALK=1` the legacy per-collector walks
-      # also run as the oracle and any divergence aborts the run — the
-      # corpus-scale half of the equivalence harness (the curated half
-      # is `rule_walk_equivalence_spec`).
-      def flow_collector_results(root, scope_index)
-        always_truthy = AlwaysTruthyConditionCollector.new(scope_index)
-        unreachable_clauses = UnreachableClauseCollector.new(scope_index)
-        RuleWalk.run(root, [always_truthy, unreachable_clauses])
-        if ENV["RIGOR_SHADOW_RULE_WALK"]
-          shadow_verify_flow_collectors(root, scope_index, always_truthy.results, unreachable_clauses.results)
-        end
-        [always_truthy.results, unreachable_clauses.results]
+      # 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)
+        case node
+        when Prism::CallNode
+          call_node_diagnostics(path, node, scope_index)
+        when Prism::DefNode
+          [
+            return_type_mismatch_diagnostic(path, node, scope_index),
+            override_visibility_diagnostic(path, node, scope_index),
+            override_return_widened_diagnostic(path, node, scope_index),
+            override_param_narrowed_diagnostic(path, node, scope_index)
+          ].compact
+        when Prism::IfNode, Prism::UnlessNode
+          [unreachable_branch_diagnostic(path, node, scope_index)].compact
+        else
+          []
+        end
       end
 
-      def shadow_verify_flow_collectors(root, scope_index, always_truthy_results, unreachable_clause_results)
-        legacy_always = AlwaysTruthyConditionCollector.new(scope_index).collect(root)
-        legacy_clauses = UnreachableClauseCollector.new(scope_index).collect(root)
-        return if legacy_always == always_truthy_results && legacy_clauses == unreachable_clause_results
+      # Constructs the fresh, unpopulated built-in collector set keyed by
+      # role, including the main pass. Split out so the converged walk
+      # (ADR-53 B4) can build the collectors, drive them via a
+      # {RuleWalk::CollectorDriver} inside the single {Plugin::NodeRuleWalk}
+      # 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)
+        {
+          main_pass: MainPassCollector.new(->(node) { main_pass_node_diagnostics(path, node, scope_index) }),
+          always_truthy: AlwaysTruthyConditionCollector.new(scope_index),
+          unreachable_clauses: UnreachableClauseCollector.new(scope_index),
+          ivar_writes: IvarWriteCollector.new(scope_index),
+          dead_assignments: DeadAssignmentCollector.new(scope_index)
+        }
+      end
 
-        raise "RIGOR_SHADOW_RULE_WALK divergence: always-truthy legacy=#{legacy_always.size} " \
-              "walk=#{always_truthy_results.size}; unreachable-clause legacy=#{legacy_clauses.size} " \
-              "walk=#{unreachable_clause_results.size}"
+      # A {RuleWalk::CollectorDriver} over a built-in collector set, for a
+      # foreign traversal to drive (ADR-53 B4). The driver visits each node
+      # and derives child contexts exactly as the standalone {RuleWalk}
+      # walk would.
+      def node_collector_driver(collectors)
+        RuleWalk::CollectorDriver.new(collectors.values)
+      end
+
+      # ADR-53 Track B — the {RuleWalk}-hosted built-in collectors (the main
+      # pass and the four fact collectors) all ride one traversal of the
+      # file instead of one walk each. Returns the populated collectors
+      # keyed by role so the caller can build the diagnostics from each
+      # collector's `results`. Used on the standalone path (no converged
+      # plugin walk); the converged path populates the same collector set
+      # via {.node_collector_driver} instead.
+      #
+      # Under `RIGOR_SHADOW_RULE_WALK=1` each hosted collector's legacy
+      # single-collector `#collect` walk also runs as the oracle and any
+      # divergence aborts the run — the corpus-scale half of the
+      # equivalence harness (the curated half is `rule_walk_equivalence_spec`).
+      def run_node_collectors(path, root, scope_index)
+        collectors = build_node_collectors(path, scope_index)
+        RuleWalk.run(root, collectors.values)
+        shadow_verify_node_collectors(path, root, scope_index, collectors) if ENV["RIGOR_SHADOW_RULE_WALK"]
+        collectors
+      end
+
+      def shadow_verify_node_collectors(path, root, scope_index, collectors)
+        divergences = collectors.filter_map do |role, collector|
+          legacy = oracle_results(role, collector, path, root, scope_index)
+          next if comparable(legacy) == comparable(collector.results)
+
+          "#{role} legacy=#{legacy.size} walk=#{collector.results.size}"
+        end
+        return if divergences.empty?
+
+        raise "RIGOR_SHADOW_RULE_WALK divergence: #{divergences.join('; ')}"
+      end
+
+      # Normalises a collector's result for value comparison. The fact
+      # collectors return `Data` / Hash structures that already compare by
+      # value; the main pass returns {Diagnostic} objects (plain objects
+      # with identity `==`), so serialise those to hashes first.
+      def comparable(results)
+        return results.map(&:to_h) if results.is_a?(Array) && results.first.is_a?(Diagnostic)
+
+        results
+      end
+
+      # The oracle each hosted collector's walk result is checked against.
+      # The fact collectors re-run their legacy single-collector `#collect`
+      # walk; the main pass re-runs the former inline `Source::NodeWalker`
+      # `case` (`main_pass_oracle`) since its diagnostics are the result.
+      def oracle_results(role, collector, path, root, scope_index)
+        return main_pass_oracle(path, root, scope_index) if role == :main_pass
+
+        collector.class.new(scope_index).collect(root)
+      end
+
+      # The former inline main pass, kept as the shadow oracle: walks the
+      # tree with `Source::NodeWalker.each` and accumulates the same
+      # per-node diagnostics in the same order {MainPassCollector} now
+      # produces them on the shared walk.
+      def main_pass_oracle(path, root, scope_index)
+        diagnostics = []
+        Source::NodeWalker.each(root) do |node|
+          diagnostics.concat(main_pass_node_diagnostics(path, node, scope_index))
+        end
+        diagnostics
+      end
+
+      # ADR-53 B4 — corpus-scale oracle for the CONVERGED walk: the
+      # collectors (including the main pass, ADR-53 B3c) were populated by
+      # the {Plugin::NodeRuleWalk} traversal, not by `RuleWalk.run`, so
+      # re-run each collector's legacy oracle (the fact collectors'
+      # `#collect` walk, the main pass's inline `Source::NodeWalker` `case`)
+      # and assert the converged walk produced byte-identical results. Same
+      # divergence contract as {.shadow_verify_node_collectors}; nil
+      # collectors (caller without built-in collection) is a no-op. `path`
+      # is threaded because the main pass's oracle carries it.
+      def shadow_verify_converged_collectors(path, root, scope_index, collectors)
+        return if collectors.nil?
+
+        shadow_verify_node_collectors(path, root, scope_index, collectors)
       end
 
       def call_node_diagnostics(path, node, scope_index)
@@ -252,8 +337,8 @@ module Rigor
       #   Class-level ivars (`@x = 1` outside any def, in the
       #   class body) are also skipped — they're a separate
       #   surface (`Module#@var`) the engine doesn't yet model.
-      def ivar_write_mismatch_diagnostics(path, root, scope_index)
-        IvarWriteCollector.new(scope_index).collect(root).flat_map do |class_name, writes_by_ivar|
+      def ivar_write_mismatch_diagnostics(path, ivar_writes)
+        ivar_writes.flat_map do |class_name, writes_by_ivar|
           writes_by_ivar.flat_map do |ivar_name, writes|
             ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
           end
@@ -266,8 +351,8 @@ module Rigor
       # read in the same body. The
       # `Analysis::CheckRules::DeadAssignmentCollector` describes
       # the conservative envelope.
-      def dead_assignment_diagnostics(path, root, scope_index)
-        DeadAssignmentCollector.new(scope_index).collect(root).map do |result|
+      def dead_assignment_diagnostics(path, dead_assignments)
+        dead_assignments.map do |result|
           build_dead_assignment_diagnostic(path, result[:write_node], result[:def_node])
         end
       end
@@ -421,9 +506,24 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
-          receiver_type = scope.type_of(call_node.receiver)
+          # N3 — a safe-navigation call (`recv&.m`) never dispatches on the
+          # nil edge of its receiver: at runtime it short-circuits to nil.
+          # A receiver that types as exactly `nil` yields nil with no call at
+          # all, so it is silent (no dead-code diagnostic — `&.` is the
+          # nil-skip operator by design, and frightening working
+          # `@x = nil; @x&.m` code would breach FP discipline). A nil-bearing
+          # *union* receiver is left to flow through unchanged: a `T | nil`
+          # union has no single concrete class, so the rule already bails
+          # 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)
           class_name = concrete_class_name(receiver_type)
-          return nil if class_name.nil?
+          # A union receiver has no single concrete class. The scalar path
+          # below cannot reason about it, but the call is still definitely
+          # undefined when EVERY arm lacks the method — see
+          # `union_undefined_method_diagnostic`.
+          return union_undefined_method_diagnostic(path, call_node, receiver_type, scope) if class_name.nil?
 
           # ADR-26 — a plugin may declare a class "open": one
           # known to respond beyond its RBS-declared method
@@ -602,6 +702,20 @@ module Rigor
           when Type::Tuple then "Array"
           when Type::HashShape then "Hash"
           when Type::Constant then constant_class_name(type.value)
+          # A refinement IS its base class for method dispatch — its method
+          # surface is the base's. Resolve to the base so the call rules
+          # (undefined-method / wrong-arity / argument-type-mismatch) reason
+          # about it instead of bailing. `Type::Refined` carries string-family
+          # refinements (`lowercase-string`, …) over an explicit `.base`;
+          # `Type::IntegerRange` carries the bounded-int refinements
+          # (`non-negative-int`, `positive-int`, `int<1,5>`), every one an
+          # Integer; `Type::Difference` (`A - B`) carries the non-empty /
+          # non-zero refinements (`non-empty-string` = `String - ""`,
+          # `non-empty-array` = `Array - []`, `non-zero-int` = `Integer - 0`)
+          # — subtracting values never changes the method surface, so the
+          # base (minuend) class dispatches.
+          when Type::Refined, Type::Difference then concrete_class_name(type.base)
+          when Type::IntegerRange then "Integer"
           end
         end
 
@@ -678,12 +792,90 @@ module Rigor
             scope = scope_index[miss.node]
             next if scope.nil?
             next unless confidently_closed_self_class?(miss.class_name, scope)
+            next if method_defined_on_known_subclass?(miss.class_name, miss.method_name, scope)
 
             build_self_undefined_method_diagnostic(path, miss)
           end
         end
 
+        # ADR-24 slice 4 — subclass-aware gating (the abstract / template-method
+        # base-class false positive the WD4 corpus eval surfaced). A base class
+        # legitimately calls a method its subclasses implement
+        # (`Mail::CommonField#decoded` calls `do_decode`, which
+        # `Mail::UnstructuredField < CommonField` and its siblings define; the
+        # same shape covers `Mail::Retriever#find` → POP3 / IMAP). When the
+        # missed method is discovered on ANY known subclass of the self-class,
+        # the call is a template-method hook, not a typo — suppress. Walks the
+        # project subclass closure (the `discovered_superclasses` child→parent
+        # map inverted, cycle-guarded). A pure narrowing — it only ever
+        # suppresses a firing the closed-class gate would otherwise emit.
+        def method_defined_on_known_subclass?(class_name, method_name, scope)
+          supers = scope.discovered_superclasses
+          seen = {}
+          queue = direct_subclasses(class_name, supers)
+          until queue.empty?
+            subclass = queue.shift
+            next if seen[subclass]
+
+            seen[subclass] = true
+            return true if method_known_on_class?(subclass, method_name, scope)
+
+            queue.concat(direct_subclasses(subclass, supers))
+          end
+          false
+        end
+
+        # The directly-recorded subclasses of `class_name`. `discovered_superclasses`
+        # keys the child fully-qualified (`Mail::POP3`) but records the parent
+        # *as written* (`Retriever`), so a qualified miss class (`Mail::Retriever`)
+        # is matched by resolving the parent name in the child's namespace.
+        def direct_subclasses(class_name, discovered_superclasses)
+          discovered_superclasses.filter_map { |child, parent| child if parent_matches?(child, parent, class_name) }
+        end
+
+        # Ruby constant lookup: a recorded parent `Retriever` on child
+        # `Mail::POP3` resolves to `Mail::Retriever` (walk the child's namespace
+        # prefixes, longest first), matched against the miss's fully-qualified
+        # class name. Namespace-anchored, so it cannot match a same-named base in
+        # an unrelated namespace.
+        def parent_matches?(child, parent, class_name)
+          parent_name = parent.to_s
+          return true if parent_name == class_name
+
+          segments = child.to_s.split("::")[0...-1]
+          until segments.empty?
+            return true if "#{segments.join('::')}::#{parent_name}" == class_name
+
+            segments.pop
+          end
+          false
+        end
+
+        # Whether `method_name` is defined on `class_name` in the project — a
+        # plain `def` (the def-node table) or a dynamic definition
+        # (`define_method` / `attr_*` / `alias`). `discovered_method?` alone
+        # misses plain defs, which is exactly what the abstract hooks are.
+        def method_known_on_class?(class_name, method_name, scope)
+          !scope.user_def_for(class_name, method_name).nil? ||
+            scope.discovered_method?(class_name, method_name, :instance)
+        end
+
+        # ADR-24 slice 4 — the universal bases. A recorded self-call miss tagged
+        # with one of these means the engine fell back to the root self-type
+        # because it could NOT resolve the real class (a class-body macro context
+        # where self is the Class object, top-level `main`, `instance_eval`, an
+        # FFI / `define_method` metaprogramming surface). Their instance method
+        # set is never "project-known and complete" — every object also responds
+        # to whatever the unresolved real class adds — so a miss there is a
+        # resolution gap, not a typo. This is the dominant false-positive class
+        # the WD4 corpus eval surfaced (protobuf 73 / tdiary 199 / pycall 10 /
+        # … FFI + class-macro calls, 287 firings across the corpus); excluding
+        # it is a pure narrowing.
+        SELF_UNDEFINED_UNIVERSAL_BASES = %w[Object BasicObject Kernel].to_set.freeze
+        private_constant :SELF_UNDEFINED_UNIVERSAL_BASES
+
         def confidently_closed_self_class?(class_name, scope)
+          return false if SELF_UNDEFINED_UNIVERSAL_BASES.include?(class_name)
           return false if unbounded_receiver_surface?(class_name, scope)
           return false if scope.discovered_method?(class_name, :method_missing, :instance)
           # A superclass or mixin extends the surface beyond what this file
@@ -742,7 +934,7 @@ module Rigor
         # by `undefined_method_diagnostic`; it returns nil
         # when the call's receiver / RBS coverage / call shape
         # disqualifies the rule.
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
         def wrong_arity_diagnostic(path, call_node, scope_index)
           return nil if call_node.receiver.nil?
           return nil unless plain_positional_call?(call_node)
@@ -755,6 +947,15 @@ module Rigor
           return nil if class_name.nil?
 
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+          # `Struct.new(:a, :b).new(...)` chained: the inner
+          # `Struct.new(...)` is an anonymous Struct *subclass* whose
+          # `.new` accepts any positional arity (one slot per member,
+          # all defaulting to nil) — including zero. The receiver types
+          # as `Singleton[Struct]` (so the call-site `.new` dispatches,
+          # per the dispatcher's `struct_new_lift`), but validating that
+          # `.new` against the real `Struct.new(*Symbol)` signature is a
+          # false positive. Skip arity-checking the chained position.
+          return nil if anonymous_struct_new_call?(call_node, class_name, kind)
           return nil if scope.discovered_method?(class_name, call_node.name, kind)
 
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
@@ -772,7 +973,25 @@ module Rigor
 
           build_arity_diagnostic(path, call_node, class_name, min, max, actual)
         end
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+
+        # True for the outer `.new` of a chained `Struct.new(...).new`:
+        # `class_name`/`kind` already pin the receiver to
+        # `Singleton[Struct]`, and the receiver node is itself a
+        # `Struct.new` (or `::Struct.new`) call — the anonymous subclass.
+        def anonymous_struct_new_call?(call_node, class_name, kind)
+          return false unless class_name == "Struct" && kind == :singleton
+          return false unless call_node.name == :new
+
+          receiver = call_node.receiver
+          return false unless receiver.is_a?(Prism::CallNode) && receiver.name == :new
+
+          inner = receiver.receiver
+          return true if inner.is_a?(Prism::ConstantReadNode) && inner.name == :Struct
+
+          # `::Struct.new(...).new` — a top-level constant path.
+          inner.is_a?(Prism::ConstantPathNode) && inner.parent.nil? && inner.name == :Struct
+        end
 
         def plain_positional_call?(call_node)
           arguments = call_node.arguments
@@ -864,6 +1083,17 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
+          # ADR-58 WD1 — a receiver whose `nil` constituent is purely
+          # declaration-sourced (the class-ivar index seed of a ctor
+          # `@x = nil` written in another method, possibly copied into a
+          # local via `r = @right`) does not fire by default: the working
+          # program's cross-method invariant is assumed per the robustness
+          # principle. The nil stays in the displayed type; only its use as
+          # diagnostic fuel is withheld. Any flow-live touch (method-local
+          # nil write, failed-guard narrowing) drops the mark upstream, so
+          # flow-observed nil keeps firing exactly as before.
+          return nil if scope.declaration_sourced?(:local, call_node.receiver.name)
+
           receiver_type = scope.type_of(call_node.receiver)
           return nil unless receiver_type.is_a?(Type::Union)
 
@@ -883,6 +1113,21 @@ module Rigor
           union.members.any? { |member| nil_member?(member) }
         end
 
+        # The receiver type the `call.undefined-method` existence check
+        # should reason about. For a safe-navigation call whose receiver
+        # types as exactly `nil`, this is `Type::Bot` — the call is
+        # statically skipped at runtime, and `concrete_class_name(Bot)` is
+        # 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)
+          return receiver_type unless call_node.safe_navigation?
+          return receiver_type unless nil_member?(receiver_type)
+
+          Type::Combinator.bot
+        end
+
         def nil_member?(member)
           (member.is_a?(Type::Constant) && member.value.nil?) ||
             (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
@@ -919,6 +1164,71 @@ module Rigor
           !definition.methods[method_name.to_sym].nil?
         end
 
+        # Teeth on a *union* receiver. The scalar `undefined_method_diagnostic`
+        # bails when the receiver has no single concrete class; here we fire
+        # when EVERY non-nil arm is a fully-known, bounded, instance class on
+        # which the method is absent — the call is then undefined regardless of
+        # which arm the value takes at runtime (`A | B` responds to `m` only if
+        # both `A` and `B` do). FP-safe by construction: `method_present_anywhere?`
+        # returns "present" for any Dynamic / unknown / unbuildable /
+        # source-declared arm, so the `any?` short-circuits and we never fire on
+        # uncertainty; `union_arm_blocks_undefined_fire?` additionally bails on
+        # any open (ADR-26) / synthesized / singleton / module-mixin arm. This is
+        # no more aggressive than the scalar rule — it just applies the same
+        # certainty test to each arm.
+        #
+        # Nil-bearing unions are deferred: their nil arm interacts with the
+        # `possible-nil-receiver` rule, safe-navigation, and ADR-58
+        # declaration-sourced nil. Slice 1 handles pure non-nil unions
+        # (e.g. `String | Symbol`).
+        def union_undefined_method_diagnostic(path, call_node, receiver_type, scope)
+          return nil unless receiver_type.is_a?(Type::Union)
+          return nil if call_node.safe_navigation?
+
+          members = receiver_type.members
+          # Nil-bearing unions (`T | nil`) stay silent — the deliberate N3
+          # decision (`safe_navigation_undefined_method_spec.rb`). A corpus FP
+          # study of a bundled-arm-narrowed candidate (12 projects incl.
+          # ActiveSupport-heavy) found ~zero real firings yet a demonstrated
+          # loss-of-specificity false positive, so the silence is kept. See
+          # ADR-62 and `docs/notes/20260613-mutation-teeth-harness.md`.
+          return nil if members.any? { |member| nil_member?(member) }
+          return nil if members.any? { |member| union_arm_blocks_undefined_fire?(member, scope) }
+          # Only a genuinely multi-class union ("the value is an A or a B") gains
+          # from this rule. A union whose arms all resolve to ONE class
+          # (`Hash[K1, V1] | Hash[K2, V2]`) is a shape-join artifact — checking
+          # method existence there is the scalar rule's job, and when the join is
+          # a misinference it is a false positive (a corpus probe caught mail's
+          # `compose_codepoints` typed `Hash | Hash` for an `Array`, flagging
+          # `.pack`). Require at least two distinct arm classes.
+          return nil if members.map { |member| concrete_class_name(member) }.uniq.size < 2
+          return nil if members.any? { |member| method_present_anywhere?(member, call_node.name, scope) }
+
+          build_undefined_method_diagnostic(path, call_node, receiver_type)
+        end
+
+        # An arm that makes a sound "undefined on every arm" verdict
+        # impossible: a non-class surface (Dynamic / Top / Bot), a singleton
+        # (slice 1 reasons about instance arms only), the generic metaclass
+        # `Class` / `Module` (a value typed as one is *some* class/module object
+        # whose singleton methods cannot be enumerated from the metaclass — e.g.
+        # `plugin_class : Class` really holds a `Plugin` subclass with
+        # `.manifest`), an unbounded receiver (ADR-26 open class or a synthesized
+        # stub), or a module mixin whose Object-inherited methods the per-arm
+        # lookup would miss.
+        METACLASS_ARMS = %w[Class Module].to_set.freeze
+        private_constant :METACLASS_ARMS
+
+        def union_arm_blocks_undefined_fire?(member, scope)
+          class_name = concrete_class_name(member)
+          return true if class_name.nil?
+          return true if member.is_a?(Type::Singleton)
+          return true if METACLASS_ARMS.include?(class_name)
+          return true if unbounded_receiver_surface?(class_name, scope)
+
+          module_mixin_receiver?(member, scope)
+        end
+
         # Slice 7 phase 19 — PHPStan-style `dump_type(value)`.
         # When the engine recognises a call to `dump_type` (with
         # any of the supported receiver shapes — implicit self
@@ -1011,27 +1321,12 @@ module Rigor
           receiver = call_node.receiver
           return true if receiver.nil?
 
-          name = constant_name_of(receiver)
+          name = Source::ConstantPath.qualified_name_or_nil(receiver)
           return false if name.nil?
 
           RIGOR_TESTING_RECEIVERS.include?(name)
         end
 
-        def constant_name_of(node)
-          case node
-          when Prism::ConstantReadNode then node.name.to_s
-          when Prism::ConstantPathNode then render_constant_path(node)
-          end
-        end
-
-        def render_constant_path(node)
-          parent = node.parent
-          base = constant_name_of(parent)
-          return nil if parent && base.nil?
-
-          parent ? "#{base}::#{node.name}" : node.name.to_s
-        end
-
         def build_assert_type_diagnostic(path, call_node, expected, actual)
           Diagnostic.from_message_loc(
             call_node,
@@ -1048,7 +1343,8 @@ module Rigor
             rule: RULE_NIL_RECEIVER,
             path: path,
             message: "possible nil receiver: `#{call_node.name}' is undefined on NilClass",
-            severity: :error
+            severity: :error,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1236,7 +1532,9 @@ module Rigor
             rule: RULE_VISIBILITY_MISMATCH,
             path: path,
             message: "private method `#{call_node.name}' called on #{receiver_type.class_name} receiver",
-            severity: :error
+            severity: :error,
+            receiver_type: receiver_type.class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1382,6 +1680,21 @@ module Rigor
         UNIVERSAL_EQUALITY_METHODS = %i[== != eql? equal? <=>].to_set.freeze
         private_constant :UNIVERSAL_EQUALITY_METHODS
 
+        # ADR-64 WD1 — the binary arithmetic / bit / ordering operators
+        # dispatch through Ruby's `coerce` protocol (and `<=>` for the
+        # comparisons): `5 + Money.new` is valid at runtime because
+        # `Integer#+` calls `Money#coerce(5)`, even though no RBS `Integer#+`
+        # overload lists `Money`. A non-`Numeric` argument to them is therefore
+        # NOT statically refutable — any user type may define `coerce` — so the
+        # *non-nil* argument-type-mismatch channel excludes them (a fixed
+        # allow-list, modelled on {UNIVERSAL_EQUALITY_METHODS}, not `coerce`
+        # detection). `nil` never coerces, so the nil channel stays in force
+        # here; the exclusion applies to the non-nil case only. `<=>` and the
+        # `==` family are already excluded wholesale by
+        # {UNIVERSAL_EQUALITY_METHODS}.
+        COERCE_DISPATCH_METHODS = %i[+ - * / % ** & | ^ << >> < > <= >=].to_set.freeze
+        private_constant :COERCE_DISPATCH_METHODS
+
         def argument_type_diagnostic(path, call_node, scope_index)
           return nil if call_node.receiver.nil?
           return nil if UNIVERSAL_EQUALITY_METHODS.include?(call_node.name)
@@ -1405,15 +1718,266 @@ module Rigor
 
           method_def = lookup_method(receiver_type, class_name, call_node.name, scope)
           return nil if method_def.nil? || method_def == true
-          return nil unless method_def.method_types.size == 1
 
           param_overrides = Rigor::RbsExtended.param_type_override_map(method_def, environment: scope.environment)
-          mismatch = first_argument_mismatch(method_def.method_types.first, call_node, scope, param_overrides)
+          mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides)
           return nil if mismatch.nil?
 
           build_argument_type_diagnostic(path, call_node, class_name, mismatch)
         end
 
+        # Single overload → the exact per-argument acceptance (unchanged).
+        # Multiple overloads → the nil channel (a pure-`nil` argument every
+        # overload rejects) plus, on non-coerce methods, the non-nil channel
+        # (a single-concrete-class argument every overload rejects). See
+        # {#multi_overload_argument_mismatch}.
+        def argument_mismatch(method_types, call_node, scope, param_overrides)
+          if method_types.size == 1
+            first_argument_mismatch(method_types.first, call_node, scope, param_overrides)
+          else
+            multi_overload_argument_mismatch(method_types, call_node, scope, param_overrides)
+          end
+        end
+
+        # Multi-overload argument-type-mismatch. The dispatcher's per-overload
+        # acceptance plumbing is not run here; instead the FP-safe shape mirrors
+        # the "absent on every arm" union-undefined-method rule: an argument is
+        # a mismatch only when EVERY overload's matching positional param
+        # rejects it.
+        #
+        # Two channels, both gated on a positively-refuted argument:
+        # - **nil** (any method): a pure `nil` no overload admits is a
+        #   guaranteed `TypeError` — `nil` never coerces.
+        # - **non-nil** (ADR-64, non-coerce methods only): an argument that
+        #   types to a single concrete RBS-known class that no overload admits.
+        #   Excludes {COERCE_DISPATCH_METHODS} (`5 + Money.new` is valid via
+        #   `coerce`), restricts to a single concrete class (WD3 — a union arg
+        #   stays deferred), and decides acceptance on the RBS param type
+        #   ({#param_accepts_arg_class?}) so it sees through the `int` / `string`
+        #   interface-aliases the translator degrades.
+        def multi_overload_argument_mismatch(method_types, call_node, scope, param_overrides)
+          functions = method_types.map(&:type)
+          return nil unless functions.all? { |function| argument_check_eligible?(function) }
+
+          coerce_method = COERCE_DISPATCH_METHODS.include?(call_node.name)
+          arguments = call_node.arguments&.arguments || []
+          arguments.each_with_index do |arg, index|
+            arg_type = scope.type_of(arg)
+            params = overload_positional_params(functions, index)
+            next if params.nil? # arity divergence — some overload lacks a param here
+
+            mismatch =
+              if nil_member?(arg_type) # pure nil only — not a `T | nil` union
+                nil_arg_overload_mismatch(arg, arg_type, params, param_overrides, scope)
+              elsif !coerce_method
+                non_nil_arg_overload_mismatch(arg, arg_type, params, param_overrides, scope)
+              end
+            return mismatch if mismatch
+          end
+          nil
+        end
+
+        # The nil channel: a pure `nil` argument no overload admits (ADR-58
+        # parity excuses a declaration-sourced ivar nil).
+        def nil_arg_overload_mismatch(arg, arg_type, params, param_overrides, scope)
+          return nil if declaration_sourced_nil_argument?(arg, scope)
+          return nil if params.any? { |param| param_admits_nil?(param, param_overrides, scope) }
+
+          { node: arg, name: nil, expected: overload_param_expected_label(params), actual: arg_type }
+        end
+
+        # 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 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
+
+        # 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).
+        def overload_positional_params(functions, index)
+          params = functions.map { |function| (function.required_positionals + function.optional_positionals)[index] }
+          params.any?(&:nil?) ? nil : params
+        end
+
+        # The class names whose instances `nil` IS — `NilClass` and every
+        # ancestor. A parameter typed as any other class instance rejects nil.
+        NIL_COMPATIBLE_CLASS_NAMES = %w[NilClass Object BasicObject Kernel].to_set.freeze
+        private_constant :NIL_COMPATIBLE_CLASS_NAMES
+
+        # Does this parameter admit a `nil` argument? Decided on the RBS
+        # parameter type (a `rigor:v1:param` override takes precedence).
+        # Conservative throughout: any case we cannot decide returns true
+        # (admits → do not fire), so the rule never fires on uncertainty.
+        def param_admits_nil?(param, param_overrides, scope)
+          override = param_overrides[param.name]
+          return rigor_type_admits_nil?(override) if override
+
+          rbs_type_admits_nil?(param.type, scope)
+        end
+
+        # The `rigor:v1:param` override variant — a refinement
+        # (`non-empty-string`) rejects nil; an explicit nil / nilable union /
+        # gradual override admits it.
+        def rigor_type_admits_nil?(type)
+          return true if type.is_a?(Type::Dynamic) || type.is_a?(Type::Top)
+          return true if nil_member?(type)
+          return union_contains_nil?(type) if type.is_a?(Type::Union)
+
+          false
+        end
+
+        # Walks the RBS parameter type. The load-bearing cases are `Alias`
+        # (`string` = `String | _ToStr`) and `Interface` (`_ToStr`), which
+        # {Inference::RbsTypeTranslator} degrades to `untyped` — the reason a
+        # `nil` argument is invisible after translation (the interface-alias
+        # gap). Resolving them here recovers the rejection. Only a concrete
+        # class instance that is not a `nil` ancestor, and an interface
+        # NilClass does not satisfy, return false; everything else admits.
+        def rbs_type_admits_nil?(rbs_type, scope)
+          case rbs_type
+          when RBS::Types::Union then rbs_type.types.any? { |member| rbs_type_admits_nil?(member, scope) }
+          when RBS::Types::Alias
+            expanded = scope.environment&.rbs_loader&.expand_type_alias(rbs_type)
+            expanded.nil? || rbs_type_admits_nil?(expanded, scope)
+          when RBS::Types::ClassInstance
+            NIL_COMPATIBLE_CLASS_NAMES.include?(rbs_type.name.to_s.delete_prefix("::"))
+          when RBS::Types::Interface then interface_admits_nil?(rbs_type, scope)
+          else true # Optional / bases / variable / tuple / record / proc / literal / intersection → conservative admit
+          end
+        end
+
+        # An interface parameter (`_ToStr`) admits nil only when NilClass
+        # implements every method it requires (`to_str`, `to_int`, … — which
+        # NilClass does not, so `string` / `int` params reject nil; a
+        # hypothetical `_ToS` would admit, since NilClass#to_s exists).
+        # Unresolvable → conservative true.
+        def interface_admits_nil?(rbs_type, scope)
+          loader = scope.environment&.rbs_loader
+          return true if loader.nil?
+
+          methods = loader.interface_method_names(rbs_type.name.to_s)
+          return true if methods.nil? || methods.empty?
+
+          methods.all? { |method_name| nil_class_has_method?(method_name, scope) }
+        end
+
+        # ADR-64 WD3 — the non-nil channel fires only on an argument that types
+        # to a single concrete, RBS-known class. A union arg mirrors the
+        # union-receiver story and stays deferred; a class/module object
+        # (`Singleton`) has a special acceptance surface and is skipped; a
+        # non-RBS project class is skipped because its conversion protocol (a
+        # duck-typed `to_int` / `to_str`) is invisible to us, so we cannot
+        # refute acceptance.
+        def single_concrete_arg_class?(arg_type, scope)
+          return false if arg_type.is_a?(Type::Union)
+          return false if arg_type.is_a?(Type::Singleton)
+
+          class_name = concrete_class_name(arg_type)
+          return false if class_name.nil?
+
+          Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+        end
+
+        # ADR-64 WD2 — does this parameter accept the (non-nil) argument?
+        # The non-nil generalization of {#param_admits_nil?}: decided on the RBS
+        # parameter type (a `rigor:v1:param` override takes precedence) so it
+        # sees through the `int` / `string` interface-aliases the translator
+        # degrades to gradual. Conservative throughout — any case we cannot
+        # decide returns true (accepts → do not fire).
+        def param_accepts_arg_class?(param, arg_type, param_overrides, scope)
+          override = param_overrides[param.name]
+          return rigor_type_accepts_arg?(override, arg_type) if override
+
+          rbs_type_accepts_arg?(param.type, arg_type, scope)
+        end
+
+        # The `rigor:v1:param` override variant — a Rigor `Type`, so the
+        # acceptance engine decides directly (gradual; only a proven rejection
+        # refutes). Dynamic / Top admit unconditionally.
+        def rigor_type_accepts_arg?(param_type, arg_type)
+          return true if param_type.is_a?(Type::Dynamic) || param_type.is_a?(Type::Top)
+
+          !Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual).no?
+        end
+
+        # Walks the RBS parameter type, mirroring {#rbs_type_admits_nil?}. The
+        # load-bearing cases are `Alias` / `Interface` (`int` = `Integer |
+        # _ToInt`), which the translator degrades to gradual — resolving them
+        # here recovers the rejection. A faithfully-translated `ClassInstance`
+        # is handed to the acceptance engine; everything undecidable admits.
+        def rbs_type_accepts_arg?(rbs_type, arg_type, scope)
+          case rbs_type
+          when RBS::Types::Union then rbs_type.types.any? { |member| rbs_type_accepts_arg?(member, arg_type, scope) }
+          when RBS::Types::Alias
+            expanded = scope.environment&.rbs_loader&.expand_type_alias(rbs_type)
+            expanded.nil? || rbs_type_accepts_arg?(expanded, arg_type, scope)
+          when RBS::Types::ClassInstance then class_instance_accepts_arg?(rbs_type, arg_type, scope)
+          when RBS::Types::Interface then interface_accepts_arg?(rbs_type, arg_type, scope)
+          else true # bases / variable / tuple / record / proc / literal / intersection / optional → conservative admit
+          end
+        end
+
+        # A `ClassInstance` param (`Integer`, `Numeric`, …) is translated
+        # faithfully (no interface degradation), so the acceptance engine — the
+        # canonical RBS-ancestry / generic-aware subtype check — decides it.
+        # Only a proven rejection refutes; an unresolvable class is `:maybe`,
+        # which admits.
+        def class_instance_accepts_arg?(rbs_type, arg_type, scope)
+          translated = translate_param_type(rbs_type, scope.environment)
+          return true if translated.is_a?(Type::Dynamic) || translated.is_a?(Type::Top)
+
+          !Inference::Acceptance.accepts(translated, arg_type, mode: :gradual).no?
+        end
+
+        # An interface param (`_ToInt`) accepts the arg only when the arg's
+        # class implements every method it requires (`to_int`, …). The non-nil
+        # mirror of {#interface_admits_nil?}: ask the arg class, not NilClass.
+        # Unresolvable anywhere → conservative true (admit).
+        def interface_accepts_arg?(rbs_type, arg_type, scope)
+          loader = scope.environment&.rbs_loader
+          return true if loader.nil?
+
+          methods = loader.interface_method_names(rbs_type.name.to_s)
+          return true if methods.nil? || methods.empty?
+
+          class_name = concrete_class_name(arg_type)
+          return true if class_name.nil?
+
+          methods.all? { |method_name| arg_class_has_method?(class_name, method_name, scope) }
+        end
+
+        # The non-nil mirror of {#nil_class_has_method?}, but conservative on
+        # the unknown side: an unresolvable definition returns true (the class
+        # *might* implement the method — e.g. a metaprogrammed conversion), so
+        # the channel never fires on uncertainty.
+        def arg_class_has_method?(class_name, method_name, scope)
+          definition = Rigor::Reflection.instance_definition(class_name, scope: scope)
+          return true if definition.nil?
+
+          !definition.methods[method_name.to_sym].nil?
+        end
+
+        # A readable "expected" label for a multi-overload mismatch — the RBS
+        # parameter type(s) as written (`string`, or the per-overload set), since
+        # the translated Rigor type degrades the interface-alias the rejection
+        # hinges on. Shared by the nil and non-nil channels.
+        def overload_param_expected_label(params)
+          params.map { |param| param.type.to_s.delete_prefix("::") }.uniq.join(" | ")
+        end
+
+        # ADR-58 parity for the nil channel: a declaration-sourced ivar read
+        # that types as nil is the same not-diagnostic-fuel case the union
+        # path gates in {#declaration_sourced_nil_only_mismatch?}; suppress it
+        # here too so a ctor-seeded `@x = nil` read passed as an argument does
+        # not fire on a working program's cross-method invariant.
+        def declaration_sourced_nil_argument?(arg, scope)
+          arg.is_a?(Prism::InstanceVariableReadNode) && scope.declaration_sourced?(:ivar, arg.name)
+        end
+
         def first_argument_mismatch(method_type, call_node, scope, param_overrides)
           function = method_type.type
           return nil unless argument_check_eligible?(function)
@@ -1424,21 +1988,71 @@ module Rigor
             param = params[index]
             next if param.nil? # arity mismatch is the wrong-arity rule's concern.
 
-            # `rigor:v1:param: <name> <refinement>` annotations
-            # tighten the RBS-declared parameter type. The
-            # override is the authoritative contract when
-            # present; otherwise we translate the RBS type as
-            # before.
-            param_type = param_overrides[param.name] || translate_param_type(param.type, scope.environment)
-            next if param_type.is_a?(Type::Dynamic) || param_type.is_a?(Type::Top)
+            mismatch = single_argument_mismatch(param, arg, scope, param_overrides)
+            return mismatch if mismatch
+          end
+          nil
+        end
 
-            arg_type = scope.type_of(arg)
-            next if arg_type.is_a?(Type::Dynamic) || arg_type.is_a?(Type::Top)
+        # The mismatch (or nil) for one positional argument against one
+        # parameter. The nil channel decides a pure `nil` argument on the RBS
+        # parameter type — seeing through the `string` / `int` interface-alias
+        # the translator degrades to gradual (so `"a" + nil` fires), excusing a
+        # declaration-sourced ivar nil (ADR-58 parity). The non-nil channel is
+        # the original translated-acceptance check, with a `rigor:v1:param`
+        # override taking precedence over the RBS-declared type.
+        def single_argument_mismatch(param, arg, scope, param_overrides)
+          arg_type = scope.type_of(arg)
+
+          if nil_member?(arg_type)
+            return nil if declaration_sourced_nil_argument?(arg, scope)
+            return nil if param_admits_nil?(param, param_overrides, scope)
 
-            result = Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual)
-            return { node: arg, name: param.name, expected: param_type, actual: arg_type } if result.no?
+            return { node: arg, name: param.name, expected: overload_param_expected_label([param]), actual: arg_type }
           end
-          nil
+
+          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 unless argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
+
+          { node: arg, name: param.name, expected: param_type, actual: arg_type }
+        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?
+
+          # ADR-58 (N2 extension) — the same declaration-sourced-nil-is-not-
+          # diagnostic-fuel criterion that governs `possible-nil-receiver`
+          # applies here. When the only reason the argument is rejected is a
+          # *declaration-sourced* nil constituent (the class-ivar index seed
+          # of a ctor `@x = nil` / a non-definitely-assigned ivar read), and
+          # the argument type with that nil removed WOULD be accepted, the
+          # working program's cross-method invariant is assumed and we do not
+          # fire. Flow-live nil (a method-local `@x = nil` write, a failed-
+          # guard narrowing) drops the provenance mark upstream and still
+          # fires. The argument's type is unchanged — only the firing
+          # decision is gated.
+          !declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
+        end
+
+        # True when `arg` is a declaration-sourced ivar 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
+        # `possible-nil-receiver` WD1 gate, keyed on the ivar provenance mark
+        # rather than a local copy.
+        def declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
+          return false unless arg.is_a?(Prism::InstanceVariableReadNode)
+          return false unless scope.declaration_sourced?(:ivar, arg.name)
+          return false unless arg_type.is_a?(Type::Union)
+          return false unless union_contains_nil?(arg_type)
+
+          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?
         end
 
         def argument_check_eligible?(function)
@@ -1463,15 +2077,19 @@ module Rigor
         def build_argument_type_diagnostic(path, call_node, class_name, mismatch)
           method_label = "`#{call_node.name}' on #{class_name}"
           parameter_label = mismatch[:name] ? "parameter `#{mismatch[:name]}' of #{method_label}" : method_label
+          expected = mismatch[:expected]
+          expected_description = expected.is_a?(String) ? expected : expected.describe(:short)
           message = "argument type mismatch at #{parameter_label}: " \
-                    "expected #{mismatch[:expected].describe(:short)}, " \
+                    "expected #{expected_description}, " \
                     "got #{mismatch[:actual].describe(:short)}"
           Diagnostic.from_node(
             mismatch[:node],
             rule: RULE_ARGUMENT_TYPE,
             path: path,
             message: message,
-            severity: :error
+            severity: :error,
+            receiver_type: class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1484,7 +2102,9 @@ module Rigor
             rule: RULE_WRONG_ARITY,
             path: path,
             message: message,
-            severity: :error
+            severity: :error,
+            receiver_type: class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1657,7 +2277,8 @@ module Rigor
             path: path,
             message: "return-type mismatch on `#{def_node.name}': " \
                      "declared #{declared.describe(:short)}, inferred #{inferred.describe(:short)}",
-            severity: severity
+            severity: severity,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1809,7 +2430,8 @@ module Rigor
             message: "visibility of `#{def_node.name}' reduced from #{parent_visibility} to " \
                      "#{override_visibility} (overrides #{parent_class}##{def_node.name}); " \
                      "breaks substitutability",
-            severity: :warning
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1833,7 +2455,14 @@ module Rigor
         # everything, so they stay silent (FP-safe). `self`/`instance`
         # are translated with `self_type: nil` on both sides, so a
         # parent `-> self` and an override `-> self` never fire.
-        def override_return_widened_diagnostic(path, def_node, scope_index)
+        # The authored-override resolution shared by the Liskov override
+        # rules (`def.override-return-widened` and
+        # `def.override-param-narrowed`): the def must be an instance method
+        # whose own class declares it in RBS, and a project-discovered
+        # ancestor must also declare it. Returns
+        # `[scope, override_method, parent_class, parent_method]`, or nil
+        # (the rule does not fire) when any gate is unmet.
+        def resolve_authored_override(def_node, scope_index)
           return nil unless def_node.receiver.nil? # instance methods only (singleton: follow-on)
 
           scope = scope_index[def_node]
@@ -1853,6 +2482,14 @@ module Rigor
           return nil if parent.nil?
 
           parent_class, parent_method = parent
+          [scope, override_method, parent_class, parent_method]
+        end
+
+        def override_return_widened_diagnostic(path, def_node, scope_index)
+          resolved = resolve_authored_override(def_node, scope_index)
+          return nil if resolved.nil?
+
+          scope, override_method, parent_class, parent_method = resolved
           override_return = declared_return_union(override_method, scope.environment)
           parent_return = declared_return_union(parent_method, scope.environment)
           return nil if override_return.nil? || parent_return.nil?
@@ -1902,7 +2539,8 @@ module Rigor
             message: "return type of `#{def_node.name}' widened from #{parent_return.describe(:short)} " \
                      "to #{override_return.describe(:short)} (overrides #{parent_class}##{def_node.name}); " \
                      "breaks substitutability",
-            severity: :warning
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1924,25 +2562,10 @@ module Rigor
         # overload-arm ambiguity, both sides must have exactly one
         # method type.
         def override_param_narrowed_diagnostic(path, def_node, scope_index)
-          return nil unless def_node.receiver.nil? # instance methods only
-
-          scope = scope_index[def_node]
-          return nil if scope.nil?
-
-          self_type = scope.self_type
-          return nil unless self_type.respond_to?(:class_name)
-
-          class_name = self_type.class_name.to_s
-          method_name = def_node.name
+          resolved = resolve_authored_override(def_node, scope_index)
+          return nil if resolved.nil?
 
-          override_method = safe_instance_method_definition(class_name, method_name, scope)
-          return nil if override_method.nil?
-          return nil unless defined_on?(override_method, class_name)
-
-          parent = nearest_ancestor_method_def(scope, class_name, method_name)
-          return nil if parent.nil?
-
-          parent_class, parent_method = parent
+          _scope, override_method, parent_class, parent_method = resolved
           override_params = positional_param_types(override_method)
           parent_params = positional_param_types(parent_method)
           return nil if override_params.nil? || parent_params.nil?
@@ -2006,7 +2629,8 @@ module Rigor
             message: "parameter #{index + 1} of `#{def_node.name}' narrowed from " \
                      "#{parent_param.describe(:short)} to #{override_param.describe(:short)} " \
                      "(overrides #{parent_class}##{def_node.name}); breaks substitutability",
-            severity: :warning
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
       end