rigortype 0.4.1 → 0.4.2

data/lib/rigor/scope/resolution_chain.rb

@@ -83,10 +83,12 @@ module Rigor
       # One ancestor on a chain. A project entry names a class or module (`name`) on `side` `:instance` (its
       # instance methods) or `:singleton` (the class object's singleton). An external entry has no `name`: it
       # keeps the spelling (`raw`) and its candidate names (`candidates`, most qualified first, empty for an
-      # ambiguous spelling), and `superclass_edge` says it was reached through a superclass edge.
+      # ambiguous spelling), and `superclass_edge` says it was reached through a superclass edge. `owner` names
+      # the class or module whose edge an external entry is (#1698: Ruby resolves an `include`'s argument with
+      # that body as the innermost cref, a namespace `candidates` leaves out); it is nil on a project entry.
       # `last_segment` is the unqualified name a project entry files its negative class edge under, computed once
       # when the entry is interned.
-      Entry = Data.define(:name, :side, :raw, :candidates, :superclass_edge, :last_segment) do
+      Entry = Data.define(:name, :side, :raw, :candidates, :superclass_edge, :last_segment, :owner) do
         def external? = name.nil?
       end
 
@@ -98,7 +100,9 @@ module Rigor
       # module whose mixin edges' order is not a fact, `kind` the side read (`:include` or `:extend`), `listed`
       # the entries `DiscoveryIndex#unpositioned_mixins` lists for it (`"*"` included), and `multi_file` whether
       # the multi-file rule fired (two or more files declare it and it has two or more edges on that side).
-      # Interned per `[node, kind]` in the flavor's bucket, so equal marks are one object.
+      # Interned per `[node, kind]` in the flavor's bucket, so equal marks are one object. Kind `:extend_hook`
+      # (#1730, listing `"*"`) marks a node a module it extends may mix into through a hook; it is not an order mark
+      # ({#order_marks}).
       Mark = Data.define(:node, :kind, :listed, :multi_file)
 
       NO_MARKS = [].freeze
@@ -135,7 +139,20 @@ module Rigor
 
       # True when a class on the chain has mixin edges whose order the tables cannot vouch for
       # (`DiscoveryIndex#unpositioned_mixins`, or a class declared in several files with several edges).
-      def unsettled? = !@marks.empty?
+      def unsettled? = !order_marks.empty?
+
+      # The marks that make the chain's ORDER doubtful. An `:extend_hook` mark (#1730) says only that an extended
+      # module's hook may have mixed something in that the chain does not list: it makes a candidate-set read
+      # `:unknown` and {#wildcard_mixin?} true, and leaves every other reader on the chain's own order. Sending
+      # those readers to master's order would answer a constant lookup breadth-first, which is wrong for the
+      # #1567 shape on every class that extends such a module.
+      def order_marks
+        @memo[:order_marks] ||= @marks.reject { |mark| mark.kind == :extend_hook }.freeze
+      end
+
+      # True when a class on the chain records a mixin the tables cannot name (`"*"`: an `include` of a
+      # non-constant, or a call the walk cannot record), so the chain may hold a module it does not list.
+      def wildcard_mixin? = @marks.any? { |mark| mark.listed.include?(Relevance::WILDCARD) }
 
       # The ONE decision every first-definer reader makes: does `answer`, read off this chain, stand, or does
       # the reader answer what the walk this chain replaced answered ({MasterOrder})? Returns `:chain` or
@@ -163,7 +180,7 @@ module Rigor
         # goes; `search` files only the entries ahead of an answer. `owner` names the entry that answered.
         record_beyond(scope, owner, unknown_for.nil?)
         return settle_unknown(scope, answer, unknown_for, &) unless unknown_for.nil?
-        return :master unless @marks.empty?
+        return :master unless order_marks.empty?
 
         case @forks
         when 0 then :chain
@@ -208,7 +225,10 @@ module Rigor
       def search(scope, start = 0, stop = nil, side: nil)
         recording = Analysis::DependencyRecorder.active?
         stop ||= @entries.size
-        record_head(scope, start, side) if recording
+        if recording
+          record_head(scope, start, side)
+          record_extend_hooks(scope)
+        end
         index = start
         while index < stop
           entry = @entries[index]
@@ -228,6 +248,7 @@ module Rigor
 
         ResolutionChain.record_class(scope, @root)
         (stop || @entries.size).times { |index| ResolutionChain.record_entry(scope, @entries[index], side) }
+        record_extend_hooks(scope)
       end
 
       # What a {#settle} verdict adds to what the search already filed. The search files the root and every entry
@@ -241,7 +262,8 @@ module Rigor
       #   it `:unknown`, so the rest of the chain is filed as for any other answer;
       # - otherwise every entry after the answer (the whole chain when `owner` names none) files its class edge
       #   and, for a project entry, the negative class edge on its unqualified name, so a NEW file declaring or
-      #   reopening it re-checks the reader. An external entry files only the sites of the names it can denote.
+      #   reopening it re-checks the reader. An external entry files only the sites of the names it can denote,
+      #   and every external on the chain files its hook edges ({#record_hooks}, #1641).
       #
       # What is filed is a function of this chain, the entry the filing starts from and the discovery index the
       # sites are read from, so a consumer that settles the same chain from the same entry again (the common case:
@@ -253,6 +275,8 @@ module Rigor
 
         start = owner.nil? ? nil : @entries.index { |entry| entry.name == owner }
         Analysis::DependencyRecorder.file_chain_once(self, start, scope.discovery) { file_beyond(scope, start) }
+        record_hooks(scope)
+        record_extend_hooks(scope)
       end
       private :record_beyond
 
@@ -268,6 +292,113 @@ module Rigor
       end
       private :file_beyond
 
+      # #1641 — the hook edges of every EXTERNAL entry on the chain, ahead of the answer or past it. A project file
+      # that gives an external module a hook (`module Comparable; def self.included(base) = base.prepend(P); end`)
+      # can put a definer ahead of the answer wherever the module sits, and a candidate-set read declines on it
+      # (the hook's mixin lists `"*"` on the module). The entry's class edges are the sites of the names it can
+      # denote, which a NEW file is not among, and a negative class edge on its name would re-check every reader of
+      # `Kernel` or `Enumerable` on any reopening. So each candidate name files the negative method edge of every
+      # {Relevance::HOOKS} name on its singleton side (`method:Comparable.included`, the key a new `def
+      # self.included` satisfies); a file adding any other method to the module re-checks nothing, and once the
+      # module is declared its sites carry later edits and the removal. The edges are a function of the chain alone,
+      # so a consumer files them once per chain ({Analysis::DependencyRecorder.file_chain_once}, #1590). A hook
+      # written another way — an instance `def included` in a module extended onto the external, a
+      # `define_singleton_method(:included)` — satisfies no such key and is not seen.
+      def record_hooks(scope)
+        externals = (@memo[:externals] ||= @entries.select(&:external?).freeze)
+        return if externals.empty?
+
+        Analysis::DependencyRecorder.file_chain_once(self, :hooks, scope.discovery) do
+          externals.each do |entry|
+            entry.candidates.each { |name| Analysis::DependencyRecorder.read_keys(ResolutionChain.hook_keys(name)) }
+          end
+        end
+      end
+      private :record_hooks
+
+      # #1730 — the edges of the {Builder#extend_hook_taint?} decision: an instance chain's project entries may carry
+      # a `"*"` mark because a module one of them `extend`s has a hook that mixes into the extender, and the
+      # module is often declared in a file the chain records nothing of. Each such module the decision read files
+      # its class edges (an edit to its hook moves its declaration signature) and the negative method edges of
+      # the hooks the decision reads ({ResolutionChain.extend_hook_keys}), which a NEW file reopening the module
+      # to add a hook satisfies; a spelling no project module answers files the singleton hook keys of each name
+      # it can denote, as {#record_hooks} does. Filed once per consumer and chain.
+      def record_extend_hooks(scope)
+        return unless @side == :instance
+
+        targets = (@memo[:extend_targets] ||= ResolutionChain.extend_targets(scope, @flavor, @entries))
+        return if targets.empty?
+
+        Analysis::DependencyRecorder.file_chain_once(self, :extend_hooks, scope.discovery) do
+          targets.each do |raw, resolved, candidates|
+            Analysis::DependencyRecorder.read_last_segment(:class, raw)
+            if resolved
+              ResolutionChain.record_class(scope, resolved)
+              Analysis::DependencyRecorder.read_keys(ResolutionChain.extend_hook_keys(resolved))
+            else
+              candidates.each { |name| Analysis::DependencyRecorder.read_keys(ResolutionChain.hook_keys(name)) }
+            end
+          end
+        end
+      end
+      private :record_extend_hooks
+
+      # The hooks that let a module `extend`ed onto N reshape N's INSTANCE side (#1730): its singleton `extended` /
+      # `extend_object` run against N at the `extend` and may mix into N; its instance `included` /
+      # `append_features` / `prepended` / `prepend_features` / `inherited` become N's own singleton hooks and run
+      # against N's includers, prependers and subclasses, which the mark on N reaches through their chains.
+      SINGLETON_EXTEND_HOOKS = %i[extended extend_object].freeze
+      INSTANCE_EXTEND_HOOKS = %i[included append_features prepended prepend_features inherited].freeze
+
+      @extend_hook_keys = {}
+
+      # The frozen negative method keys of `name`'s {SINGLETON_EXTEND_HOOKS} and {INSTANCE_EXTEND_HOOKS}.
+      def self.extend_hook_keys(name)
+        @extend_hook_keys[name] ||= (
+          SINGLETON_EXTEND_HOOKS.map { |hook| "method:#{name}.#{hook}".freeze } +
+          INSTANCE_EXTEND_HOOKS.map { |hook| "method:#{name}##{hook}".freeze }
+        ).freeze
+      end
+
+      # Whether extending `name` may mix modules into the extender's instance side, or into its includers' (#1730):
+      # `name` records a mixin it cannot name on its own instance side (`"*"`, which a hook's `base.include X` or
+      # `base.class_eval { … }` lists on the hook's module) and defines one of the hooks that would run it there.
+      def self.extend_reshapes_instance?(scope, name)
+        listed = scope.discovery.unpositioned_mixins[name]&.dig(:include)
+        return false unless listed&.include?(Relevance::WILDCARD)
+
+        defines_any?(scope.discovered_singleton_def_nodes[name], SINGLETON_EXTEND_HOOKS) ||
+          defines_any?(scope.discovered_def_nodes[name], INSTANCE_EXTEND_HOOKS)
+      end
+
+      # Read off the def-node tables: the existence table does not carry a module's own instance hook once the
+      # extend fold has copied it onto the extender's singleton.
+      def self.defines_any?(defs, hooks)
+        !defs.nil? && hooks.any? { |hook| defs.key?(hook) }
+      end
+
+      # `[[spelling, resolved name or nil, candidate names], …]`: every module the project entries of an instance chain
+      # `extend`, as {Builder#extend_hook_taint?} resolved them.
+      def self.extend_targets(scope, flavor, entries)
+        resolver = resolver_for(scope, flavor)
+        extends = scope.discovery.discovered_extends
+        entries.each_with_object([]) do |entry, out|
+          next if entry.external? || entry.side != :instance
+
+          (extends[entry.name] || EMPTY_NAMES).each do |raw|
+            resolved = resolver.resolve_one(entry.name, raw)
+            out << [raw, resolved, resolved ? EMPTY_NAMES : resolver.candidates(entry.name, raw)].freeze
+          end
+        end.uniq.freeze
+      end
+
+      @hook_keys = {}
+
+      # The frozen `method:Name.hook` negative keys of `name`'s {Relevance::HOOKS}, built once per name.
+      def self.hook_keys(name)
+        @hook_keys[name] ||= Relevance::HOOKS.map { |hook| "method:#{name}.#{hook}".freeze }.freeze
+      end
+
       def record_head(scope, start, side)
         ResolutionChain.record_class(scope, @root) unless start.zero? && @entries.first&.name == @root
         start.times { |index| ResolutionChain.record_entry(scope, @entries[index], side) }
@@ -397,7 +528,8 @@ module Rigor
             @discovery.discovered_superclasses.key?(name) || @discovery.discovered_includes.key?(name) ||
               @discovery.discovered_classes.key?(name)
           when :arity
-            @scope.known_user_class?(name) || @discovery.discovered_parameter_envelopes.key?(name)
+            @scope.known_user_class?(name) ||
+              DiscoveryIndex.declares_surface?(@discovery.discovered_parameter_envelopes[name])
           else
             @scope.known_user_class?(name)
           end
@@ -601,7 +733,8 @@ module Rigor
         # The chain for `root`, carrying its retro world when the skip rule skipped anything on the way.
         def chain(root, side)
           entries, starts, classes, forks, marks, retro_ok = lin_for(root, side)
-          retro = build_retro(root, side) if forks == 1 && retro_ok && marks.empty? && !@retro
+          order_marked = marks.any? { |mark| mark.kind != :extend_hook }
+          retro = build_retro(root, side) if forks == 1 && retro_ok && !order_marked && !@retro
           cut_at = cut_position(entries)
           return whole_chain(root, side, entries, starts, classes, [forks, marks], retro) if cut_at.nil?
 
@@ -701,6 +834,7 @@ module Rigor
         def compute_instance(name, depth)
           # `discovered_includes` already carries the prepended names, so it counts every instance-side edge once.
           mark_unsettled(name, :include, (@discovery.discovered_includes[name] || EMPTY).size)
+          @frames.last.add_marks(mark_for(name, :extend_hook, WILDCARD_LIST, false)) if extend_hook_taint?(name)
           entries = [project_entry(name, :instance)]
           super_lin = superclass_lin(name, :instance, depth)
           entries.concat(super_lin[0])
@@ -743,6 +877,20 @@ module Rigor
                                                        multi)].freeze
         end
 
+        WILDCARD_LIST = ["*"].freeze # Relevance::WILDCARD, which loads after this file
+        private_constant :WILDCARD_LIST
+
+        # #1730 — whether a module `name` extends has a hook that may mix into `name`'s instance side or its
+        # includers' ({ResolutionChain.extend_reshapes_instance?}). Ruby runs it at the `extend`, so the mixin is
+        # not a fact of the tables and `name`'s instance side is unpositioned. A spelling no project module
+        # answers taints nothing: the project cannot see its hooks.
+        def extend_hook_taint?(name)
+          (@discovery.discovered_extends[name] || EMPTY).any? do |raw|
+            resolved = @resolver.resolve_one(name, raw)
+            !resolved.nil? && ResolutionChain.extend_reshapes_instance?(@scope, resolved)
+          end
+        end
+
         def multi_file?(name)
           sites = @discovery.discovered_class_sources[name]
           !sites.nil? && sites.size >= 2
@@ -866,14 +1014,14 @@ module Rigor
 
         def project_entry(name, side)
           by_side = (@bucket[:interned][side] ||= {})
-          by_side[name] ||= Entry.new(name, side, nil, nil, false, name.to_s.split("::").last.freeze)
+          by_side[name] ||= Entry.new(name, side, nil, nil, false, name.to_s.split("::").last.freeze, nil)
         end
 
         def external_entry(owner, raw, side, superclass_edge)
           by_edge = ((@bucket[:externals][side] ||= {})[superclass_edge] ||= {})
           by_owner = (by_edge[owner] ||= {})
           by_owner[raw] ||= Entry.new(nil, side, raw, @scope.ancestor_name_candidates(owner, raw).freeze,
-                                      superclass_edge, nil)
+                                      superclass_edge, nil, owner)
         end
       end
       private_constant :Builder

data/lib/rigor/scope.rb

@@ -5,6 +5,7 @@ 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"
@@ -26,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, :bot_guard_classes
+                :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
@@ -62,6 +63,20 @@ 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
@@ -182,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
@@ -320,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,
@@ -334,7 +352,8 @@ module Rigor
       match_frame: nil,
       constant_narrowings: EMPTY_CONSTANT_NARROWINGS,
       guard_records: EMPTY_GUARD_RECORDS,
-      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES
+      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES,
+      declared_refinements: Inference::InEffectRefinements::EMPTY
     )
       @environment = environment
       @locals = locals
@@ -351,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
@@ -366,6 +386,7 @@ module Rigor
       @constant_narrowings = constant_narrowings
       @guard_records = guard_records
       @bot_guard_classes = bot_guard_classes
+      @declared_refinements = declared_refinements
       freeze
     end
 
@@ -378,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])
 
@@ -476,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
@@ -518,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`
@@ -544,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
@@ -600,6 +712,45 @@ module Rigor
     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.
     def seed_declaration_sourced_ivar(name, type)
@@ -1954,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,
@@ -1968,7 +2120,8 @@ module Rigor
       match_frame: @match_frame,
       constant_narrowings: @constant_narrowings,
       guard_records: @guard_records,
-      bot_guard_classes: @bot_guard_classes
+      bot_guard_classes: @bot_guard_classes,
+      declared_refinements: @declared_refinements
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -1982,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,
@@ -1996,7 +2150,8 @@ module Rigor
         match_frame: match_frame,
         constant_narrowings: constant_narrowings,
         guard_records: guard_records,
-        bot_guard_classes: bot_guard_classes
+        bot_guard_classes: bot_guard_classes,
+        declared_refinements: declared_refinements
       )
     end
 
@@ -2014,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,
@@ -2062,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.
@@ -2086,12 +2245,24 @@ 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 #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_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)
       joined = { global: joined_globals, ivar: joined_ivars, constant: joined_constants }
@@ -2246,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

data/lib/rigor/sig_gen/classification.rb

@@ -57,7 +57,10 @@ module Rigor
         inline_generic_class: "sig.skipped.inline-generic-class",
         # ADR-112 WD4 — the member is declared inline and in `sig/`, and the two disagree. A refusal, not a
         # skip: `--write` and `--check` exit 1 until a person reconciles them or passes `--overwrite`.
-        inline_differs: "sig.skipped.inline-differs"
+        inline_differs: "sig.skipped.inline-differs",
+        # #1676 — a plain top-level `def` defines a private `Object` method and has no class to write a
+        # declaration under, so it is reported rather than silently dropped. Whether to emit it stays open.
+        top_level_def: "sig.skipped.top-level-def"
       }.freeze
     end
   end