rigortype 0.1.7 → 0.1.8

data/lib/rigor/inference/expression_typer.rb

@@ -1025,11 +1025,15 @@ module Rigor
         local_def = node.receiver.nil? ? scope.top_level_def_for(node.name) : nil
         if local_def
           local_inference = infer_top_level_user_method(local_def, receiver, arg_types)
-          return local_inference if local_inference
-
-          # The local def matches by name but the
-          # parameter shape is too complex for the first-
-          # iteration binder (kwargs / optionals / rest).
+          return local_inference if local_inference && adoptable_self_call_result?(local_inference)
+
+          # The local def matches by name but the inference
+          # was disqualified — either the parameter shape is
+          # too complex for the first-iteration binder
+          # (kwargs / optionals / rest), or ADR-24 slice 1's
+          # conservative gate declined the resolved return
+          # type inside a class body (see
+          # `adoptable_self_call_result?`).
           # Returning `Dynamic[Top]` is the safest answer:
           # we know RBS dispatch would be wrong (the
           # method is user-defined and shadows whatever
@@ -1069,7 +1073,11 @@ module Rigor
         # the body with the call's argument types bound and
         # return the body's last-expression type.
         user_inference = try_user_method_inference(receiver, node, arg_types)
-        return user_inference if user_inference
+        if user_inference
+          return user_inference if adoptable_self_call_result?(user_inference)
+
+          return dynamic_top
+        end
 
         # Dynamic-origin propagation: when the receiver is Dynamic[T] and
         # no positive rule resolves the call, the result inherits the
@@ -1112,10 +1120,39 @@ module Rigor
         nil
       end
 
+      # ADR-24 slice 1 — implicit-self method-call resolution.
+      # `discovered_def_nodes` is now carried into method /
+      # class body scopes (see `StatementEvaluator#build_fresh_body_scope`),
+      # so a call written with no explicit receiver inside a
+      # method body resolves against the enclosing class's own
+      # definitions and the file's top-level defs. Before
+      # slice 1 every such call typed `Dynamic[top]`.
+      #
+      # The adoption of the resolved return type is gated:
+      #
+      # - At top-level / inside a DSL block (`scope.self_type`
+      #   is nil) the result is adopted unchanged — this is
+      #   the pre-slice-1 surface (the v0.0.3 A local-`def`
+      #   shortcut) and MUST keep working.
+      # - Inside a class body / method body (`self_type` set)
+      #   the result is adopted ONLY when it is `Bot`. A `Bot`
+      #   return is an always-diverging guard helper; adopting
+      #   it can only ever enable correct terminating-branch
+      #   narrowing, never a new `undefined-method` /
+      #   argument-type false positive. A non-`Bot` resolved
+      #   return is kept as `Dynamic[top]` (WD3) — adopting
+      #   precise non-`Bot` returns project-wide awaits the
+      #   callee-return-inference precision a later slice
+      #   brings (measured: unconditional adoption regressed
+      #   `rigor check lib` by 16 diagnostics).
+      def adoptable_self_call_result?(type)
+        scope.self_type.nil? || type.is_a?(Type::Bot)
+      end
+
       def try_user_method_inference(receiver, call_node, arg_types)
         return nil unless receiver.is_a?(Type::Nominal)
 
-        def_node = scope.user_def_for(receiver.class_name, call_node.name)
+        def_node = resolve_user_def_through_ancestors(receiver.class_name, call_node.name)
         return nil if def_node.nil?
 
         infer_user_method_return(def_node, receiver, arg_types)
@@ -1123,6 +1160,81 @@ module Rigor
         nil
       end
 
+      # ADR-24 slice 2 — resolves `method_name` against
+      # `class_name`'s own `def`s, then walks the user-class
+      # ancestor chain: included / prepended modules (transitive)
+      # and the superclass chain. RBS-known ancestors are NOT
+      # walked here — the `MethodDispatcher` RBS tier runs before
+      # `try_user_method_inference` and already covers them; an
+      # ancestor name that resolves to no project-discovered
+      # class/module ends that branch. Cross-file: the chain is
+      # followed through `Scope#discovered_superclasses` /
+      # `#discovered_includes` / `#discovered_def_nodes`, which
+      # the runner seeds from the project-wide pre-pass. The walk
+      # is breadth-first, cycle-guarded, and node-count-capped.
+      ANCESTOR_WALK_LIMIT = 100
+      private_constant :ANCESTOR_WALK_LIMIT
+
+      def resolve_user_def_through_ancestors(class_name, method_name)
+        queue = [class_name.to_s]
+        seen = {}
+        visited = 0
+        until queue.empty?
+          current = queue.shift
+          next if current.nil? || seen[current]
+
+          seen[current] = true
+          visited += 1
+          return nil if visited > ANCESTOR_WALK_LIMIT
+
+          found = scope.user_def_for(current, method_name)
+          return found if found
+
+          enqueue_ancestors(current, queue)
+        end
+        nil
+      end
+
+      # Pushes `current`'s direct ancestors onto the BFS queue:
+      # included / prepended modules first (Ruby places mixins
+      # nearer than the superclass), then the superclass. Each
+      # as-written name is resolved against `current`'s lexical
+      # nesting; names that resolve to no project class/module
+      # are dropped (RBS-known / third-party ancestors).
+      def enqueue_ancestors(current, queue)
+        scope.includes_of(current).each do |raw|
+          resolved = resolve_ancestor_class_name(current, raw)
+          queue.push(resolved) if resolved
+        end
+        raw_super = scope.superclass_of(current)
+        return if raw_super.nil?
+
+        resolved_super = resolve_ancestor_class_name(current, raw_super)
+        queue.push(resolved_super) if resolved_super
+      end
+
+      # Resolves a superclass name AS WRITTEN (`"Base"`, or a
+      # qualified `"A::B"`) to a project-discovered class,
+      # following Ruby's `Module.nesting` constant lookup: try
+      # the raw name under each enclosing namespace of the
+      # subclass, innermost first, then bare. Returns nil when
+      # no candidate names a discovered user class (e.g. the
+      # superclass is an RBS-known or third-party class).
+      def resolve_ancestor_class_name(subclass_qualified, raw_superclass)
+        segments = subclass_qualified.split("::")
+        (segments.length - 1).downto(0) do |i|
+          candidate = (segments[0, i] + [raw_superclass]).join("::")
+          return candidate if known_user_class?(candidate)
+        end
+        nil
+      end
+
+      def known_user_class?(name)
+        scope.discovered_superclasses.key?(name) ||
+          scope.discovered_def_nodes.key?(name) ||
+          scope.discovered_includes.key?(name)
+      end
+
       INFERENCE_GUARD_KEY = :__rigor_user_method_inference_stack__
       private_constant :INFERENCE_GUARD_KEY
 
@@ -1132,11 +1244,20 @@ module Rigor
         body_scope = build_user_method_body_scope(def_node, receiver, arg_types)
         return nil if body_scope.nil?
 
-        # Recursion-guard signature. Uses `describe(:short)`
-        # so non-Nominal receivers (e.g. the implicit
-        # `Object` carrier used for top-level / DSL-block
-        # defs in v0.0.3 A) can participate without raising.
-        signature = [receiver.describe(:short), def_node.name, arg_types.map { |t| t.describe(:short) }]
+        # Recursion-guard signature. Keyed on `(receiver,
+        # method)` only — NOT the argument types. ADR-24 WD5:
+        # a method whose summary is still being computed
+        # resolves to `Dynamic[top]` for that cycle. Keying on
+        # arg types would let mutual recursion through a
+        # `module_function` module (`Acceptance#accepts` →
+        # `accepts_one` → `accepts_dynamic` → `accepts`)
+        # recurse unboundedly whenever the carried argument
+        # types differ at each level — observed as a
+        # `SystemStackError` once implicit-self calls began
+        # resolving during the main walk. `describe(:short)`
+        # keeps non-Nominal receivers (the implicit `Object`
+        # carrier for top-level / DSL-block defs) printable.
+        signature = [receiver.describe(:short), def_node.name]
         stack = (Thread.current[INFERENCE_GUARD_KEY] ||= [])
         return Type::Combinator.untyped if stack.include?(signature)
 
@@ -1174,6 +1295,8 @@ module Rigor
                      .with_program_globals(scope.program_globals)
                      .with_discovered_methods(scope.discovered_methods)
                      .with_discovered_def_nodes(scope.discovered_def_nodes)
+                     .with_discovered_superclasses(scope.discovered_superclasses)
+                     .with_discovered_includes(scope.discovered_includes)
                      .with_self_type(receiver)
 
         required.each_with_index do |param, index|

data/lib/rigor/inference/method_dispatcher/rbs_dispatch.rb

@@ -85,10 +85,17 @@ module Rigor
         #   `Bundler::URI::Generic` per `Kernel#dup: () -> self`
         #   rather than `Object`. Defaults to nil (compute self
         #   from the resolved class_name as before).
+        # @param public_only [Boolean] when true, a method whose RBS
+        #   accessibility is `:private` does not resolve (the call
+        #   yields `nil`, i.e. "no rule"). Set by the explicit-
+        #   non-`self`-receiver user-class fallback so a call like
+        #   `Favourite.select(...)` does not adopt the private
+        #   `Kernel#select` signature.
         # @return [Rigor::Type, nil] inferred return type, or `nil`
         #   when no rule resolves (no class name, no method, dispatch
         #   on a Top/Dynamic[Top] receiver, etc.).
-        def try_dispatch(receiver:, method_name:, args:, environment:, block_type: nil, self_type_override: nil)
+        def try_dispatch(receiver:, method_name:, args:, environment:, block_type: nil, self_type_override: nil,
+                         public_only: false)
           return nil if environment.nil?
           return nil unless environment.rbs_loader
 
@@ -98,7 +105,8 @@ module Rigor
             args: args,
             environment: environment,
             block_type: block_type,
-            self_type_override: self_type_override
+            self_type_override: self_type_override,
+            public_only: public_only
           )
         end
 
@@ -140,32 +148,39 @@ module Rigor
         class << self
           private
 
-          def dispatch_for(receiver:, method_name:, args:, environment:, block_type:, self_type_override: nil)
+          def dispatch_for(receiver:, method_name:, args:, environment:, block_type:, self_type_override: nil,
+                           public_only: false)
             args ||= []
             case receiver
             when Type::Union
-              dispatch_union(receiver, method_name, args, environment, block_type, self_type_override)
+              dispatch_union(receiver, method_name, args, environment, block_type, self_type_override,
+                             public_only: public_only)
             else
-              dispatch_one(receiver, method_name, args, environment, block_type, self_type_override)
+              dispatch_one(receiver, method_name, args, environment, block_type, self_type_override,
+                           public_only: public_only)
             end
           end
 
-          def dispatch_union(receiver, method_name, args, environment, block_type, self_type_override = nil)
+          def dispatch_union(receiver, method_name, args, environment, block_type, self_type_override = nil,
+                             public_only: false)
             results = receiver.members.map do |member|
-              dispatch_one(member, method_name, args, environment, block_type, self_type_override)
+              dispatch_one(member, method_name, args, environment, block_type, self_type_override,
+                           public_only: public_only)
             end
             return nil if results.any?(&:nil?)
 
             Type::Combinator.union(*results)
           end
 
-          def dispatch_one(receiver, method_name, args, environment, block_type, self_type_override = nil)
+          def dispatch_one(receiver, method_name, args, environment, block_type, self_type_override = nil,
+                           public_only: false)
             descriptor = receiver_descriptor(receiver)
             return nil unless descriptor
 
             class_name, kind, receiver_args = descriptor
             method_definition = lookup_method(environment, class_name, kind, method_name)
             return nil unless method_definition
+            return nil if public_only && method_private?(method_definition)
 
             type_vars = build_type_vars(environment, class_name, receiver_args)
             translate_return_type(
@@ -242,6 +257,16 @@ module Rigor
             ]
           end
 
+          # True when the RBS method definition is `private`. A call
+          # with an explicit, non-`self` receiver cannot reach a
+          # private method (Ruby raises `NoMethodError`), so the
+          # explicit-receiver user-class fallback uses this to reject
+          # private signatures rather than return a wrong type.
+          def method_private?(method_definition)
+            method_definition.respond_to?(:accessibility) &&
+              method_definition.accessibility == :private
+          end
+
           def lookup_method(environment, class_name, kind, method_name)
             case kind
             when :instance

data/lib/rigor/inference/method_dispatcher.rb

@@ -191,7 +191,7 @@ module Rigor
         # introspection (`attr_reader`, `private`, ...) on
         # user classes without requiring the user to author
         # their own RBS.
-        try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
+        try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type, call_node)
       end
 
       # v0.1.3 — discovered-method dispatch tier. `scope` carries
@@ -651,7 +651,7 @@ module Rigor
           )
       end
 
-      def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type)
+      def try_user_class_fallback(receiver_type, method_name, arg_types, environment, block_type, call_node = nil)
         return nil if environment.nil?
 
         fallback_receiver = user_class_fallback_receiver(receiver_type, environment)
@@ -665,16 +665,44 @@ module Rigor
         # `Bundler::URI::Generic` instance method types `base`
         # as `Object` because `Bundler::URI::Generic` is not in
         # RBS and the fallback's `self` resolves to Object.
+        #
+        # `public_only:` — when the call has an EXPLICIT, non-`self`
+        # receiver (`Favourite.select(...)`), suppress the private
+        # `Object`/`Kernel`/`Class` methods the fallback would
+        # otherwise resolve. Ruby raises `NoMethodError` for a
+        # private method called with an explicit receiver, so
+        # resolving `Favourite.select` to the private `Kernel#select`
+        # (`-> Array[String]`) is a confidently-wrong type. Implicit-
+        # self / `self.`-receiver calls (`puts`, `raise`, `require`)
+        # keep resolving — those are the fallback's intended targets.
         RbsDispatch.try_dispatch(
           receiver: fallback_receiver,
           method_name: method_name,
           args: arg_types,
           environment: environment,
           block_type: block_type,
-          self_type_override: receiver_type
+          self_type_override: receiver_type,
+          public_only: explicit_non_self_receiver?(call_node)
         )
       end
 
+      # True when the call node carries an explicit receiver that is
+      # not the literal `self`. Such a call cannot legally dispatch to
+      # a private method, so the user-class fallback must skip private
+      # signatures rather than return a confidently-wrong type. Returns
+      # false for implicit-self calls and `self.`-receiver calls (both
+      # may legally reach a private method in modern Ruby), and false
+      # when no `call_node` is supplied (internal dispatcher callers).
+      def explicit_non_self_receiver?(call_node)
+        return false if call_node.nil?
+        return false unless call_node.respond_to?(:receiver)
+
+        receiver = call_node.receiver
+        return false if receiver.nil?
+
+        !receiver.is_a?(Prism::SelfNode)
+      end
+
       def user_class_fallback_receiver(receiver_type, environment)
         case receiver_type
         when Type::Nominal

data/lib/rigor/inference/scope_indexer.rb

@@ -109,12 +109,11 @@ module Rigor
         discovered_methods = build_discovered_methods(root)
         seeded_scope = seeded_scope.with_discovered_methods(discovered_methods)
 
-        # v0.0.2 #5 — also record the def node itself for
-        # instance methods so the engine can re-type the body
-        # when a call site dispatches against a user-defined
-        # method without an RBS sig.
-        discovered_def_nodes = build_discovered_def_nodes(root)
-        seeded_scope = seeded_scope.with_discovered_def_nodes(discovered_def_nodes)
+        # v0.0.2 #5 + ADR-24 slice 2 — record per-instance-method
+        # def nodes, the class -> superclass map, and the
+        # class/module -> included-modules map, each merged under
+        # the cross-file pre-pass seed (see below).
+        seeded_scope = merge_project_method_indexes(seeded_scope, default_scope, root)
 
         # v0.1.2 — per-class table of method visibilities
         # (`:public` / `:private` / `:protected`). The
@@ -134,6 +133,31 @@ module Rigor
         table
       end
 
+      # v0.0.2 #5 + ADR-24 slice 2 — seeds the three
+      # project-method indexes onto `seeded_scope`: the
+      # per-instance-method def-node table, the class ->
+      # superclass map, and the class/module -> included-modules
+      # map. Each per-file table is merged UNDER the cross-file
+      # `discovered_def_index_for_paths` seed carried on
+      # `default_scope` — same-file declarations win per entry,
+      # the cross-file seed supplies sibling-file ancestors.
+      def merge_project_method_indexes(seeded_scope, default_scope, root)
+        def_nodes = default_scope.discovered_def_nodes.merge(
+          build_discovered_def_nodes(root)
+        ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
+        superclasses = default_scope.discovered_superclasses.merge(
+          build_discovered_superclasses(root)
+        )
+        includes = default_scope.discovered_includes.merge(
+          build_discovered_includes(root)
+        ) { |_class, cross_file, per_file| (cross_file + per_file).uniq }
+
+        seeded_scope
+          .with_discovered_def_nodes(def_nodes)
+          .with_discovered_superclasses(superclasses)
+          .with_discovered_includes(includes)
+      end
+
       # Slice 7 phase 2. Builds the class-level ivar accumulator
       # by walking every `Prism::ClassNode` / `Prism::ModuleNode`
       # body, descending into each nested `Prism::DefNode`, and
@@ -580,6 +604,94 @@ module Rigor
         accumulator[class_name][def_node.name] = def_node
       end
 
+      # ADR-24 slice 2 — per-class table mapping a fully
+      # qualified user class to its superclass name AS WRITTEN
+      # at the `class Foo < Bar` declaration. Only constant
+      # superclasses are recorded (`class Foo < Struct.new(...)`
+      # and other non-constant superclasses produce no entry).
+      # The as-written name is resolved to a qualified class at
+      # the call site against the subclass's lexical nesting —
+      # see `ExpressionTyper#resolve_ancestor_class_name`.
+      def build_discovered_superclasses(root)
+        accumulator = {}
+        walk_class_superclasses(root, [], accumulator)
+        accumulator.freeze
+      end
+
+      def walk_class_superclasses(node, qualified_prefix, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            superclass = node.superclass && qualified_name_for(node.superclass)
+            accumulator[full] = superclass if superclass
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        when Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_superclasses(child, qualified_prefix, accumulator)
+        end
+      end
+
+      MIXIN_CALL_NAMES = %i[include prepend].freeze
+
+      # ADR-24 slice 2 — per-class/module table mapping a fully
+      # qualified user class or module to the list of module
+      # names it `include`s / `prepend`s, AS WRITTEN at the
+      # mixin call (`include Foo` / `include Foo::Bar`). Only
+      # constant arguments are recorded; dynamic mixins
+      # (`include some_method`) produce no entry. `prepend` is
+      # bucketed with `include` — both contribute instance
+      # methods to the ancestor chain. `extend` is NOT tracked
+      # (it adds singleton methods; ADR-24 slice 2 resolves the
+      # instance-side chain).
+      def build_discovered_includes(root)
+        accumulator = {}
+        walk_class_includes(root, [], nil, accumulator)
+        accumulator.transform_values { |mods| mods.uniq.freeze }.freeze
+      end
+
+      def walk_class_includes(node, qualified_prefix, current_class, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            full = (qualified_prefix + [name]).join("::")
+            walk_class_includes(node.body, qualified_prefix + [name], full, accumulator) if node.body
+            return
+          end
+        when Prism::CallNode
+          record_mixin_call(node, current_class, accumulator)
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_class_includes(child, qualified_prefix, current_class, accumulator)
+        end
+      end
+
+      def record_mixin_call(node, current_class, accumulator)
+        return unless current_class && node.receiver.nil?
+        return unless MIXIN_CALL_NAMES.include?(node.name)
+
+        node.arguments&.arguments&.each do |arg|
+          mod = qualified_name_for(arg)
+          (accumulator[current_class] ||= []) << mod if mod
+        end
+      end
+
       VISIBILITY_MODIFIERS = %i[public private protected].freeze
 
       # v0.1.2 — per-class method-visibility table for the
@@ -845,6 +957,44 @@ module Rigor
         accumulator.freeze
       end
 
+      # ADR-24 slice 2 — cross-file companion to
+      # `discovered_classes_for_paths`. Walks every project
+      # file once and returns both the merged
+      # `discovered_def_nodes` table (a class reopened across
+      # files has its method tables merged) and the merged
+      # class -> superclass-name map. The engine consults these
+      # so an implicit-self call inside a subclass resolves
+      # against a superclass `def` declared in a sibling file
+      # (`Mastodon::CLI::Accounts` calling a helper defined in
+      # `Mastodon::CLI::Base`).
+      #
+      # @param paths  [Array<String>] project file paths.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{Symbol => Hash}] `{ def_nodes:, superclasses: }`
+      def discovered_def_index_for_paths(paths, buffer: nil)
+        def_nodes = {}
+        superclasses = {}
+        includes = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          root = Prism.parse(File.read(physical), filepath: path).value
+          build_discovered_def_nodes(root).each do |class_name, methods|
+            (def_nodes[class_name] ||= {}).merge!(methods)
+          end
+          superclasses.merge!(build_discovered_superclasses(root))
+          build_discovered_includes(root).each do |class_name, mods|
+            includes[class_name] = ((includes[class_name] || []) + mods).uniq
+          end
+        rescue StandardError
+          # Skip files that fail to parse or read; the per-file
+          # analyzer surfaces the parse error separately.
+          next
+        end
+        def_nodes.each_value(&:freeze)
+        includes.each_value(&:freeze)
+        { def_nodes: def_nodes.freeze, superclasses: superclasses.freeze, includes: includes.freeze }
+      end
+
       # Class-only variant of `record_declarations` — descends
       # into nested module bodies (so `module Foo; class Bar`
       # registers `Foo::Bar`) but never registers the module

data/lib/rigor/inference/statement_evaluator.rb

@@ -358,9 +358,9 @@ module Rigor
         # is the falsey edge of the predicate (subsequent
         # statements observe the predicate-was-false world).
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.subsequent.nil?
+          if branch_terminates?(node.statements, then_type) && node.subsequent.nil?
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.subsequent) && node.statements
+          if branch_terminates?(node.subsequent, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -385,9 +385,9 @@ module Rigor
         # `if`: when the body unconditionally exits and there
         # is no else, the post-scope is the truthy edge.
         return [Type::Combinator.union(then_type, else_type), truthy_scope] \
-          if branch_unconditionally_exits?(node.statements) && node.else_clause.nil?
+          if branch_terminates?(node.statements, then_type) && node.else_clause.nil?
         return [Type::Combinator.union(then_type, else_type), falsey_scope] \
-          if branch_unconditionally_exits?(node.else_clause) && node.statements
+          if branch_terminates?(node.else_clause, else_type) && node.statements
 
         [
           Type::Combinator.union(then_type, else_type),
@@ -709,24 +709,25 @@ module Rigor
       # `a` when the RHS is skipped, while `a || b` can only produce
       # the truthy fragment of `a` when the RHS is skipped.
       #
-      # When the RHS unconditionally exits (`raise` / `return` /
-      # `throw` / `exit` / `abort` / `fail` / `next` / `break`), the
-      # post-OR / post-AND scope is the LHS-skipped edge alone:
-      # `a or raise` only survives when `a` was truthy, so subsequent
-      # statements observe `a` narrowed to its truthy fragment; the
-      # symmetric `a and raise` survives only when `a` was falsey.
-      # Same shape as the `eval_if` / `eval_unless` early-return
-      # narrowing.
+      # When the RHS is a terminating branch — it `raise`s /
+      # `return`s / `throw`s / `exit`s / `break`s / `next`s, OR its
+      # inferred type is `Bot` (ADR-24 WD6: a divergent helper such
+      # as `a or fail_with_message(...)`, recognised via
+      # `branch_terminates?`) — the post-OR / post-AND scope is the
+      # LHS-skipped edge alone: `a or raise` only survives when `a`
+      # was truthy, so subsequent statements observe `a` narrowed to
+      # its truthy fragment; the symmetric `a and raise` survives
+      # only when `a` was falsey. Same shape as the `eval_if` /
+      # `eval_unless` early-return narrowing.
       def eval_and_or(node)
         left_type, left_scope = sub_eval(node.left, scope)
         truthy_left, falsey_left = Narrowing.predicate_scopes(node.left, left_scope)
         rhs_entry = node.is_a?(Prism::AndNode) ? truthy_left : falsey_left
-        if branch_unconditionally_exits?(node.right)
-          # Walk the RHS for side-effects (on_enter callbacks,
-          # diagnostic dispatch on the raise / return expression
-          # itself) but discard its scope: control never reaches
-          # any statement after `a or raise` via that edge.
-          sub_eval(node.right, rhs_entry)
+        right_type, right_scope = sub_eval(node.right, rhs_entry)
+
+        if branch_terminates?(node.right, right_type)
+          # Control never reaches any statement after `a or raise`
+          # via the RHS edge — the RHS scope is discarded.
           surviving_type =
             if node.is_a?(Prism::AndNode)
               Narrowing.narrow_falsey(left_type)
@@ -737,7 +738,6 @@ module Rigor
           return [surviving_type, surviving_scope]
         end
 
-        right_type, right_scope = sub_eval(node.right, rhs_entry)
         skipped_type =
           if node.is_a?(Prism::AndNode)
             Narrowing.narrow_falsey(left_type)
@@ -1484,7 +1484,7 @@ module Rigor
       # ScopeIndexer-populated declaration overrides
       # (`Prism::ConstantReadNode` for `module Foo` headers, etc.)
       # remain reachable from inside nested bodies.
-      def build_fresh_body_scope
+      def build_fresh_body_scope # rubocop:disable Metrics/AbcSize
         Scope.empty(environment: scope.environment)
              .with_declared_types(scope.declared_types)
              .with_discovered_classes(scope.discovered_classes)
@@ -1493,6 +1493,9 @@ module Rigor
              .with_class_cvars(scope.class_cvars)
              .with_program_globals(scope.program_globals)
              .with_discovered_methods(scope.discovered_methods)
+             .with_discovered_def_nodes(scope.discovered_def_nodes)
+             .with_discovered_superclasses(scope.discovered_superclasses)
+             .with_discovered_includes(scope.discovered_includes)
              .with_discovered_method_visibilities(scope.discovered_method_visibilities)
       end
 
@@ -1692,6 +1695,23 @@ module Rigor
         end
       end
 
+      # ADR-24 WD6 / slice 3 — generalised terminating-branch
+      # detection. `branch_unconditionally_exits?` recognises a
+      # branch SYNTACTICALLY (return / next / break / a call
+      # named raise / throw / exit / abort / fail). A branch
+      # whose *inferred type is `Bot`* also terminates — it
+      # cannot produce a value, so control never falls through
+      # it — regardless of how it is spelled. The canonical
+      # case is a resolved guard helper (`fail_with_message(...)`)
+      # whose body always raises: ADR-24 slice 1 types the call
+      # `bot`, and this OR-test makes `helper(...) if x.nil?`
+      # narrow exactly like `raise ... if x.nil?`. The branch
+      # type is already computed by `eval_if` / `eval_unless`.
+      def branch_terminates?(branch_node, branch_type)
+        branch_unconditionally_exits?(branch_node) ||
+          branch_type.is_a?(Type::Bot)
+      end
+
       def eval_branch_or_nil(branch_node, branch_scope)
         return [Type::Combinator.constant_of(nil), branch_scope] if branch_node.nil?