rigortype 0.1.19 → 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"
@@ -17,37 +18,30 @@ 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 §
@@ -525,7 +519,11 @@ module Rigor
           # 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
@@ -704,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
 
@@ -780,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
@@ -1074,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
@@ -1166,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,
@@ -1540,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)
@@ -1563,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)
@@ -1582,22 +1988,35 @@ 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)
 
-            next unless argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
+          if nil_member?(arg_type)
+            return nil if declaration_sourced_nil_argument?(arg, scope)
+            return nil if param_admits_nil?(param, param_overrides, scope)
 
-            return { node: arg, name: param.name, expected: param_type, actual: arg_type }
+            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
@@ -1658,8 +2077,10 @@ 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],
@@ -2034,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]
@@ -2054,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?
@@ -2126,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
-
-          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?
+          resolved = resolve_authored_override(def_node, scope_index)
+          return nil if resolved.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?