rigortype 0.1.11 → 0.1.13

data/lib/rigor/inference/indexed_narrowing.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../type"
+require_relative "mutation_widening"
+
+module Rigor
+  module Inference
+    # Closes the "`params[:f] ||= []; params[:f] << x`" precision
+    # gap surfaced by the Redmine 6.1.2 `Query#as_params` survey
+    # (ROADMAP § Future cycles / Type-language / engine —
+    # "Indexed-collection narrowing through `Hash[k] ||= default`").
+    #
+    # After `receiver[key] ||= default` the next read at
+    # `receiver[key]` is known non-nil, but Rigor types each
+    # `Hash#[]` independently and the subsequent `<<` / `[]=` /
+    # other mutator dispatches against the un-narrowed result —
+    # which on a `HashShape{}` carrier folds to `Constant[nil]`.
+    #
+    # This module is the address-recogniser + invalidator shared
+    # by {Inference::StatementEvaluator}'s `eval_index_or_write`
+    # handler (which RECORDS the narrowing) and `eval_call`
+    # (which INVALIDATES on intervening writes / mutators) and
+    # by {Inference::ExpressionTyper}'s `call_type_for` (which
+    # CONSUMES the narrowing when typing a follow-up `[]` read).
+    #
+    # **Stable receivers.** A receiver is "stable" iff it is a
+    # `LocalVariableReadNode` or `InstanceVariableReadNode`.
+    # Method-call chains (`foo.bar[:k]`) and other shapes are
+    # rejected because a follow-up read against an identical-
+    # looking AST chain has no guarantee of resolving to the
+    # same runtime value — narrowing it would invent a fact.
+    #
+    # **Stable keys.** A key is "stable" iff it is a literal
+    # `SymbolNode` / `StringNode` / `IntegerNode`. Local-variable
+    # keys (`params[field]`) are excluded for the same
+    # invent-a-fact reason: the local could be rebound between
+    # the `||=` and the read.
+    #
+    # **Invalidation.** Three conditions drop a recorded
+    # narrowing:
+    # - The receiver variable is rebound (handled inside
+    #   `Scope#with_local` / `Scope#with_ivar`).
+    # - An intervening `receiver[key] = value` writes the same
+    #   slot — `:[]=` could rebind the slot to nil; conservative
+    #   drop.
+    # - An intervening mutator from {MutationWidening::HASH_MUTATORS}
+    #   or {MutationWidening::ARRAY_MUTATORS} runs against the
+    #   receiver (e.g. `params.delete(:f)`, `params.clear`).
+    #
+    # All three are implemented in `StatementEvaluator#eval_call`'s
+    # post-dispatch path through {.invalidate_after_call}.
+    module IndexedNarrowing
+      # Literal Prism nodes whose Ruby value the analyzer trusts
+      # as a stable address. Symbol / String are the dominant
+      # Hash key shapes; Integer covers numerically-keyed Hashes
+      # and Array indices.
+      STABLE_KEY_NODES = [Prism::SymbolNode, Prism::StringNode, Prism::IntegerNode].freeze
+
+      module_function
+
+      # Returns `[receiver_kind, receiver_name]` when `node` is a
+      # `LocalVariableReadNode` or `InstanceVariableReadNode`,
+      # otherwise nil.
+      def stable_receiver(node)
+        case node
+        when Prism::LocalVariableReadNode then [:local, node.name]
+        when Prism::InstanceVariableReadNode then [:ivar, node.name]
+        end
+      end
+
+      # Returns the literal Ruby value when `node` is a stable
+      # key shape, otherwise nil. Symbols → `Symbol`,
+      # Strings → `String` (unescaped), Integers → `Integer`.
+      def stable_key(node)
+        case node
+        when Prism::SymbolNode then node.unescaped.to_sym
+        when Prism::StringNode then node.unescaped
+        when Prism::IntegerNode then node.value
+        end
+      end
+
+      # Returns `[receiver_kind, receiver_name, key]` when the
+      # CallNode is a `receiver[key]` read or write whose
+      # receiver and key are both stable, otherwise nil. Used
+      # by both the recorder (for `IndexOrWriteNode`'s
+      # receiver/arguments triplet) and the invalidator (for
+      # `CallNode :[]=` / mutator calls). Treats only the FIRST
+      # argument as the key; `:[]=`'s second argument is the
+      # rvalue and is not part of the address.
+      def stable_address(receiver_node, key_node)
+        receiver = stable_receiver(receiver_node)
+        return nil if receiver.nil?
+
+        key = stable_key(key_node)
+        return nil if key.nil?
+
+        [receiver.first, receiver.last, key]
+      end
+
+      # Looks up a recorded narrowing for `receiver[key]` against
+      # `scope`, returning the narrowed type or nil when no
+      # entry applies. Used by ExpressionTyper's `[]` dispatch
+      # to refine the result of a stable indexed read.
+      def lookup_for_call(node, scope)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless node.name == :[]
+        return nil if node.arguments.nil?
+        return nil unless node.arguments.arguments.size == 1
+
+        address = stable_address(node.receiver, node.arguments.arguments.first)
+        return nil if address.nil?
+
+        scope.indexed_narrowing(*address)
+      end
+
+      # Removes recorded narrowings invalidated by `call_node`.
+      # Two patterns:
+      #
+      # - `receiver[key] = value` (a `:[]=` against a stable
+      #   address): drop the specific `(receiver, key)` entry.
+      # - Any mutator from `HASH_MUTATORS` / `ARRAY_MUTATORS`
+      #   against a stable receiver: drop EVERY entry rooted
+      #   at that receiver, because the mutator could rebind
+      #   any slot.
+      #
+      # Returns the updated scope. Always-safe (only forgets;
+      # never invents).
+      def invalidate_after_call(call_node:, current_scope:)
+        return current_scope unless call_node.is_a?(Prism::CallNode)
+
+        if call_node.name == :[]=
+          invalidate_indexed_write(call_node, current_scope)
+        elsif mutator?(call_node.name)
+          invalidate_mutator(call_node, current_scope)
+        else
+          current_scope
+        end
+      end
+
+      def mutator?(method_name)
+        MutationWidening::HASH_MUTATORS.include?(method_name) ||
+          MutationWidening::ARRAY_MUTATORS.include?(method_name)
+      end
+
+      def invalidate_indexed_write(call_node, current_scope)
+        args = call_node.arguments&.arguments
+        return current_scope if args.nil? || args.empty?
+
+        address = stable_address(call_node.receiver, args.first)
+        return current_scope if address.nil?
+
+        current_scope.without_indexed_narrowing(*address)
+      end
+
+      def invalidate_mutator(call_node, current_scope)
+        receiver = stable_receiver(call_node.receiver)
+        return current_scope if receiver.nil?
+
+        current_scope.without_indexed_narrowings_for(*receiver)
+      end
+
+      # Companion invalidator for single-hop method-chain
+      # narrowings (ROADMAP § Future cycles — "Method-call
+      # receiver narrowing across stable receivers", B2 from
+      # the slice's design notes). Drops every
+      # `(receiver, *)` chain narrowing rooted at the call's
+      # OUTER stable receiver — matching the ROADMAP's "any
+      # intervening method call against the same receiver"
+      # criterion. A call against `x.last` (the OUTER receiver
+      # is a `CallNode`, not a stable root) does NOT drop
+      # narrowings keyed on `x`, so the worked-site
+      # `x.last << y` pattern correctly preserves the chain
+      # narrowing for any further `x.last` read in the same
+      # body. Always-safe (only forgets; never invents).
+      def invalidate_chain_after_call(call_node:, current_scope:)
+        return current_scope unless call_node.is_a?(Prism::CallNode)
+
+        receiver = stable_receiver(call_node.receiver)
+        return current_scope if receiver.nil?
+
+        current_scope.without_method_chain_narrowings_for(*receiver)
+      end
+    end
+  end
+end

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

@@ -42,9 +42,33 @@ module Rigor
           when :inject, :reduce then inject_block_params(receiver, args)
           when :group_by, :partition then single_element_block_params(receiver)
           when :each_slice, :each_cons then slice_block_params(receiver)
+          when :new then class_new_block_params(receiver, args)
           end
         end
 
+        # `Class.new { |c| … }` and `Class.new(Parent) { |c| … }`
+        # — the block parameter is the freshly-created anonymous
+        # class, statically representable as the parent's singleton
+        # type (the new class inherits every singleton method the
+        # parent exposes, which is what callers use this form to
+        # configure: `c.table_name = …`, `c.attribute :foo`, etc.).
+        # No parent → `singleton(Object)`. RBS would otherwise widen
+        # the block param to bare `Nominal[Class]`, dropping access
+        # to the parent's class-side surface.
+        def class_new_block_params(receiver, args)
+          return nil unless class_metaclass_receiver?(receiver)
+
+          parent = args.first
+          return [Type::Combinator.singleton_of("Object")] if parent.nil?
+          return [parent] if parent.is_a?(Type::Singleton)
+
+          nil
+        end
+
+        def class_metaclass_receiver?(type)
+          type.is_a?(Type::Singleton) && type.class_name == "Class"
+        end
+
         def times_block_params(receiver)
           return nil unless integer_rooted?(receiver)
 

data/lib/rigor/inference/method_dispatcher.rb

@@ -805,9 +805,32 @@ module Rigor
         date_lift = date_new_lift(receiver_type.class_name, arg_types)
         return date_lift if date_lift
 
+        class_new_lift = class_new_lift(receiver_type.class_name, arg_types)
+        return class_new_lift if class_new_lift
+
         Type::Combinator.nominal_of(receiver_type.class_name)
       end
 
+      # `Class.new` and `Class.new(Parent)` create a brand-new
+      # anonymous class. Statically that class is representable as
+      # the parent's singleton type — its singleton-method surface
+      # is the parent's (plus whatever the block defines, which we
+      # do not statically track here), so `Singleton[Parent]` lets
+      # downstream `klass.some_class_method` resolve. No parent →
+      # `singleton(Object)`. Anything else (dynamic parent, more
+      # than one positional, …) falls back to `Nominal[Class]` via
+      # the surrounding `meta_new` tail.
+      def class_new_lift(class_name, arg_types)
+        return nil unless class_name == "Class"
+        return Type::Combinator.singleton_of("Object") if arg_types.empty?
+        return nil unless arg_types.size == 1
+
+        parent = arg_types.first
+        return parent if parent.is_a?(Type::Singleton)
+
+        nil
+      end
+
       # ADR-15 Phase 4b.x — `Ractor.make_shareable` on both the
       # outer Hash and each lambda value. A plain `.freeze` leaves
       # the Procs unshareable; reading `CONSTANT_CONSTRUCTORS[class]`

data/lib/rigor/inference/mutation_widening.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # Widens a local- or instance-variable binding after a call
+    # whose receiver is that variable AND whose method is a known
+    # in-place mutator.
+    #
+    # Closes the **G1 / G2** flow-folding gaps documented at
+    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md`
+    # and queued in [`docs/CURRENT_WORK.md`](../../../docs/CURRENT_WORK.md)
+    # § "Flow-folding". The user-visible symptom they shared was a
+    # spurious `flow.always-truthy-condition` on a `arr.size == N`
+    # / `arr.empty?` / `@arr.empty?` check that follows a loop
+    # body or sibling method that mutates `arr` / `@arr` in place.
+    #
+    # **The mechanism.** When source like
+    #
+    #     arms = [first]                     # arms : Tuple[T]  (size=1)
+    #     while peek_pipe?
+    #       arms << next_arm                 # mutator call on a local
+    #     end
+    #     return arms.first if arms.size == 1
+    #
+    # runs through inference today, the literal `[first]` writes
+    # `arms` as `Tuple[T]`. The shape carrier's `size` folds to
+    # `Constant[1]`. The body's `arms << next_arm` returns a type
+    # for the call expression but does NOT rebind `arms`, so after
+    # the loop `arms` still carries the `Tuple[T]` binding —
+    # `arms.size == 1` constant-folds to `true` and the user sees
+    # a false `flow.always-truthy-condition`.
+    #
+    # The narrowest correct fix is to **widen the receiver binding
+    # at the mutator call site**: replace `arms`'s binding with
+    # `Nominal[Array, [union(elements)]]` so the carrier no longer
+    # carries the literal arity. Inside a loop body, the post-call
+    # body scope then joins with the pre-loop scope through
+    # `join_with_nil_injection` → `Scope#join` (which unions per
+    # name); the resulting union loses size precision, so the
+    # `arms.size` fold returns `Integer` (not `Constant[1]`) and
+    # the diagnostic correctly stays silent.
+    #
+    # The widening is **always type-safe**: it never introduces a
+    # new fact, only forgets a literal-shape fact that is no longer
+    # justified once mutation occurred. It costs only the precise
+    # arity / pair-set the shape carrier was tracking; the underlying
+    # nominal stays exact (`Array` / `Hash`) and element types
+    # stay as a union of what was there.
+    #
+    # **Scope.** This slice addresses:
+    #
+    # - `arr.<mutator>(...)` where `arr` is a local variable.
+    # - `@arr.<mutator>(...)` where `@arr` is an instance variable.
+    #
+    # Out of scope (left for a separate cycle):
+    #
+    # - **`retry` flow edge** (e.g. `tries += 1; retry`). The
+    #   `tries` rebind across `retry` is a flow-edge issue, not a
+    #   call-site mutation issue.
+    # - **Intervening method call invalidates the ivar binding**
+    #   (e.g. `if @performed; perform!; if @performed`). The
+    #   intra-procedural call effect on ivars is a separate
+    #   mutation-effect feature.
+    # - **Read-before-write nil** (e.g. `unless @warning_issued;
+    #   ...; @warning_issued = true`). Requires tracking the
+    #   first-write position; flow-sensitive but orthogonal.
+    # - **Local-variable mutation inside a block body** (e.g.
+    #   `arr = []; xs.each { |x| arr << x }`). Block bodies
+    #   create a child scope; the existing closure-escape model
+    #   only widens outer locals when the block ESCAPES the
+    #   call. An in-place mutator inside a non-escaping block on
+    #   an outer LOCAL does not yet flow back. **Ivar mutations
+    #   inside a block ARE handled** (ivars live in the
+    #   method-body scope, not the block-local scope) — the
+    #   widening fires from inside the block and the new ivar
+    #   binding is visible to the outer scope.
+    #
+    # Those four are documented as "G2 remaining" in
+    # `docs/CURRENT_WORK.md` and are intentionally deferred.
+    module MutationWidening
+      # Array mutators that change either the size or the element
+      # set of a literal-shape carrier (Tuple). Receiver-mutating
+      # methods only — non-mutating siblings (`map` vs `map!`,
+      # `select` vs `select!`) stay precise.
+      #
+      # `<<` and `[]=` are the dominant survey cases; the bang
+      # variants and the size-mutators cover the rest of the
+      # Mastodon cluster-4 G1 catalogue.
+      ARRAY_MUTATORS = %i[
+        << push append prepend unshift concat insert
+        pop shift
+        delete delete_at delete_if reject!
+        clear compact!
+        replace fill []=
+        map! collect! select! filter! keep_if uniq!
+        flatten! sort! sort_by! reverse! rotate! shuffle! slice!
+      ].to_set.freeze
+
+      # Hash mutators that invalidate a `HashShape` carrier. Same
+      # principle as `ARRAY_MUTATORS`: only the receiver-mutating
+      # methods are listed.
+      HASH_MUTATORS = %i[
+        []= store
+        delete delete_if reject! select! filter! keep_if
+        clear compact! merge! update transform_keys! transform_values!
+        replace
+      ].to_set.freeze
+
+      module_function
+
+      # Returns a scope with the call's receiver widened, when the
+      # receiver is a local-/instance-variable read whose current
+      # binding is a literal-shape carrier (`Tuple` / `HashShape`)
+      # AND the call name is a known in-place mutator for that
+      # shape. Returns `current_scope` unchanged otherwise.
+      #
+      # @param call_node     [Prism::CallNode]
+      # @param current_scope [Rigor::Scope]
+      # @return              [Rigor::Scope]
+      def widen_after_call(call_node:, current_scope:)
+        receiver = call_node.receiver
+        return current_scope if receiver.nil?
+
+        case receiver
+        when Prism::LocalVariableReadNode
+          widen_local(call_node.name, receiver.name, current_scope)
+        when Prism::InstanceVariableReadNode
+          widen_ivar(call_node.name, receiver.name, current_scope)
+        else
+          current_scope
+        end
+      end
+
+      # Propagate block-body mutations of outer-scope variables
+      # back into `outer_scope`. Block bodies live in a child
+      # scope; mutations the block body performs on captured
+      # outer LOCALS are otherwise invisible to the post-call
+      # outer scope (ivars are handled correctly already because
+      # they live in the method-body scope, not the block-local
+      # scope).
+      #
+      # Walks the block AST for `<receiver>.<method>(...)` calls
+      # whose receiver is either a `LocalVariableReadNode` with
+      # `depth > 0` (a captured outer local — Prism's `depth`
+      # counts scope hops outward; `depth == 0` means a
+      # block-local) or an `InstanceVariableReadNode` (always
+      # method-scope), and applies `widen_after_call` for each
+      # one against the outer scope. The widening is always safe
+      # — it can only LOSE precision — so blindly propagating is
+      # sound regardless of whether the block actually runs.
+      #
+      # Recurses into nested expression nodes so chained / nested
+      # forms (`arr << f(x); arr << g(y)`, `arr.push(x) if cond`)
+      # are all caught. Does NOT recurse into nested
+      # `Prism::BlockNode`s — each block is processed by its own
+      # `eval_call`.
+      def widen_after_block(call_node:, outer_scope:)
+        block = call_node.block
+        return outer_scope unless block.is_a?(Prism::BlockNode)
+
+        body = block.body
+        return outer_scope if body.nil?
+
+        walk_for_outer_mutations(body, outer_scope)
+      end
+
+      def walk_for_outer_mutations(node, scope)
+        return scope if node.nil?
+
+        scope = widen_for_outer_receiver(node, scope) if node.is_a?(Prism::CallNode)
+
+        # Descend into every child, including nested blocks. The
+        # `LocalVariableReadNode#depth` check inside
+        # `widen_for_outer_receiver` keeps nested-block-locals
+        # from being widened in the outer scope — only references
+        # with `depth >= 1` (true captures of the outer scope's
+        # locals) trigger widening, so descending into nested
+        # blocks is safe and necessary for the hkt_registry-shape
+        # case (an outer collection mutated inside an iterator
+        # block whose body is itself inside another block).
+        node.compact_child_nodes.each do |child|
+          scope = walk_for_outer_mutations(child, scope)
+        end
+        scope
+      end
+
+      def widen_for_outer_receiver(call_node, scope)
+        receiver = call_node.receiver
+        return scope if receiver.nil?
+
+        case receiver
+        when Prism::LocalVariableReadNode
+          return scope if receiver.depth.zero?
+
+          widen_local(call_node.name, receiver.name, scope)
+        when Prism::InstanceVariableReadNode
+          widen_ivar(call_node.name, receiver.name, scope)
+        else
+          scope
+        end
+      end
+
+      def widen_local(method_name, var_name, current_scope)
+        current = current_scope.local(var_name)
+        widened = widen_for_mutator(current, method_name)
+        return current_scope if widened.nil?
+
+        current_scope.with_local(var_name, widened)
+      end
+
+      def widen_ivar(method_name, var_name, current_scope)
+        current = current_scope.ivar(var_name)
+        widened = widen_for_mutator(current, method_name)
+        return current_scope if widened.nil?
+
+        current_scope.with_ivar(var_name, widened)
+      end
+
+      # Returns the widened type for a binding whose receiver is
+      # about to be mutated by `method_name`, or `nil` when no
+      # widening applies (binding is not a literal-shape carrier,
+      # OR the method is not a mutator for that shape, OR the
+      # binding is already a nominal — no precision to lose).
+      def widen_for_mutator(type, method_name)
+        return nil if type.nil?
+
+        case type
+        when Type::Tuple
+          return nil unless ARRAY_MUTATORS.include?(method_name)
+
+          widen_tuple(type)
+        when Type::HashShape
+          return nil unless HASH_MUTATORS.include?(method_name)
+
+          widen_hash_shape(type)
+        end
+      end
+
+      # `Tuple[A, B, C]` → `Nominal[Array, [union(A, B, C)]]`.
+      # An empty tuple has no element evidence, so the widened
+      # form carries `untyped` element bound — matches the
+      # `tuple_to_array` widening already used by `BlockFolding`.
+      def widen_tuple(tuple)
+        element_type =
+          if tuple.elements.empty?
+            Type::Combinator.untyped
+          elsif tuple.elements.size == 1
+            tuple.elements.first
+          else
+            Type::Combinator.union(*tuple.elements)
+          end
+        Type::Combinator.nominal_of("Array", type_args: [element_type])
+      end
+
+      # `HashShape` (closed or open) → `Nominal[Hash, [Kunion,
+      # Vunion]]`. Empty / extra-keys-only shapes degrade to a
+      # fully-untyped Hash.
+      def widen_hash_shape(shape)
+        if shape.pairs.empty?
+          return Type::Combinator.nominal_of("Hash",
+                                             type_args: [Type::Combinator.untyped,
+                                                         Type::Combinator.untyped])
+        end
+
+        key_type = key_union_for(shape.pairs.keys)
+        value_type = Type::Combinator.union(*shape.pairs.values)
+        Type::Combinator.nominal_of("Hash", type_args: [key_type, value_type])
+      end
+
+      # Maps the literal Ruby key set (`Symbol` / `String`) to a
+      # union of the corresponding type carriers. We deliberately
+      # do NOT fold to a `Constant<:k1> | Constant<:k2>` union —
+      # that would be a precision improvement that complicates the
+      # widening contract; the goal here is to LOSE precision, not
+      # to record a new fact set.
+      def key_union_for(keys)
+        kinds = keys.map { |k| k.is_a?(Symbol) ? "Symbol" : "String" }.uniq
+        carriers = kinds.map { |name| Type::Combinator.nominal_of(name) }
+        carriers.size == 1 ? carriers.first : Type::Combinator.union(*carriers)
+      end
+    end
+  end
+end

data/lib/rigor/inference/narrowing.rb

@@ -1371,16 +1371,12 @@ module Rigor
         # can resolve to a qualified class name. Anything else falls
         # through to "no narrowing".
         def analyse_class_predicate(node, scope, exact:)
-          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
           bare_name = static_class_name(node.arguments.arguments.first)
           return nil if bare_name.nil?
 
-          current = scope.local(node.receiver.name)
-          return nil if current.nil?
-
           # Resolve `bare_name` through the lexical-scope chain
           # so a name shadowed by the current class / enclosing
           # module wins over the top-level constant. Mirrors
@@ -1392,9 +1388,81 @@ module Rigor
           # surface as a spurious `undefined-method` on
           # subsequent `other.class_name` calls).
           class_name = resolve_class_name_lexically(bare_name, scope)
+
+          case node.receiver
+          when Prism::LocalVariableReadNode
+            analyse_class_predicate_on_local(node, scope, class_name, exact)
+          when Prism::CallNode
+            analyse_class_predicate_on_chain(node, scope, class_name, exact)
+          end
+        end
+
+        def analyse_class_predicate_on_local(node, scope, class_name, exact)
+          current = scope.local(node.receiver.name)
+          return nil if current.nil?
+
           class_predicate_scopes(scope, node.receiver.name, current, class_name, exact: exact)
         end
 
+        # Stable single-hop method-chain narrowing (ROADMAP §
+        # Future cycles — "Method-call receiver narrowing across
+        # stable receivers"). When the predicate's receiver is
+        # `<local/ivar>.<method>` with no args and no block,
+        # record the truthy / falsey narrowing in
+        # `Scope#method_chain_narrowings` keyed on the chain
+        # address. The dominated body's identical chain reads
+        # then observe the narrowed type through
+        # `ExpressionTyper#call_type_for`'s lookup.
+        #
+        # Heuristic-by-design (ROADMAP § "Soundness gap"): a
+        # second call to `x.last` could in principle return a
+        # different value than the first. The chain is dropped
+        # on (1) receiver variable rebind (handled inside
+        # `Scope#with_local` / `#with_ivar`), and (2) any
+        # intervening call against the same root receiver
+        # (handled by `StatementEvaluator#eval_call`'s
+        # invalidation step). The Law of Demeter justifies the
+        # single-hop restriction: a single-hop chain is the
+        # idiomatic Ruby shape where re-evaluation soundness is
+        # the strongest.
+        def analyse_class_predicate_on_chain(node, scope, class_name, exact)
+          address = stable_chain_address(node.receiver)
+          return nil if address.nil?
+
+          current = scope.type_of(node.receiver)
+          return nil if current.nil?
+
+          truthy_type = narrow_class(current, class_name, exact: exact, environment: scope.environment)
+          falsey_type = narrow_not_class(current, class_name, exact: exact, environment: scope.environment)
+
+          [
+            scope.with_method_chain_narrowing(*address, truthy_type),
+            scope.with_method_chain_narrowing(*address, falsey_type)
+          ]
+        end
+
+        # Returns `[receiver_kind, receiver_name, method_name]`
+        # iff `chain_call` is a stable single-hop chain whose
+        # root is a local / ivar read and whose own call shape
+        # has no positional arguments and no block. Other shapes
+        # (multi-hop, args, block, method-defined-on-arbitrary-
+        # receiver) lose stability for one of the reasons
+        # enumerated in the slice's design notes.
+        def stable_chain_address(chain_call)
+          return nil unless chain_call.is_a?(Prism::CallNode)
+          return nil unless chain_call.block.nil?
+
+          args = chain_call.arguments
+          return nil unless args.nil? || args.arguments.empty?
+
+          case chain_call.receiver
+          when Prism::LocalVariableReadNode
+            [:local, chain_call.receiver.name, chain_call.name]
+          when Prism::InstanceVariableReadNode
+            [:ivar, chain_call.receiver.name, chain_call.name]
+          end
+        end
+
         # Walks the lexical-nesting chain derived from
         # `scope.self_type` and returns the first
         # `<prefix>::<bare_name>` (or bare `<bare_name>` at the