rigortype 0.4.0 → 0.4.2

data/lib/rigor/scope.rb

@@ -3,6 +3,9 @@
 require_relative "type"
 require_relative "environment"
 require_relative "scope/discovery_index"
+require_relative "scope/resolution_chain"
+require_relative "inference/definer_resolution"
+require_relative "inference/in_effect_refinements"
 require_relative "analysis/fact_store"
 require_relative "analysis/dependency_recorder"
 require_relative "inference/expression_typer"
@@ -24,12 +27,12 @@ module Rigor
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced, :published_constant_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
-                :opaque_block_self, :singleton_class_body, :lexical_nesting,
+                :opaque_block_self, :block_self_unknown, :singleton_class_body, :lexical_nesting,
                 :dynamic_origins, :local_origins, :ivar_origins,
                 :void_origins, :plugin_typed_calls,
                 :optimistic_origins, :optimistic_locals, :optimistic_ivars,
                 :repeated_or_writes, :match_frame,
-                :constant_narrowings, :guard_records
+                :constant_narrowings, :guard_records, :bot_guard_classes, :declared_refinements
 
     # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
     # reference; the per-table readers stay on Scope so engine call sites and plugins are unaffected by the
@@ -60,13 +63,30 @@ module Rigor
     # Issue #1120 — `{refined class name => {method name => [refining module names]}}`: what each
     # `refine X do … end` block defines, visible only where a `using` of its module is in effect.
     def discovered_refinements = @discovery.discovered_refinements
+
+    # Issue #1673 (ADR-121 WD1) — the in-effect refinements at `node`: the refining-module names whose refinements
+    # Ruby applies there, ordered so a later activation comes later (the later one wins), each once at its first
+    # position, each `using`'d module expanded through its includes and prepends in CRuby's activation order.
+    # `declared` is a block source's modules, appended and expanded on the same terms; it defaults to this scope's
+    # {#declared_refinements}, a plugin-declared refined block's (#1667). An entry may be
+    # `Inference::InEffectRefinements::UNKNOWN`, which means any refinement may be in effect. A node another file
+    # wrote (a callee body typed under this file's scope) answers `declared` alone. Reads include edges, so it records
+    # the dependencies `Inference::InEffectRefinements.activated_modules` names; a consumer that asks for a method
+    # name also records `refinement:<name>` (`Inference::InEffectRefinements.refining_modules`).
+    def in_effect_refinements(node, declared = @declared_refinements)
+      Inference::InEffectRefinements.for_node(self, node, declared)
+    end
+
     # Issue #1367 — the project's `Inference::GlobalWriteCensus`, a `Set` of frozen entries.
     def discovered_global_write_census = @discovery.discovered_global_write_census
     def discovered_includes = @discovery.discovered_includes
     # Issue #1123 — `{qualified class or module name => [module names it `prepend`s, as written]}`, in
-    # instance-ancestor search order (nearest prepend first). Feeds {#prepends_of}, the one table that tells
-    # a `prepend` from an `include` at `def`-priority level.
-    def discovered_prepends = @discovery.discovered_prepends
+    # instance-ancestor search order (nearest prepend first). The one table that tells a `prepend` from an
+    # `include`: {ResolutionChain} reads it to put a prepended module ahead of the class.
+    # The plugin-facing view: each class's prepends once, nearest first. The discovery index itself keeps every
+    # statement (a repeated `prepend` is a no-op in Ruby, the first statement winning), and the resolution chain
+    # reads that raw list.
+    def discovered_prepends = @discovery.discovered_prepends.transform_values { |names| names.uniq.freeze }.freeze
     def discovered_extends = @discovery.discovered_extends
     def discovered_class_sources = @discovery.discovered_class_sources
     # Issue #644 — `{qualified constant name => Set[declaring file]}`; seeded only on an ADR-46 recording run.
@@ -85,9 +105,13 @@ module Rigor
     # Issue #1290 — the census names sharing `name`'s last segment that some write other than a memo `||=`
     # assigns: the ones that shadow an outer constant of the name, so the lexical ladder stops at them
     # (`Reflection.resolve_constant_type`). That asks once per constant reference, so a bare name is looked up
-    # as it stands rather than split.
+    # as it stands rather than split, and a qualified one is sliced after its last `::` rather than split into
+    # an Array of every segment ([#1502](https://github.com/rigortype/rigor/issues/1502)). The two agree on every
+    # name a parsed constant path spells. Only the `Foo::` Prism recovers from a syntax error differs, and no
+    # file with a parse error is typed.
     def shadowing_constant_names(name)
-      segment = name.include?("::") ? name.split("::").last : name
+      separator = name.rindex("::")
+      segment = separator ? name[(separator + 2)..] : name
       @discovery.constant_shadowers[segment] || EMPTY_BOUND_CONSTANT_NAMES
     end
 
@@ -173,7 +197,9 @@ module Rigor
     #   today.
     # - `receiver_name` is the variable's Symbol.
     # - `key` is the Ruby value of the literal index (Symbol / String / Integer). Non-literal keys
-    #   (`params[field]`) are not recorded; they have no stable address.
+    #   (`params[field]`) have no stable address for a recorded value. A `key?` guard with a non-literal key
+    #   (issue #1703) records an {Inference::KeyPresenceGuard::KeyExpr} here instead, with `receiver_kind`
+    #   `:const` allowed; its entry marks presence only.
     IndexedKey = Data.define(:receiver_kind, :receiver_name, :key)
 
     # Narrowing key for a no-arg / no-block method-call chain `receiver.method_name` (a "single-hop" chain per A1
@@ -241,12 +267,21 @@ module Rigor
     # analysis cannot see runs, so a call or block that may run project or unresolved code restores each recorded
     # binding to the union of this pre-guard type and its narrowed one ({#forget_guard_narrowings}). A write drops
     # the record ({#with_global}), and a name the frame-local special-variable machinery owns is never recorded.
+    # Issue #1446 — a class guard's narrowing of an instance variable is recorded too, keyed `[:ivar, :@name]`
+    # ({#with_guarded_ivar}), since that code may reach `self` and rebind it; a write drops it ({#without_ivar_guard}).
     EMPTY_GUARD_RECORDS = {}.freeze
+    # Issue #1446 — the classes a class guard narrowed a receiver to where the narrowing left it `bot`, keyed like
+    # {EMPTY_GUARD_RECORDS} with `[:local, :name]` too: `return unless @cb.is_a?(Proc)` binds `@cb` to `bot` when the
+    # guard is disjoint from its binding, but the value that passes it is a `Proc` (or a subclass of one), and a call
+    # on it dispatches on that class. `Inference::GuardRebinding` reads the class a `bot` receiver runs its methods
+    # on from here ({#bot_guard_classes_for}); a `bot` no class guard produced has no entry. A write or another
+    # narrowing of the name drops its entry, and a join keeps one only both arms hold.
+    EMPTY_BOT_GUARD_CLASSES = {}.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
                      :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED,
                      :EMPTY_FOLD_SAFE, :EMPTY_ORIGINS, :EMPTY_PUBLISHED_CONSTANT_SOURCED,
                      :EMPTY_PUBLISHED_CONSTANT_IVARS, :EMPTY_REPEATED_OR_WRITES,
-                     :EMPTY_CONSTANT_NARROWINGS, :EMPTY_GUARD_RECORDS
+                     :EMPTY_CONSTANT_NARROWINGS, :EMPTY_GUARD_RECORDS, :EMPTY_BOT_GUARD_CLASSES
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -287,7 +322,7 @@ module Rigor
       @plugin_typed_calls.key?(node)
     end
 
-    def initialize(
+    def initialize( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- one keyword and assignment per field
       environment:, locals:,
       fact_store: Analysis::FactStore.empty,
       self_type: nil,
@@ -302,6 +337,7 @@ module Rigor
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
       opaque_block_self: false,
+      block_self_unknown: false,
       singleton_class_body: false,
       lexical_nesting: nil,
       dynamic_origins: {}.compare_by_identity,
@@ -315,7 +351,9 @@ module Rigor
       repeated_or_writes: EMPTY_REPEATED_OR_WRITES,
       match_frame: nil,
       constant_narrowings: EMPTY_CONSTANT_NARROWINGS,
-      guard_records: EMPTY_GUARD_RECORDS
+      guard_records: EMPTY_GUARD_RECORDS,
+      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES,
+      declared_refinements: Inference::InEffectRefinements::EMPTY
     )
       @environment = environment
       @locals = locals
@@ -332,6 +370,7 @@ module Rigor
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @opaque_block_self = opaque_block_self
+      @block_self_unknown = block_self_unknown
       @singleton_class_body = singleton_class_body
       @lexical_nesting = lexical_nesting
       @dynamic_origins = dynamic_origins
@@ -346,6 +385,8 @@ module Rigor
       @match_frame = match_frame
       @constant_narrowings = constant_narrowings
       @guard_records = guard_records
+      @bot_guard_classes = bot_guard_classes
+      @declared_refinements = declared_refinements
       freeze
     end
 
@@ -358,6 +399,14 @@ module Rigor
       self
     end
 
+    # Issue #1703 — this scope with private copies of the identity-keyed side tables (dynamic, void and optimistic
+    # origins, plugin-typed calls), so a second walk from it — the `key?`-guarded re-walk — records into its own
+    # tables and never into the ones the file's analysis reads.
+    def with_isolated_side_tables
+      rebuild(dynamic_origins: @dynamic_origins.dup, void_origins: @void_origins.dup,
+              plugin_typed_calls: @plugin_typed_calls.dup, optimistic_origins: @optimistic_origins.dup)
+    end
+
     def optimistic_local(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_locals[name.to_sym])
     def optimistic_ivar(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_ivars[name.to_sym])
 
@@ -440,7 +489,8 @@ module Rigor
               # rvalue is one.
               published_constant_sourced: drop_published_constant_sourced_for(:local, name),
               local_origins: drop_origin(@local_origins, name),
-              optimistic_locals: keep_marks ? @optimistic_locals : drop_origin(@optimistic_locals, name))
+              optimistic_locals: keep_marks ? @optimistic_locals : drop_origin(@optimistic_locals, name),
+              bot_guard_classes: drop_bot_guard_class(:local, name))
     end
     private :bind_local
 
@@ -455,6 +505,39 @@ module Rigor
       rebuild(self_type: type)
     end
 
+    # Issue #1717 — installs the `self` a block body runs with when the engine KNOWS it: an ADR-16
+    # `block_as_methods:` match, `define_method`, or a `Class.new` / `refine` body (#319). Like
+    # {#with_self_type} it leaves the #316 mark alone; it also sets {#block_self_unknown?} to `keeps_unknown`,
+    # which a caller passes from {#block_self_narrowing_unknown?}. A nil `type` narrows nothing and keeps it.
+    #
+    # Issue #1695 — instance variables belong to `self`, so a narrowing onto a DIFFERENT `self` than the enclosing
+    # scope's also drops every instance-variable binding the body would otherwise inherit ({#without_ivar_bindings}):
+    # a `define_method` block in a class body runs on an instance, and the class body's `@label = nil` is the class
+    # object's ivar, not the one the block reads. The body's reads answer `Dynamic` until it writes them. A narrowing
+    # that keeps the caller's `self` (an ADR-16 `:lexical` entry) keeps them.
+    def with_block_self_type(type, keeps_unknown: false)
+      unknown = type.nil? ? @block_self_unknown : keeps_unknown
+      return rebuild(self_type: type, block_self_unknown: unknown) if type.nil? || type == @self_type
+
+      without_ivar_bindings(type, unknown)
+    end
+
+    # Issue #1717 — whether a block-self narrowing for `call_node`, asked from this (the CALLER's) scope, is
+    # built on an unknown `self`. `define_method` and an implicit- or `self`-receiver `block_as_methods:` match
+    # read the lexical `self`, which inside a block of unknown `self` is the enclosing method's, not the
+    # block's; a narrowing keyed on an explicit receiver (`Grape::API.namespace do`) does not depend on it.
+    #
+    # Issue #1759 — one narrowing is not: a `define_method` written directly in a `refine X` block
+    # ({REFINEMENT_BLOCK_SELF}) defines a method of the refinement, which runs on an instance of X, and the
+    # `Nominal[X]` it reads off the block's lexical `Singleton[X]` is that `self`.
+    def block_self_narrowing_unknown?(call_node)
+      return false unless @block_self_unknown
+      return false if @block_self_unknown == REFINEMENT_BLOCK_SELF && call_node.name == :define_method
+
+      receiver = call_node.receiver
+      receiver.nil? || receiver.is_a?(Prism::SelfNode)
+    end
+
     # Issue #652 — installs the body's REAL `Module.nesting`, innermost first, as recorded at declaration
     # time by `Inference::StatementEvaluator` (`["Admin::UsersController"]` for a compact
     # `class Admin::UsersController`, `["Admin::UsersController", "Admin"]` for the nested spelling). A
@@ -497,15 +580,52 @@ module Rigor
     # `Array#each` without knowing the callee. The flag is set at every block entry that leaves `self_type`
     # unnarrowed and is inherited by every scope derived inside the block; it never leaks past the block,
     # because `eval_call` returns the caller's scope unchanged.
+    #
+    # Entering also sets {#block_self_unknown?} (issue #1717), the separate mark `call.undefined-method` reads.
     def entering_opaque_block
-      return self if @opaque_block_self
+      return self if @opaque_block_self && @block_self_unknown == true
 
-      rebuild(opaque_block_self: true)
+      rebuild(opaque_block_self: true, block_self_unknown: true)
     end
 
     # True when this scope sits inside a block whose `self` is unmodelled ({#entering_opaque_block}).
     def opaque_block_self? = @opaque_block_self
 
+    # Issue #1717 — true when this scope sits in a block whose `self` the engine does not know, so an explicit
+    # `self.m` there is no evidence `m` is missing: the yielding method may `instance_exec` the block on another
+    # object. Read ONLY by `call.undefined-method`'s explicit-`self` exemption, and kept apart from
+    # {#opaque_block_self?} so that mark's reach (the top-level-def bind gate) is untouched. Set with
+    # {#entering_opaque_block} on the evaluator's block entries and by the indexer's walk of an unentered block
+    # ({#with_block_self_unknown}); cleared where a block's `self` is narrowed ({#with_block_self_type}) and, on
+    # the indexer's walk, at a `def` / `class` / `module` body, which the evaluator starts from a fresh scope.
+    def block_self_unknown? = @block_self_unknown ? true : false
+
+    # Issue #1759 — the {#block_self_unknown?} value a `refine X do … end` block body is entered with
+    # (`with_block_self_type(Singleton[X], keeps_unknown: REFINEMENT_BLOCK_SELF)`). It reads as unknown everywhere
+    # `true` does; what it adds is that the body's lexical `self` is X's singleton, which a `define_method` in it
+    # reads correctly ({#block_self_narrowing_unknown?}). A block nested in the body takes plain `true`.
+    REFINEMENT_BLOCK_SELF = :refinement
+
+    # Issue #1763 — true directly in a `refine X do … end` block body ({REFINEMENT_BLOCK_SELF}). The body's
+    # `self_type` is the `Singleton[X]` its implicit-self calls and `define_method` read, but the block runs on the
+    # refinement module, so a `self` read as a value (`x = self`) types as `Dynamic[top]` there.
+    def refinement_block_self? = @block_self_unknown == REFINEMENT_BLOCK_SELF
+
+    # The join of two arms' {#block_self_unknown?} values: `true` if either has it, else either's mark.
+    def merged_block_self_unknown(other)
+      return true if @block_self_unknown == true || other == true
+
+      @block_self_unknown || other
+    end
+    private :merged_block_self_unknown
+
+    # Issue #1717 — sets {#block_self_unknown?} to `flag`, leaving every other field (the #316 mark included).
+    def with_block_self_unknown(flag)
+      return self if @block_self_unknown == flag
+
+      rebuild(block_self_unknown: flag)
+    end
+
     # Issue #963 — marks the body of a `class << ...` as such. Inside it `self` is the SINGLETON class, which
     # Rigor models with the same `Singleton[X]` carrier a `class X` body gets, so the carrier alone cannot say
     # which of the two a scope came from. The distinction decides what `define_method` does: in a `class << self`
@@ -523,6 +643,19 @@ module Rigor
       rebuild(singleton_class_body: flag)
     end
 
+    # Issue #1667 (ADR-121 WD5) — this scope with `names` appended to {#declared_refinements}, each once at its first
+    # position: the modules a plugin-declared refined block (`block_as_methods:` `refinements:`) runs under. Stamped
+    # at block entry and inherited by every scope derived inside the body, nested blocks included, and by a `def` or
+    # class body written in it (`StatementEvaluator#build_fresh_body_scope`), as CRuby's cref is.
+    def with_declared_refinements(names)
+      return self if names.empty?
+
+      merged = (@declared_refinements | names).freeze
+      return self if merged == @declared_refinements
+
+      rebuild(declared_refinements: merged)
+    end
+
     # True when this scope IS a `class << ...` body (not merely inside one lexically — a `def` reached from it
     # answers false).
     def singleton_class_body? = @singleton_class_body
@@ -557,6 +690,11 @@ module Rigor
     end
 
     def with_ivar(name, type)
+      bind_ivar(name, type, @guard_records)
+    end
+
+    # The one body behind {#with_ivar} and {#with_guarded_ivar}, which differ only in the guard records they leave.
+    def bind_ivar(name, type, guard_records)
       new_indexed_narrowings = drop_indexed_narrowings_for(:ivar, name)
       new_chain_narrowings = drop_chain_narrowings_for(:ivar, name)
       # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live: drop any declaration-sourced mark so
@@ -568,8 +706,50 @@ module Rigor
               declaration_sourced: drop_declaration_sourced_for(:ivar, name),
               published_constant_sourced: drop_published_constant_sourced_for(:ivar, name),
               ivar_origins: drop_origin(@ivar_origins, name),
-              optimistic_ivars: drop_origin(@optimistic_ivars, name))
+              optimistic_ivars: drop_origin(@optimistic_ivars, name),
+              guard_records: guard_records,
+              bot_guard_classes: drop_bot_guard_class(:ivar, name))
+    end
+    private :bind_ivar
+
+    # Issue #1695 — this scope with no instance-variable binding and none of the per-ivar state that rides on one:
+    # the narrowings keyed on or rooted at an ivar, its ADR-58 and #667 marks, ADR-82 origins, #286 optimistic marks
+    # and #1446 guard records, the state {#bind_ivar} drops for one name. It installs {#with_block_self_type}'s
+    # `self_type` and unknown-`self` mark in the same rebuild.
+    def without_ivar_bindings(self_type, block_self_unknown)
+      rebuild(
+        self_type: self_type,
+        block_self_unknown: block_self_unknown,
+        ivars: EMPTY_VAR_BINDINGS,
+        indexed_narrowings: reject_kept(@indexed_narrowings) { |k, _| ivar_indexed_key?(k) },
+        method_chain_narrowings: reject_kept(@method_chain_narrowings) { |k, _| k.receiver_kind == :ivar },
+        declaration_sourced: reject_kept(@declaration_sourced) { |ref| ref[0] == :ivar },
+        published_constant_sourced: reject_kept(@published_constant_sourced) { |ref| ref[0] == :ivar },
+        ivar_origins: EMPTY_ORIGINS,
+        optimistic_ivars: EMPTY_ORIGINS,
+        guard_records: reject_kept(@guard_records) { |key, _| key[0] == :ivar },
+        bot_guard_classes: reject_kept(@bot_guard_classes) { |key, _| key[0] == :ivar }
+      )
     end
+    private :without_ivar_bindings
+
+    # `collection` without the entries the block selects, or `collection` itself when it selects none. It keeps the
+    # collection's class: `Set#reject` answers an Array, which a Set carrier's readers (`merge`, `|`, `==`) reject.
+    def reject_kept(collection, &)
+      return collection if collection.empty? || collection.none?(&)
+
+      collection.dup.delete_if(&).freeze
+    end
+    private :reject_kept
+
+    # An indexed narrowing of an ivar, or of a `key?` guard's key read from one ({#key_guard_rooted_at?}).
+    def ivar_indexed_key?(indexed_key)
+      return true if indexed_key.receiver_kind == :ivar
+
+      key = indexed_key.key
+      key.is_a?(Inference::KeyPresenceGuard::KeyExpr) && key.root[0] == :ivar
+    end
+    private :ivar_indexed_key?
 
     # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only provenance is the class-ivar index.
     # Unlike `with_ivar` this binds the type AND records the declaration-sourced mark in one transition.
@@ -680,7 +860,8 @@ module Rigor
       name = name.to_sym
       written = rebuild(globals: @globals.merge(name => type).freeze,
                         declaration_sourced: drop_declaration_sourced_for(:global, name),
-                        guard_records: drop_guard_record(:global, name))
+                        guard_records: drop_guard_record(:global, name),
+                        bot_guard_classes: drop_bot_guard_class(:global, name))
       alias_name = STDOUT_ALIASES[name]
       alias_name ? written.forget_guard_narrowing_of(:global, alias_name) : written
     end
@@ -717,7 +898,28 @@ module Rigor
       records = record ? add_guard_record([:global, name].freeze, pre_guard) : drop_guard_record(:global, name)
       rebuild(globals: @globals.merge(name => type).freeze,
               declaration_sourced: drop_declaration_sourced_for(:global, name),
-              guard_records: records)
+              guard_records: records,
+              bot_guard_classes: drop_bot_guard_class(:global, name))
+    end
+
+    # Issue #1446 — binds the instance variable `name` to `type` on a class guard's edge, recording `pre_guard` as
+    # {#with_guarded_global} does. The truthiness, `nil?`, `&.` and `respond_to?` guards narrow an instance variable
+    # through {#with_ivar} and record nothing.
+    def with_guarded_ivar(name, type, pre_guard)
+      name = name.to_sym
+      bind_ivar(name, type, add_guard_record([:ivar, name].freeze, pre_guard))
+    end
+
+    # Issue #1446 — this scope with no guard record for the instance variable `name`: what a write to it leaves.
+    # {#with_ivar} keeps the record, since a narrowing binds through it too.
+    def without_ivar_guard(name)
+      records = drop_guard_record(:ivar, name.to_sym)
+      records.equal?(@guard_records) ? self : rebuild(guard_records: records)
+    end
+
+    # Issue #1446 — true when a class guard's narrowing of the instance variable `name` is live.
+    def guard_narrowed_ivar?(name)
+      !@guard_records.empty? && @guard_records.key?([:ivar, name.to_sym])
     end
 
     # Issue #1429 — the type a guard narrowed the constant reference `key` to, or nil.
@@ -731,7 +933,23 @@ module Rigor
     # {#with_guarded_global} does.
     def with_constant_narrowing(key, type, pre_guard)
       rebuild(constant_narrowings: @constant_narrowings.merge(key => type).freeze,
-              guard_records: add_guard_record([:constant, key].freeze, pre_guard))
+              guard_records: add_guard_record([:constant, key].freeze, pre_guard),
+              bot_guard_classes: drop_bot_guard_class(:constant, key))
+    end
+
+    # Issue #1446 — this scope with `class_names` recorded as the classes a class guard narrowed the receiver `[kind,
+    # name]` to, where the guard left it `bot` ({EMPTY_BOT_GUARD_CLASSES}). Call it after the narrowing, which drops
+    # any earlier entry.
+    def with_bot_guard_classes(kind, name, class_names)
+      key = [kind, kind == :constant ? name : name.to_sym].freeze
+      rebuild(bot_guard_classes: @bot_guard_classes.merge(key => class_names.dup.freeze).freeze)
+    end
+
+    # Issue #1446 — the classes a class guard narrowed the `bot` receiver `[kind, name]` to, or nil.
+    def bot_guard_classes_for(kind, name)
+      return nil if @bot_guard_classes.empty?
+
+      @bot_guard_classes[[kind, name]]
     end
 
     # Issue #1429 — every constant reference whose last segment is `name` with no narrowing: what a write to a constant
@@ -741,7 +959,9 @@ module Rigor
       return self if keys.empty?
 
       records = @guard_records.reject { |(kind, key), _| kind == :constant && keys.include?(key) }
-      rebuild(constant_narrowings: @constant_narrowings.except(*keys).freeze, guard_records: records.freeze)
+      classes = @bot_guard_classes.except(*keys.map { |key| [:constant, key] }).freeze
+      rebuild(constant_narrowings: @constant_narrowings.except(*keys).freeze, guard_records: records.freeze,
+              bot_guard_classes: classes)
     end
 
     # Issue #1429 — the constant reference `key` with no narrowing.
@@ -749,11 +969,12 @@ module Rigor
       return self unless @constant_narrowings.key?(key)
 
       rebuild(constant_narrowings: @constant_narrowings.except(key).freeze,
-              guard_records: @guard_records.except([:constant, key]).freeze)
+              guard_records: @guard_records.except([:constant, key]).freeze,
+              bot_guard_classes: drop_bot_guard_class(:constant, key))
     end
 
-    # True when a guard's narrowing of a global or constant is live, the state {#forget_guard_narrowings} drops and
-    # so the gate on every scan that decides whether to.
+    # True when a guard's narrowing of a global, constant or instance variable is live, the state
+    # {#forget_guard_narrowings} drops and so the gate on every scan that decides whether to.
     def guard_narrowed?
       !@guard_records.empty?
     end
@@ -762,23 +983,19 @@ module Rigor
     # the union of its narrowed type and the binding the guard narrowed, and no record is left. The union, not the
     # pre-guard binding alone, because the code may leave the value as it was: `$stdout.is_a?(StringIO)`, then a
     # helper, reads `IO | StringIO`, which keeps `$stdout.string` quiet as the guard intended.
+    #
+    # Issue #1446 — an instance variable a class guard narrowed is restored the same way.
     def forget_guard_narrowings
       return self if @guard_records.empty?
 
-      globals = @globals
-      constants = @constant_narrowings
+      tables = { global: @globals, constant: @constant_narrowings, ivar: @ivars }
       @guard_records.each do |(kind, name), pre_guard|
-        if kind == :global
-          current = globals[name]
-          globals = globals.merge(name => Type::Combinator.union(pre_guard, current)) if current
-        else
-          current = constants[name]
-          constants = constants.merge(name => Type::Combinator.union(pre_guard, current)) if current
-        end
+        table = tables.fetch(kind)
+        current = table[name]
+        tables[kind] = table.merge(name => Type::Combinator.union(pre_guard, current)) if current
       end
-      rebuild(globals: globals.frozen? ? globals : globals.freeze,
-              constant_narrowings: constants.frozen? ? constants : constants.freeze,
-              guard_records: EMPTY_GUARD_RECORDS)
+      globals, constants, ivars = tables.values_at(:global, :constant, :ivar).map { |t| t.frozen? ? t : t.freeze }
+      rebuild(globals: globals, constant_narrowings: constants, ivars: ivars, guard_records: EMPTY_GUARD_RECORDS)
     end
 
     # Issue #1362 (ADR-58 parity, ADR-117 Decision point 2) — used by the method-entry and top-level seeds to bind a
@@ -998,6 +1215,18 @@ module Rigor
       @self_type.nil?
     end
 
+    # ADR-119 WD1 — the RAW slot of the def tables for `class_name` and `method_name`: the instance side by default,
+    # the singleton side for `kind: :singleton`. The slot is a live `Prism::DefNode` or a {Inference::DefHandle}
+    # (ADR-85 WD3), returned as stored: no dependency recording and no handle resolution. ADR-119 C1d/C2 decide how
+    # a contested slot answers here. Callers that need a node go through {#user_def_for} or {#singleton_def_for}.
+    # The `same_slot` census reads of this slot stay justified: certainty reaches them through the declaration
+    # signature the producer fingerprints (C1d-a), not through this accessor.
+    def def_node_slot(class_name, method_name, kind = :instance)
+      table = kind == :singleton ? discovered_singleton_def_nodes : discovered_def_nodes
+      per_class = table[class_name]
+      per_class && per_class[method_name]
+    end
+
     # v0.0.2 #5 — per-class table mapping `method_name (Symbol) → Prism::DefNode`. Populated by `ScopeIndexer`
     # alongside `discovered_methods` for instance-side defs only (singleton-side and `define_method`-introduced
     # methods do not contribute a static body the engine can re-type). Consumed by `ExpressionTyper` to do
@@ -1085,12 +1314,15 @@ module Rigor
       same_file_top_level_def?(method_name) ? node : nil
     end
 
+    # ADR-119 WD1 errata, deliberately unchanged: this compares the recorded site's FILE with the call's file, and
+    # which file a def sits in does not depend on whether it executes. The `<toplevel>` slots are contested
+    # truthfully (ADR-119 C1d-a) but unread until C2 makes the top-level reader decline on them.
     def same_file_top_level_def?(method_name)
       key = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
       site = discovered_def_sources.dig(key, method_name.to_sym)
       return true if site.nil? || @source_path.nil?
 
-      File.expand_path(site.sub(/:\d+\z/, "")) == File.expand_path(@source_path)
+      File.absolute_path(site.sub(/:\d+\z/, "")) == File.absolute_path(@source_path)
     end
     private :same_file_top_level_def?
 
@@ -1272,32 +1504,6 @@ module Rigor
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
-    # Issue #1123 — the modules `class_name` `prepend`s, in instance-ancestor SEARCH order: the nearest
-    # prepend first, so `prepend A; prepend B` answers `["B", "A"]` and `prepend A, B` keeps `["A", "B"]`
-    # (each Ruby statement's argument list lands as one unit, ahead of the earlier statements'). Read by
-    # {#user_def_through_ancestors}'s prepend wedge — Ruby inserts a prepended module, and its own ancestry,
-    # IMMEDIATELY BEFORE the class that prepends it, so these names are searched ahead of the class's own
-    # `def`s. Empty for a class the project never prepends, which is the behaviour every class had before
-    # `prepend` was ordered at all.
-    #
-    # The same names ALSO appear in {#includes_of} — that table answers "which modules does this class
-    # carry", which is what the arity, visibility, reflection and constant-scope consumers ask, and a
-    # prepended module does contribute instance methods. This table adds the ORDER and the KIND; it never
-    # removes a name from the other one.
-    #
-    # The class dependency is recorded only on a HIT, as {#data_member_layout} does: the wedge asks this
-    # for every class the walk visits, so recording on a miss would give a caller file an ancestry edge on
-    # a class that prepends nothing — an edge where ADR-46 slice 4 keeps method-body reads at
-    # symbol granularity.
-    def prepends_of(class_name)
-      names = @discovery.discovered_prepends[class_name.to_s]
-      return EMPTY_MIXIN_NAMES if names.nil?
-
-      record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
-      names
-    end
-    private :prepends_of
-
     # Issue #898 — the module names `extend`ed onto `class_name`'s SINGLETON, as written, gathered up the
     # as-written superclass chain because a singleton class inherits its superclass's singleton class
     # (`class Base; extend Comparable; end; class Widget < Base; end` leaves `Widget.is_a?(Comparable)`
@@ -1326,224 +1532,145 @@ module Rigor
       names.uniq
     end
 
-    # ADR-24 slice 2 — the user-side ancestor walk: resolves `method_name` against `class_name`'s own `def`s,
-    # then breadth-first through its included / prepended modules (mixins first, as Ruby orders them) and its
-    # superclass chain. Returns `[def_node, owner]`, or `[nil, nil]` when nothing in the project defines it.
-    # RBS-known / third-party ancestors resolve to no discovered class and end that branch.
+    # ADR-24, amended for #1567 / #1568 / #1570 / #1571 — every reader below answers in Ruby's linearised
+    # ancestor order, read from {ResolutionChain} (an internal class: `Scope`'s own surface is the plugin API
+    # `spec/rigor/public_api_drift_spec.rb` pins, and the chain is not part of it). None walks `includes_of` /
+    # `superclass_of` / the extends table itself; `spec/rigor/scope/ancestry_walker_detection_spec.rb` fails on
+    # a method that does. Each keeps its signature and its return type exactly: only WHICH definer it answers
+    # moved. `name_memo:` is still accepted and no longer needed — the chain memoises name resolution itself.
+    UNUSED_NAME_MEMO = {}.freeze
+    private_constant :UNUSED_NAME_MEMO
     #
-    # It lives HERE, not in a consumer, because it reads nothing but this scope's frozen discovery index
-    # (`user_def_for` / `includes_of` / `superclass_of` / the `discovered_*` tables) — the same property that
-    # lets `ExpressionTyper` memoise its results run-wide. Two callers depend on that single answer:
-    # `ExpressionTyper#compute_user_def_with_owner`, which wraps it in the run-scoped memo for the dispatch hot
-    # path, and {Inference::MethodDispatcher::StructMaterialization}, whose `.with` guard must see a `with`
-    # contributed by an included module. They forked once — the guard resolved own-class-only while the
-    # dispatcher walked ancestors — and answered differently about the same receiver expression (#598 review).
+    # Every reader below asks {ResolutionChain#settle} whether its chain answer stands, and where it does not
+    # answers what the walk it replaced answered ({ResolutionChain::MasterOrder}) — the tables cannot say which
+    # world ran, and a disagreement is no reason to answer anything new.
+
+    # ADR-24 slice 2 — the user-side method lookup: the first project `def` of `method_name` along
+    # `class_name`'s instance chain, as `[def_node, owner]`, or `[nil, nil]` when nothing the project declares
+    # defines it. An external ancestor is passed over, as before: a caller asking "does the project define
+    # this" must not read an RBS module's declaration as absence (#1572 is the typing read that will stop
+    # there).
     #
-    # `name_memo` is a CACHE, not semantics: the per-edge as-written-name resolutions, so a caller resolving
-    # many methods against one class pays each ancestor edge once. Omit it and the walk is identical, just
-    # uncached.
+    # It lives HERE, not in a consumer, because it reads nothing but this scope's frozen discovery index — the
+    # property that lets `ExpressionTyper` memoise its results run-wide. `ExpressionTyper#compute_user_def_with_owner`
+    # wraps it in that memo for the dispatch hot path, and {Inference::MethodDispatcher::StructMaterialization}'s
+    # `.with` guard reads the same answer (#598 review).
     #
-    # Issue #1123 — a prepended module is searched through {#prepends_of} AHEAD of the class's own `def`s
-    # ({#prepend_wedge_names}), because Ruby inserts it, and its own ancestry, immediately before the class
-    # that prepends it: `class Base; def speak = "base"; end; Base.prepend(Loud)` answers `Loud#speak`, and
-    # the `super` in that body then reaches `Base#speak`. An included module still
-    # sits AFTER the class in this walk, but — since #1173 — `includes_of` feeds the mixin step in
-    # instance-ancestor search order, so `include A; include B` searches B first the way CRuby does. The
-    # wedge is searched at EVERY node, not just the entry class: a prepend on an ancestor (`class Sub <
-    # Base` where `Base` prepends a module) wins for the subclass too, exactly as Ruby dispatches it.
-    def user_def_through_ancestors(class_name, method_name, name_memo: {})
-      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 ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+    # #1567 — the walk was breadth-first until the chain replaced it: `class C < Base; include A` with `A`
+    # including `M` answered `Base#foo` where Ruby calls `M#foo`. The prepend wedge #1123 added (a prepended
+    # module searched ahead of the class's own `def`s) and the include search order #1173 fixed are both
+    # positions on the chain now, at every class on it.
+    def user_def_through_ancestors(class_name, method_name, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :instance, :methods)
+      found = first_user_def(chain, method_name)
+      owner = found&.last
+      if chain.settle(self, owner, owner: owner) { |retro| first_user_def(retro, method_name)&.last } == :master
+        found = master_user_def(class_name.to_s, method_name)
+      end
+      return found if found
 
-        wedge_hit = search_prepend_wedge(current, method_name, name_memo, seen)
-        return wedge_hit if wedge_hit
+      chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
+    end
 
-        found = user_def_for(current, method_name)
-        return [found, current] if found
+    def first_user_def(chain, method_name)
+      chain.search(self) do |entry|
+        next if entry.external?
 
-        enqueue_ancestors(current, queue, name_memo)
+        node = user_def_for(entry.name, method_name)
+        [node, entry.name] if node
       end
-      [nil, nil]
     end
 
-    # Issue #1123 — the `[def_node, owner]` pair a class's prepend wedge answers `method_name` with, or nil
-    # when nothing in the wedge defines it and the walk should ask the class's own `def`s next.
-    #
-    # Every name the wedge takes is marked on `seen`, the SAME set the walk's breadth-first step uses: a
-    # prepended module also sits in `includes_of`, so the mixin step would otherwise re-ask a name the wedge
-    # already answered — and, more importantly, marking it there keeps a `prepend` graph that loops back on
-    # the walk (a prepended module reached again from somewhere else) from being expanded twice.
-    def search_prepend_wedge(class_name, method_name, name_memo, seen)
-      prepend_wedge_names(class_name, name_memo).each do |name|
-        next if seen[name]
-
-        seen[name] = true
-        found = user_def_for(name, method_name)
-        return [found, name] if found
+    def master_user_def(class_name, method_name)
+      names = ResolutionChain::MasterOrder.definer_sequence(self, class_name)
+      names.each { |name| record_class_dependency(name) } if Analysis::DependencyRecorder.active?
+      names.each do |name|
+        node = user_def_for(name, method_name)
+        return [node, name] if node
       end
       nil
     end
-
-    # Issue #1123 — the qualified names the instance MRO searches ahead of `class_name`'s own definitions,
-    # in the order it searches them: for each of `class_name`'s prepends, nearest first, that module's own
-    # prepend wedge, then the module itself, then its includes and superclass.
-    #
-    # A prepended module's own ancestry is part of the wedge because Ruby inserts the whole sub-chain with
-    # it — `module Loud; include Loud::Prefix; end` prepended into `Base` puts `Loud::Prefix` ahead of
-    # `Base`, so the wedge has to reach it. `seen` is shared across one wedge computation and guards a cyclic
-    # `prepend`/`include` graph (and the overlap with `includes_of`, which carries the prepend names too);
-    # the walk's own set is applied by {#search_prepend_wedge}, and each name is expanded at most once.
-    def prepend_wedge_names(class_name, name_memo, seen = {})
-      out = []
-      prepends_of(class_name).each do |raw|
-        resolved = resolve_ancestor_class_name(class_name, raw, name_memo)
-        next if resolved.nil? || seen[resolved]
-
-        seen[resolved] = true
-        out.concat(subchain_names(resolved, name_memo, seen))
-      end
-      out
-    end
-
-    # Issue #1123 — appends `node`'s own instance search order to `out`: its prepend wedge, the node
-    # itself, then its includes and superclass, each expanded the same way. Since #1173 the include
-    # half is `includes_of`'s search order — the ORDER inside a prepended module's own include list is
-    # not re-derived here, only read.
-    def subchain_names(node, name_memo, seen)
-      out = prepend_wedge_names(node, name_memo, seen)
-      out << node
-      (includes_of(node) + [superclass_of(node)].compact).each do |raw|
-        resolved = resolve_ancestor_class_name(node, raw, name_memo)
-        next if resolved.nil? || seen[resolved]
-
-        seen[resolved] = true
-        out.concat(subchain_names(resolved, name_memo, seen))
+    private :first_user_def, :master_user_def
+
+    # Issue #731 — the singleton-side twin of {#user_def_through_ancestors}: the first `def self.` /
+    # `class << self` body of `method_name` along `class_name`'s singleton chain, as `[def_node, owner]`, or
+    # `[nil, nil]` — each class object's own table, then the modules it extends in Ruby's order, then the
+    # superclass's. `ScopeIndexer` folds an extended module's own `def`s into the extender's table, so those
+    # answer at the extender; a module the extended one includes is its own entry (#1567's singleton shape:
+    # `class C < Base; extend A` with `A` including `M` is `M#foo`, not `Base.foo`). Where the chain does
+    # not stand, the answer is the class objects' alone, as the superclass-only walk this replaced gave.
+    def singleton_def_through_ancestors(class_name, method_name, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :singleton, :methods)
+      found = first_singleton_def(chain, method_name)
+      owner = found&.last
+      if chain.settle(self, owner, owner: owner) { |retro| first_singleton_def(retro, method_name)&.last } == :master
+        found = first_singleton_def(chain, method_name, :singleton)
       end
-      out
-    end
-    private :search_prepend_wedge, :prepend_wedge_names, :subchain_names
-
-    # Issue #731 — the singleton-side twin of {#user_def_through_ancestors}: resolves `method_name` against
-    # `class_name`'s own `def self.` / `class << self` bodies, then up the SUPERCLASS chain. Returns
-    # `[def_node, owner]`, or `[nil, nil]`.
-    #
-    # Superclasses only, and that is the whole shape of class-method inheritance in Ruby: a subclass
-    # inherits its parent's class methods, while an `include`d module contributes INSTANCE methods and its
-    # own `def self.x` is not callable on the includer. `extend M` needs no walk either — `ScopeIndexer`
-    # folds an extend into the extender's own singleton entries before the table is frozen — so the one
-    # edge this misses is a module's singleton surface reached through some other route, which nothing
-    # resolves today.
-    def singleton_def_through_ancestors(class_name, method_name, name_memo: {})
-      queue = [class_name.to_s]
-      seen = {}
-      visited = 0
-      until queue.empty?
-        current = queue.shift
-        next if current.nil? || seen[current]
+      return found if found
 
-        seen[current] = true
-        visited += 1
-        return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+      chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
+    end
 
-        found = singleton_def_for(current, method_name)
-        return [found, current] if found
+    def first_singleton_def(chain, method_name, side = nil)
+      chain.search(self, side: side) do |entry|
+        next if entry.external?
 
-        enqueue_ancestors(current, queue, name_memo, mixins: false)
+        name = entry.name
+        node = entry.side == :singleton ? singleton_def_for(name, method_name) : user_def_for(name, method_name)
+        [node, entry.name] if node
       end
-      [nil, nil]
     end
+    private :first_singleton_def
 
     # Issue #633 — the ancestors a project class reaches that the project itself does NOT declare: the
-    # `< StandardError` / `< Array` superclasses and the `include Comparable` mixins the two walks above
-    # deliberately drop, gathered depth-first over the project ancestry (an included module's own
-    # sub-chain precedes the includer's superclass edge) so an inherited edge counts too — and, since
-    # #1173, so the groups arrive in instance-ancestor search order for the caller that adopts the
-    # FIRST answering one.
+    # `< StandardError` / `< Array` superclasses and the `include Comparable` mixins, as the CANDIDATE LIST for
+    # each as-written name ({#ancestor_name_candidates}: the nesting spellings first, the bare name last), in
+    # Ruby's order along the instance chain — the order the caller that adopts the FIRST answering one (#1173)
+    # depends on. Resolving a candidate means asking the RBS environment, which this frozen-index read does
+    # not do; the caller takes the first candidate its own oracle knows. Where the chain does not stand, the
+    # groups are the depth-first ones the walk this replaced emitted.
     #
-    # Each entry is the CANDIDATE LIST for one as-written name ({#ancestor_name_candidates}: the nesting
-    # spellings first, the bare name last), not a resolved class — resolving it means asking the RBS
-    # environment, which this frozen-index walk does not read. The caller takes the first candidate its own
-    # oracle knows and ignores the rest, the same "most-qualified first" order the project-side resolution
-    # uses.
-    # Issue #527 slice 1 — `mixins: false` follows the SUPERCLASS chain only. Ruby reaches an included
-    # module's methods too, so the default answers the whole ancestry; a consumer resolving one KIND of
-    # inheritance edge at a time (the dispatch arm lands `< Hash` before `include Enumerable`) narrows
-    # it, the same way {#singleton_def_through_ancestors} narrows {#enqueue_ancestors}.
-    def external_ancestor_name_candidates(class_name, name_memo: {}, mixins: true)
-      groups = []
-      collect_external_ancestors(class_name.to_s, groups, name_memo, mixins, {}, [0])
+    # Issue #527 slice 1 — `mixins: false` answers the superclass edge only: a consumer resolving one KIND of
+    # inheritance edge at a time (the dispatch arm lands `< Hash` before `include Enumerable`) narrows it, and
+    # records only the superclass chain it read.
+    def external_ancestor_name_candidates(class_name, name_memo: UNUSED_NAME_MEMO, mixins: true) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :instance, :methods)
+      groups = external_groups(chain, mixins)
+      if chain.settle(self, groups) { |retro| external_groups(retro, mixins) } == :master
+        groups = ResolutionChain::MasterOrder.external_groups(self, class_name.to_s, mixins)
+      end
+      if Analysis::DependencyRecorder.active?
+        mixins ? chain.record(self) : chain.level_classes.each { |name| record_class_dependency(name) if name }
+      end
+      # Issue #527 — the cut is a budget event, not an answer: consumers read the groups as "the ancestors
+      # this class reaches", so a short list must be visible in `--stats` beside the other walks' exhaustions.
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT) if chain.truncated?
       groups
     end
 
-    # One node of {#external_ancestor_name_candidates}: the project-declared ancestors continue the walk,
-    # everything else is reported as a candidate list.
-    #
-    # Issue #1173 — the walk is depth-first pre-order, not breadth-first: a resolved ancestor's own
-    # edges are followed BEFORE the next sibling edge, because Ruby inserts an included module's whole
-    # sub-chain ahead of the includer's superclass (`class C < Hash; include M` where `M` itself
-    # includes `Widen` chains `C → M → Widen → Hash`; BFS would report `Hash` ahead of `Widen`). Each
-    # node's edges still go includes-then-superclass, and `includes_of` is already search order, so the
-    # emitted groups arrive in MRO order — which the #1173 include arm depends on when two ancestors
-    # both declare the name.
-    def collect_external_ancestors(current, groups, name_memo, mixins, seen, visited)
-      return if current.nil? || seen[current]
-
-      seen[current] = true
-      visited[0] += 1
-      if visited[0] > ANCESTOR_WALK_LIMIT
-        # Issue #527 — the give-up is a budget event, not an answer. Consumers read the groups as
-        # "the ancestors this class reaches", so a truncated list must be visible in `--stats`
-        # alongside the other walks' exhaustions rather than silently short. Hit once: every node
-        # visited past the limit returns here too, and only the first should count.
-        Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT) if visited[0] == ANCESTOR_WALK_LIMIT + 1
-        return
-      end
-
-      raw_names = mixins ? includes_of(current).dup : []
-      raw_super = superclass_of(current)
-      raw_names << raw_super if raw_super
-      raw_names.each do |raw|
-        resolved = resolve_ancestor_class_name(current, raw, name_memo)
-        if resolved
-          collect_external_ancestors(resolved, groups, name_memo, mixins, seen, visited)
-        else
-          groups << ancestor_name_candidates(current, raw)
-        end
-      end
+    def external_groups(chain, mixins)
+      chain.entries.filter_map { |entry| entry.candidates if entry.external? && (mixins || entry.superclass_edge) }
     end
-    private :collect_external_ancestors
+    private :external_groups
 
-    # The BFS node cap; a hierarchy past it gives up rather than walking unboundedly (ADR-41 WD4).
-    ANCESTOR_WALK_LIMIT = 100
+    # The budget {ResolutionChain::LIMIT} enforces; a hierarchy past it gives up rather than reading an answer
+    # off a cut chain (ADR-41 WD4).
+    ANCESTOR_WALK_LIMIT = ResolutionChain::LIMIT
 
     EMPTY_HEADER_NESTING = [].freeze
     private_constant :EMPTY_HEADER_NESTING
 
-    # The answer for a class that prepends nothing — the common case, so the wedge does not allocate a
-    # fresh empty list per visited node. Shared and frozen, and never handed to a caller that could
-    # mutate it ({#prepends_of} is private to this walk).
-    EMPTY_MIXIN_NAMES = [].freeze
-    private_constant :EMPTY_MIXIN_NAMES
-
     def ancestor_walk_gave_up
       Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
       [nil, nil]
     end
+    private :ancestor_walk_gave_up
 
-    # Issue #723 — the same ancestor walk as {#user_def_through_ancestors}, asked of the DISCOVERY table
-    # rather than the def-node table: does the project define `method_name` on `class_name` or on any
-    # ancestor the project itself declares? The two tables are not interchangeable —
-    # `discovered_methods` also carries `define_method`, `attr_*` and the whole singleton side, none of
-    # which contributes a `Prism::DefNode` — and the suppression probe shared by the `call.*` check rules
-    # needs the broader one.
+    # Issue #723 — the question {#user_def_through_ancestors} asks, asked of the DISCOVERY table rather than
+    # the def-node table: does the project define `method_name` on `class_name` or on any ancestor the project
+    # itself declares? The two tables are not interchangeable — `discovered_methods` also carries
+    # `define_method`, `attr_*` and the whole singleton side, none of which contributes a `Prism::DefNode` —
+    # and the suppression probe shared by the `call.*` check rules needs the broader one.
     #
     # Why it must walk at all: `Analysis::CheckRules#source_declared_method?` asked `discovered_method?`,
     # which is keyed on the receiver's OWN name, while the typer resolves the same call through this
@@ -1551,72 +1678,47 @@ module Rigor
     # `call.undefined-method` on a method `dump_type` resolved on the same line of the same run — writing
     # MORE RBS made the run worse, the incentive #653 removed for plugin-typed calls.
     #
-    # `kind: :singleton` follows the superclass chain ONLY: a class method is inherited by a subclass, but
-    # an `include`d module contributes instance methods and its own `def self.x` is not callable on the
-    # includer. `extend M` is not lost to that narrowing — `Inference::ScopeIndexer` folds an extend into
-    # the extender's own singleton entries before this table is frozen.
-    def discovered_method_through_ancestors?(class_name, method_name, kind, name_memo: {})
+    # `kind: :singleton` reads the singleton chain: the class objects' own methods (an extended module's are
+    # folded into its extender's) and the instance methods of the modules they extend and those modules'
+    # includes. Existence is a union, so the chain's two worlds, which hold the same modules, agree on it.
+    def discovered_method_through_ancestors?(class_name, method_name, kind, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
       return false if class_name.nil?
 
-      queue = [class_name.to_s]
-      seen = {}
-      visited = 0
-      until queue.empty?
-        current = queue.shift
-        next if current.nil? || seen[current]
+      chain = ResolutionChain.for(self, class_name.to_s, kind == :singleton ? :singleton : :instance, :methods)
+      found = chain.search(self) do |entry|
+        next false if entry.external?
 
-        seen[current] = true
-        visited += 1
-        # Budget exhaustion is uncertainty, not absence: answering "not declared" here would hand a
-        # `call.undefined-method` a fired verdict it has no evidence for. Suppress and record the hit.
-        if visited > ANCESTOR_WALK_LIMIT
-          Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
-          return true
-        end
-
-        return true if discovered_method?(current, method_name, kind)
-
-        enqueue_ancestors(current, queue, name_memo, mixins: kind != :singleton)
+        discovered_method?(entry.name, method_name, entry.side == :singleton ? :singleton : kind_for(kind))
       end
-      false
-    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 the
-    # nesting `current`'s declaration header is written in ({#ancestor_name_candidates}); names that resolve
-    # to no project class/module are dropped. `mixins: false` walks the superclass chain alone, for the
-    # singleton-side question where an `include` contributes nothing.
-    def enqueue_ancestors(current, queue, name_memo, mixins: true)
-      if mixins
-        includes_of(current).each do |raw|
-          resolved = resolve_ancestor_class_name(current, raw, name_memo)
-          queue.push(resolved) if resolved
-        end
-      end
-      raw_super = superclass_of(current)
-      return if raw_super.nil?
+      return true if found
+      # Budget exhaustion is uncertainty, not absence: answering "not declared" here would hand a
+      # `call.undefined-method` a fired verdict it has no evidence for. Suppress and record the hit.
+      return false unless chain.truncated?
 
-      resolved_super = resolve_ancestor_class_name(current, raw_super, name_memo)
-      queue.push(resolved_super) if resolved_super
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+      true
     end
 
-    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) to a project-discovered class,
-    # following Ruby's `Module.nesting` constant lookup from the subclass's declaration HEADER, innermost
-    # first, then bare. nil when no candidate names a discovered user class.
-    def resolve_ancestor_class_name(subclass_qualified, raw_ancestor, name_memo)
-      by_subclass = (name_memo[subclass_qualified] ||= {})
-      return by_subclass[raw_ancestor] if by_subclass.key?(raw_ancestor)
+    # A module entry on the singleton chain answers with its INSTANCE methods; on the instance chain, the
+    # caller's kind stands.
+    def kind_for(kind) = kind == :singleton ? :instance : kind
+    private :kind_for
 
-      by_subclass[raw_ancestor] = compute_ancestor_class_name(subclass_qualified, raw_ancestor)
+    # Pushes `current`'s direct ancestors onto a breadth-first queue: included / prepended modules first, then
+    # the superclass, each resolved against the nesting `current`'s declaration header is written in; names
+    # that resolve to no project class/module are dropped. `mixins: false` gives the superclass alone. No
+    # reader in the engine walks this way any more (they read {ResolutionChain}); it stays for the plugin
+    # surface, with the ADR-46 class edge the walk it served always filed.
+    def enqueue_ancestors(current, queue, name_memo, mixins: true) # rubocop:disable Lint/UnusedMethodArgument
+      record_class_dependency(current) if Analysis::DependencyRecorder.active?
+      queue.concat(ResolutionChain.direct_ancestors(self, current.to_s, mixins))
     end
-    private :ancestor_walk_gave_up, :resolve_ancestor_class_name
 
     # Issue #682 — the candidate names an ancestor spelled `raw_ancestor` can denote in `subclass_qualified`,
     # in Ruby's lookup order, most-qualified first and the bare name last. The single owner of the question:
-    # three walks resolved a superclass / include name apiece ({#enqueue_ancestors} for method lookup,
-    # `Reflection.resolve_ancestor_name` for the constant ladder's ancestor rung, and
-    # `Analysis::CheckRules`' override-visibility rule), and each derived the order by PEELING the
-    # subclass's qualified name one `::` segment at a time.
+    # three walks resolved a superclass / include name apiece (the method walk, the constant ladder's
+    # ancestor rung, and `Analysis::CheckRules`' override-visibility rule — all three now {ResolutionChain}),
+    # and each derived the order by PEELING the subclass's qualified name one `::` segment at a time.
     #
     # That peel is the NESTED spelling's answer, given to both spellings. Ruby evaluates a superclass
     # expression before entering the body, so the cref that governs it is the one the declaration's HEADER
@@ -1628,9 +1730,9 @@ module Rigor
     # The header nesting is a property of the DECLARATION, not of the reader, so it is read from the
     # discovery table `Inference::ScopeIndexer` records it in rather than from this scope's own
     # `#lexical_nesting`. Answering off the reader's chain would be wrong past the first hop of the ancestor
-    # BFS (the chain describes the reader's class, not the ancestor being resolved) and would silently
-    # corrupt the run-scoped ancestor memos in `Inference::ExpressionTyper#class_graph_buckets` and
-    # `Reflection.ancestor_constant_scopes`, both of which key on the class name alone because this walk is
+    # chain (the chain describes the reader's class, not the ancestor being resolved) and would silently
+    # corrupt the {ResolutionChain} memo and the ones layered on it (`Inference::ExpressionTyper#class_graph_buckets`,
+    # `Reflection.ancestor_constant_scopes`), all of which key on the class name alone because this walk is
     # a pure function of the frozen discovery tables.
     #
     # The peel survives as the FALLBACK, for a class no declaration walk recorded — a scope seeded without
@@ -1737,10 +1839,6 @@ module Rigor
     end
     private :peeled_header_nesting
 
-    def compute_ancestor_class_name(subclass_qualified, raw_ancestor)
-      ancestor_name_candidates(subclass_qualified, raw_ancestor).find { |c| known_user_class?(c) }
-    end
-
     # Issue #723 — `discovered_methods` is in the list because the other three miss a class whose only
     # project-side content is CLASS methods: `class Base; def self.build = :built; end` records no instance
     # def node, no superclass and no include, so the ancestor-name resolver did not recognise `Base` as a
@@ -1755,13 +1853,13 @@ module Rigor
     # narrower predicate (`discovered_classes` alone) would read a project class as having left the project
     # and attribute its root name to a same-named locked gem — a WRONG provenance label, which is the one
     # direction ADR-82 forbids.
-    private :ancestor_walk_gave_up, :compute_ancestor_class_name
 
     # Records, for a resolved cross-class ancestry read, every file that declares `class_name` (its declaration /
-    # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated only by
-    # the cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}) and only when
-    # dependency recording is active. No-op when the class is not a project class (core / stdlib / gem names
-    # never appear in the source map). Gated by the caller on the recorder being active.
+    # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated by the
+    # cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}); a scope built
+    # without one holds none, and the read then files nothing. No-op when the class is not a project class
+    # (core / stdlib / gem names never appear in the source map). Gated by the caller on the recorder being
+    # active.
     def record_class_dependency(class_name)
       sites = @discovery.discovered_class_sources[class_name.to_s]
       return if sites.nil?
@@ -1781,8 +1879,7 @@ module Rigor
     # so a bare referent is re-checked when the class appears or disappears and at no other time. A file edge
     # would have re-checked every bare referent of every class the file declares on any edit to it.
     def record_class_existence(class_name)
-      segment = class_name.to_s.delete_prefix("::").split("::").last
-      Analysis::DependencyRecorder.read_name(:class, segment) if segment
+      Analysis::DependencyRecorder.read_last_segment(:class, class_name.to_s)
     end
 
     # Issue #644 — the positive ADR-46 edge for a cross-file VALUE constant. `Reflection.constant_type_at`
@@ -1938,17 +2035,17 @@ module Rigor
 
     # Issue #1429 — a join keeps a guard record while the joined scope still narrows its name: a global both arms
     # bind, a constant both arms narrow (one an arm does not narrow reads its resolved type after the join, so its
-    # narrowing is gone). An arm without a record contributes nothing to the restore target, whose union with the
-    # joined binding {#forget_guard_narrowings} takes, so it still covers that arm's binding.
-    def join_guard_records(other, joined_globals, joined_constants)
+    # narrowing is gone), and an instance variable both arms bind (#1446). An arm without a record contributes nothing
+    # to the restore target, whose union with the joined binding {#forget_guard_narrowings} takes, so it still covers
+    # that arm's binding.
+    # `joined` maps each record kind to the joined scope's table of that kind.
+    def join_guard_records(other, joined)
       mine = @guard_records
       theirs = other.guard_records
       return EMPTY_GUARD_RECORDS if mine.empty? && theirs.empty?
 
       merged = mine.merge(theirs) { |_key, left, right| Type::Combinator.union(left, right) }
-      kept = merged.select do |(kind, name), _|
-        kind == :global ? joined_globals.key?(name) : joined_constants.key?(name)
-      end
+      kept = merged.select { |(kind, name), _| joined.fetch(kind).key?(name) }
       kept.empty? ? EMPTY_GUARD_RECORDS : kept.freeze
     end
     private :join_guard_records
@@ -1993,7 +2090,8 @@ module Rigor
     end
 
     def same_guard_state?(other)
-      @constant_narrowings == other.constant_narrowings && @guard_records == other.guard_records
+      @constant_narrowings == other.constant_narrowings && @guard_records == other.guard_records &&
+        @bot_guard_classes == other.bot_guard_classes
     end
 
     def rebuild(
@@ -2007,6 +2105,7 @@ module Rigor
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
       opaque_block_self: @opaque_block_self,
+      block_self_unknown: @block_self_unknown,
       singleton_class_body: @singleton_class_body,
       lexical_nesting: @lexical_nesting,
       dynamic_origins: @dynamic_origins,
@@ -2020,7 +2119,9 @@ module Rigor
       repeated_or_writes: @repeated_or_writes,
       match_frame: @match_frame,
       constant_narrowings: @constant_narrowings,
-      guard_records: @guard_records
+      guard_records: @guard_records,
+      bot_guard_classes: @bot_guard_classes,
+      declared_refinements: @declared_refinements
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -2034,6 +2135,7 @@ module Rigor
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
         opaque_block_self: opaque_block_self,
+        block_self_unknown: block_self_unknown,
         singleton_class_body: singleton_class_body,
         lexical_nesting: lexical_nesting,
         dynamic_origins: dynamic_origins,
@@ -2047,7 +2149,9 @@ module Rigor
         repeated_or_writes: repeated_or_writes,
         match_frame: match_frame,
         constant_narrowings: constant_narrowings,
-        guard_records: guard_records
+        guard_records: guard_records,
+        bot_guard_classes: bot_guard_classes,
+        declared_refinements: declared_refinements
       )
     end
 
@@ -2065,7 +2169,8 @@ module Rigor
       result.freeze
     end
 
-    def build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
+    # One keyword per Scope field, each with its join rule beside it; the size is the field count.
+    def build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       self.class.new(
         environment: @environment,
         locals: joined_locals.freeze,
@@ -2113,6 +2218,9 @@ module Rigor
         # block entry by `entering_opaque_block` and inherited through `rebuild`), so both arms usually carry
         # the same value and the `||` is that value.
         opaque_block_self: @opaque_block_self || other.opaque_block_self,
+        # Issue #1717 — the same body property, and `||` keeps the exemption it grants (the FP-safe side).
+        # A plain `true` outranks the refine body's {REFINEMENT_BLOCK_SELF} for the same reason.
+        block_self_unknown: merged_block_self_unknown(other.block_self_unknown),
         # Issue #963 — a body property like the two above, so both arms of an in-body merge carry the identical
         # value and the `||` is that value. `||` is also the safe direction on its own terms: keeping the mark
         # declines the `define_method` narrowing, which is the pre-#963 answer.
@@ -2137,15 +2245,44 @@ module Rigor
         # of a merge inside one body carry the same one; `||` keeps it should either arm lack it, since dropping
         # it only loses the frame's resets.
         match_frame: @match_frame || other.match_frame,
-        # Issue #1429 — the guard narrowings of globals and constants and their pre-guard records.
-        **join_guard_narrowings(other, joined_globals)
+        # Issue #1667 — a body property stamped at block entry like the frame above, so both arms of a merge carry
+        # the same list; the union keeps either arm's modules, the declining direction.
+        declared_refinements: join_declared_refinements(other),
+        # Issue #1429 — the guard narrowings of globals and constants and their pre-guard records, and of instance
+        # variables (#1446).
+        **join_guard_narrowings(other, joined_globals, joined_ivars)
       )
     end
 
-    def join_guard_narrowings(other, joined_globals)
+    def join_declared_refinements(other)
+      mine = @declared_refinements
+      theirs = other.declared_refinements
+      return mine if theirs.equal?(mine) || theirs.empty?
+      return theirs if mine.empty?
+
+      (mine | theirs).freeze
+    end
+
+    def join_guard_narrowings(other, joined_globals, joined_ivars)
       joined_constants = join_constant_narrowings(other)
-      { constant_narrowings: joined_constants,
-        guard_records: join_guard_records(other, joined_globals, joined_constants) }
+      joined = { global: joined_globals, ivar: joined_ivars, constant: joined_constants }
+      { constant_narrowings: joined_constants, guard_records: join_guard_records(other, joined),
+        bot_guard_classes: join_bot_guard_classes(other) }
+    end
+
+    # Issue #1446 — an entry both arms hold, with the classes of either: the joined receiver reads `bot` only where
+    # both arms do. One only an arm holds is dropped, so a call on the joined `bot` reads as on an unknown one.
+    def join_bot_guard_classes(other)
+      mine = @bot_guard_classes
+      theirs = other.bot_guard_classes
+      return mine if mine.equal?(theirs)
+      return EMPTY_BOT_GUARD_CLASSES if mine.empty? || theirs.empty?
+
+      joined = mine.each_with_object({}) do |(key, names), acc|
+        other_names = theirs[key]
+        acc[key] = (names | other_names).freeze if other_names
+      end
+      joined.empty? ? EMPTY_BOT_GUARD_CLASSES : joined.freeze
     end
 
     # Issue #1429 — a constant reference both arms narrow reads the union; one only an arm narrows reads its resolved
@@ -2280,11 +2417,19 @@ module Rigor
       sym_kind = receiver_kind.to_sym
       sym_name = receiver_name.to_sym
       filtered = @indexed_narrowings.reject do |k, _|
-        k.receiver_kind == sym_kind && k.receiver_name == sym_name
+        (k.receiver_kind == sym_kind && k.receiver_name == sym_name) || key_guard_rooted_at?(k.key, sym_kind, sym_name)
       end
       filtered.size == @indexed_narrowings.size ? @indexed_narrowings : filtered.freeze
     end
 
+    # Issue #1703 — whether `key` is a `key?` guard's key that is the variable `kind`/`name`, or a chain read from it.
+    def key_guard_rooted_at?(key, kind, name)
+      return false unless key.is_a?(Inference::KeyPresenceGuard::KeyExpr)
+
+      root = key.root
+      root[0] == kind && root[1] == name
+    end
+
     # ADR-58 WD1 — set/clear the declaration-sourced provenance mark.
     # Issue #667 — the #667 carrier's add/drop pair. Deliberately not reusing
     # {#add_declaration_sourced} / {#drop_declaration_sourced_for}: the two sets are joined by opposite
@@ -2359,6 +2504,13 @@ module Rigor
       @guard_records.merge(key => pre_guard).freeze
     end
 
+    def drop_bot_guard_class(kind, name)
+      return @bot_guard_classes if @bot_guard_classes.empty?
+
+      key = [kind, kind == :constant ? name : name.to_sym]
+      @bot_guard_classes.key?(key) ? @bot_guard_classes.except(key).freeze : @bot_guard_classes
+    end
+
     def drop_guard_record(kind, name)
       return @guard_records if @guard_records.empty?