rigortype 0.4.6 → 0.4.8

data/lib/rigor/sig_gen/generator.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../configuration"
 require_relative "../environment"
+require_relative "../run_scoped_slots"
 require_relative "../project_environment"
 require_relative "../scope"
 require_relative "../reflection"
@@ -16,6 +17,7 @@ require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/project_seed_tables"
 require_relative "../inference/module_function_state"
+require_relative "bot_proposal_guard"
 require_relative "../inference/rbs_type_translator"
 require_relative "alias_index"
 require_relative "meta_class_shape"
@@ -26,6 +28,8 @@ require_relative "declaration_equivalence"
 require_relative "inline_declarations"
 require_relative "layout_index"
 require_relative "method_candidate"
+require_relative "platform_guarded_files"
+require_relative "type_name_qualification"
 require_relative "writer"
 require_relative "../rooted_glob"
 
@@ -79,16 +83,20 @@ module Rigor
       attr_reader :unrenderable, :unresolvable_superclasses
 
       # @param paths — files / directories to scan.
-      # @param observations — => Array<Array<Rigor::Type>>}]
+      # @param observations —
       #   ADR-14 slice 3 — per-target-method arg-tuple observations
       #   produced by {ObservationCollector}. An empty Hash (the default)
       #   means "no observations available; emit `untyped` for every
       #   parameter position" per ADR-5 clause 2.
+      # @param target_writer — the {Writer} a `--write` or `--check` run hands the candidates to. When given, a
+      #   class counts as written for a subclass only if that writer accepts its target file (#2461); nil (print,
+      #   diff, JSON) counts every class with a candidate the writer is sure to write.
       # @param overwrite — `--overwrite`: a member declared inline whose `sig/` copy disagrees is proposed as an
       #   `inline-overwrite` of the whole member instead of refused (ADR-112 WD4).
       def initialize(configuration:, paths:, observations: {}, include_private: false, effect_annotator: nil,
-                     overwrite: false)
+                     overwrite: false, target_writer: nil)
         @configuration = configuration
+        @target_writer = target_writer
         @overwrite = overwrite
         @paths = paths
         @observations = normalize_observations(observations)
@@ -114,6 +122,36 @@ module Rigor
         @unresolvable_superclasses = {}
         # Issue #722 — whole-run: `{ class name => the lexical nesting its header is written in }`.
         @superclass_nestings = {}
+        # Issue #2437 — whole-run: every class a walked file declares with a `class` keyword or a `Data.define` /
+        # `Struct.new` layout, so the report can tell a project superclass this run did not write from one nothing
+        # declares.
+        @source_classes = Set.new
+      end
+
+      # How the report names an unresolvable superclass token ({#unresolvable_superclasses}). It is a project
+      # superclass when it names a class the walked source declares and this run wrote nothing for, whose own chain
+      # would close if the project's classes were written:
+      # each step a source class, ending at no superclass or at one the RBS environment knows (#2437). What is
+      # missing is then the project's own declaration, not a gem's RBS. `class ApplicationRecord <
+      # ActiveRecord::Base` with no RBS for the gem is not such a class: writing it would not help.
+      #
+      # Returns `[:project, token]` for such a class. Otherwise `[:external, root]`, where `root` is the first token
+      # on the chain that is not a source class: `User < ApplicationRecord` reports `ActiveRecord::Base`, the class
+      # whose RBS is missing, rather than the project class between them.
+      def unresolvable_superclass_report(token)
+        name = bare_superclass_name(token)
+        root = token
+        seen = {}
+        while @source_classes.include?(name) && !seen[name]
+          seen[name] = true
+          nesting, superclass = @superclass_nestings[name]
+          return [:project, token] if superclass.nil?
+
+          root = resolve_superclass_token(superclass, nesting, @source_classes, name)
+          name = bare_superclass_name(root)
+          return [:project, token] if Reflection.rbs_class_known?(name, environment: @environment)
+        end
+        [:external, root]
       end
 
       # Lifts legacy plain-`Array[Type]` observation entries into {ObservedCall} carriers. Specs from the
@@ -128,13 +166,45 @@ module Rigor
       def run
         resolved = resolve_paths(@paths)
         @resolved_paths = resolved
+        # Issue #3035 — the scanned files Ruby loads only through a platform-conditional require; their
+        # candidates are demoted in {#demote_platform_guarded}.
+        @platform_guarded_files = PlatformGuardedFiles.call(
+          resolved, ruby_version: @configuration.target_ruby
+        )
         @environment = build_environment(resolved)
-        candidates = resolved.flat_map { |path| analyse_file(path, @environment) }
-        annotate_effects(
-          demote_overridden_base_methods(
-            demote_unresolvable_superclasses(demote_inline_generic_classes(resolve_superclass_spellings(candidates)))
+        # ADR-84 WD2, as `Runner#run_analysis` mints it for `check` (#2300): one return-memo bucket for the whole
+        # run. Without it the memo keys on each file's merged `discovered_def_nodes`, a new table per file, so a
+        # callee reached from two files was re-inferred in each. A fresh token per run keeps a second run in one
+        # process from reading the first's entries, and the bucket is released with the other run-scoped slots
+        # when the run ends ({RunScopedSlots}), so a finished run holds none of it.
+        @run_generation = Object.new.freeze
+        # Both read the files as they are now, so a second `run` of one generator re-reads them.
+        @project_tables = nil
+        @file_base_scope = nil
+        # #2461 — which `sig/` targets the writer will write to, read from the files as they are now.
+        @writable_targets = {}
+        # ADR-130 WD5 — with interface dispatch off, so a return read through a `Rigor::Plugin` interface member
+        # (`_FactStore#publish: ... -> nil`) is not written into RBS a plugin author never wrote against the
+        # interface: the output is the output of erasure.
+        candidates = Inference::MethodDispatcher::RbsDispatch.without_interface_dispatch do
+          resolved.flat_map { |path| analyse_file(path, @environment) }
+        end
+        demoted = shelter_withheld_classes(
+          demote_platform_guarded(
+            demote_overridden_base_methods(
+              demote_bot_proposals(
+                demote_unresolvable_superclasses(
+                  demote_generic_reopenings(demote_inline_generic_classes(resolve_superclass_spellings(candidates)))
+                )
+              )
+            )
           )
         )
+        # Again after the override demotion: a demoted method can leave its file with nothing to write, and a class
+        # shell riding on that file then declares nothing a subclass elsewhere could rest on.
+        annotate_effects(stamp_generic_reopenings(demote_unresolvable_superclasses(demoted)))
+      ensure
+        RunScopedSlots.release
       end
 
       private
@@ -209,10 +279,10 @@ module Rigor
         decls.each do |decl|
           next unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
 
-          name = (prefix + [decl.name.to_s.delete_prefix("::")]).join("::")
-          return decl if name == class_name
+          path = ::Rigor::Environment::RbsLoader.declared_class_path(decl, prefix)
+          return decl if path.join("::") == class_name
 
-          found = find_declaration(decl.members, name.split("::"), class_name)
+          found = find_declaration(decl.members, path, class_name)
           return found if found
         end
         nil
@@ -223,6 +293,88 @@ module Rigor
         (1..segments.size).any? { |n| generic.key?(segments.first(n).join("::")) }
       end
 
+      # Issue #2436 — a class the loaded RBS declares generic (`Array`, `Hash`, a gem's or the project's own) is
+      # reopened with that declaration's type parameters copied onto the header ({#stamp_generic_reopenings}),
+      # which is exact only while every parameter is plain. A bound or a default is a type spelled relative to the
+      # declaring file's namespace, and copying it under another nesting can resolve it to a different class, so
+      # rbs would reject the header as it rejects a parameterless one (`GenericParameterMismatchError`): the class,
+      # and every class whose signature mentions it, fails its definition build. A method of such a class, or of
+      # one nested in it, is skipped instead — unless `sig/` already declares the class, whose own header the
+      # writer then writes into ({#demote_inline_generic_classes}' rule).
+      def demote_generic_reopenings(candidates)
+        loader = @environment&.rbs_loader
+        return candidates if loader.nil?
+
+        layout = nil
+        candidates.map do |candidate|
+          next candidate unless Classification::EMITTABLE.include?(candidate.classification)
+          next candidate unless namespace_prefixes(candidate.class_name).any? { |name| bounded_generic?(loader, name) }
+
+          layout ||= LayoutIndex.new(signature_paths: @configuration.signature_paths)
+          next candidate if layout.file_for(candidate.class_name)
+
+          demoted_candidate(candidate, :generic_reopening)
+        end
+      end
+
+      # The other half of {#demote_generic_reopenings}: every emittable candidate carries the header spelling of
+      # each generic class the run may open a header for — its own class, the classes it is nested in, and the
+      # file's class shells and theirs — so the writer and `--print` spell the same header. Method bodies keep
+      # `untyped` for element types; nothing here names `E` in a member.
+      #
+      # Issue #2580 — a skipped candidate is stamped too, and its class counts towards the map: the writer
+      # repairs a parameterless header an earlier run wrote into the file a candidate routes to, and a file whose
+      # every proposal is already declared (or untyped) would otherwise keep a header rbs rejects.
+      def stamp_generic_reopenings(candidates)
+        loader = @environment&.rbs_loader
+        return candidates if loader.nil?
+
+        spelled = header_type_params(candidates.flat_map { |c| [c.class_name, *c.class_shells] }.compact)
+        return candidates if spelled.empty?
+
+        candidates.map { |candidate| candidate.with_class_type_params(spelled) }
+      end
+
+      # #2603 — the header spelling {#header_type_params} gives `class_name` alone, or nil when the loaded RBS does
+      # not declare it generic with plain parameters only. The writer asks it for a bare header in a `sig/` file no
+      # candidate of the run routes to. Nil before {#run} has built the environment.
+      def generic_header_spelling(class_name)
+        loader = @environment&.rbs_loader
+        return nil if loader.nil?
+
+        params = loader.class_declaration_type_params(class_name)
+        "[#{params.join(', ')}]" if !params.empty? && params.all? { |p| plain_type_param?(p) }
+      end
+      public :generic_header_spelling
+
+      # `{ class name => "[unchecked out E]" }` for every name in `names`, or a namespace it is nested in, whose
+      # loaded declaration is generic with plain parameters only.
+      def header_type_params(names)
+        names.uniq.flat_map { |name| namespace_prefixes(name) }.uniq.each_with_object({}) do |name, acc|
+          spelling = generic_header_spelling(name)
+          acc[name] = spelling if spelling
+        end.freeze
+      end
+
+      def namespace_prefixes(class_name)
+        return [] if class_name.nil?
+
+        segments = class_name.split("::")
+        (1..segments.size).map { |n| segments.first(n).join("::") }
+      end
+
+      def bounded_generic?(loader, name)
+        params = loader.class_declaration_type_params(name)
+        !params.empty? && !params.all? { |param| plain_type_param?(param) }
+      end
+
+      # A name, a variance and `unchecked`, and nothing that spells a type: no upper or lower bound, no default.
+      def plain_type_param?(param)
+        %i[upper_bound lower_bound default_type].none? do |reader|
+          param.respond_to?(reader) && param.public_send(reader)
+        end
+      end
+
       # Issue #744 — a base class's method is NOT emitted when a project subclass overrides it and the
       # override is not emitted itself.
       #
@@ -241,7 +393,7 @@ module Rigor
       # (#744 half 2) and is not decided here: this pass only stops sig-gen manufacturing the conflict.
       def demote_overridden_base_methods(candidates)
         superclasses = candidates.each_with_object({}) do |candidate, acc|
-          (candidate.class_superclasses || {}).each { |name, sup| acc[name] = sup.sub(/\[.*\]\z/, "") }
+          (candidate.class_superclasses || {}).each { |name, sup| acc[name] = bare_superclass_name(sup) }
         end
         return candidates if superclasses.empty?
 
@@ -256,6 +408,82 @@ module Rigor
         end
       end
 
+      # Issue #3029 — an emittable `-> bot` proposal for an overridden, abstract or template method is skipped
+      # ({BotProposalGuard}). It runs before {#demote_overridden_base_methods}, so a subclass's `bot` override this
+      # skips counts there as an override that is not emitted, and its parent's declaration is held back too.
+      def demote_bot_proposals(candidates)
+        guard = nil
+        candidates.map do |candidate|
+          next candidate unless Classification::EMITTABLE.include?(candidate.classification)
+          next candidate if candidate.classification == Classification::INLINE_OVERWRITE
+          next candidate unless candidate.inferred_return.is_a?(Type::Bot)
+
+          guard ||= BotProposalGuard.new(project_tables)
+          reason = guard.reason_for(candidate)
+          reason ? demoted_candidate(candidate, reason) : candidate
+        end
+      end
+
+      # The reasons that withhold a member because of what its class's subclasses or callees do, not because the class
+      # itself cannot be declared. `:platform_guarded` counts too (#3035): a class whose every proposal the guard
+      # withheld — the raising-stub shape — still needs its shell on a subclass's file, or the subclass's own
+      # declaration reads `unresolvable-superclass` against a class this platform does load.
+      WITHHELD_FOR_OVERRIDES = %i[overridden_bot abstract_method template_method overridden_by_unsigned_subclass
+                                  platform_guarded].freeze
+      private_constant :WITHHELD_FOR_OVERRIDES
+
+      # Issue #3029 — a class whose members {#demote_bot_proposals} or {#demote_overridden_base_methods} withheld,
+      # leaving it nothing to emit, is still declared, as a class shell, so its subclasses keep their proposals.
+      # Without it an all-abstract base has nothing to write, {#demote_unresolvable_superclasses} finds no
+      # declaration for it, and every subclass proposal is skipped as `unresolvable-superclass`. The shell rides on
+      # each file that declares one of its subclasses, so it reaches disk wherever a subclass's members do. The writer
+      # spells its header with the run's recorded superclass and namespace kinds. A class the file already declares
+      # makes the shell a no-op, and one the loaded RBS declares gets none ({#wholly_withheld_classes}). A class whose
+      # own superclass chain is unresolvable is already skipped as `unresolvable-superclass` when this pass runs, so
+      # it is never withheld here and gets no shell.
+      def shelter_withheld_classes(candidates)
+        withheld = wholly_withheld_classes(candidates)
+        return candidates if withheld.empty?
+
+        shells_by_path = withheld_shell_paths(candidates, withheld)
+        candidates.map do |candidate|
+          extra = shells_by_path.fetch(candidate.path, nil)
+          next candidate if extra.nil?
+
+          shells = (candidate.class_shells + extra.to_a).uniq
+          shells.size == candidate.class_shells.size ? candidate : candidate.with_class_shells(shells)
+        end
+      end
+
+      # The classes to shelter: a withheld member and nothing to emit, and no declaration in the loaded RBS (`sig/`,
+      # the collection, gems). A declared class needs no shell for its subclasses' headers to resolve, and a shell
+      # spelling the source's superclass could contradict the declaration's (`RBS::SuperclassMismatchError`).
+      def wholly_withheld_classes(candidates)
+        by_class = candidates.select(&:class_name).group_by(&:class_name)
+        by_class.each_with_object(Set.new) do |(name, rows), acc|
+          next unless rows.any? { |c| WITHHELD_FOR_OVERRIDES.include?(c.skip_reason) }
+          next if rows.any? { |c| Classification::EMITTABLE.include?(c.classification) }
+          next if class_known?(name)
+
+          acc << name
+        end
+      end
+
+      # `{ path => Set[class name] }`: the files each withheld class's shell rides on, which are the files of every
+      # candidate whose class descends from it, however far down.
+      def withheld_shell_paths(candidates, withheld)
+        superclasses = candidates.each_with_object({}) do |candidate, acc|
+          (candidate.class_superclasses || {}).each { |name, sup| acc[name] = bare_superclass_name(sup) }
+        end
+        candidates.each_with_object(Hash.new { |h, k| h[k] = Set.new }) do |candidate, acc|
+          next if candidate.class_name.nil?
+
+          each_ancestor(candidate.class_name, superclasses) do |ancestor|
+            acc[candidate.path] << ancestor if withheld.include?(ancestor)
+          end
+        end
+      end
+
       # `[class name, method name]` pairs an UNSIGNED override shadows: for every candidate that will not
       # be emitted, every ancestor of its class paired with its method name.
       def unsigned_override_ancestors(candidates, superclasses)
@@ -287,6 +515,54 @@ module Rigor
         )
       end
 
+      # Issue #3035 — a file Ruby loads only under a `RUBY_ENGINE` / `RUBY_PLATFORM` / `defined?(…)`
+      # require guard is not an ordinary definition for the platform sig-gen cannot pick:
+      # `stackprof/truffleruby.rb`'s raising `StackProf.run` stub proposed `-> bot` against the C
+      # extension's real signature. {PlatformGuardedFiles} names those files; a candidate from one is
+      # demoted when another file also provides the method — the guarded proposal would compete with
+      # or duplicate the definition this platform actually loads — or when its inferred return is
+      # `bot`, the shape a raising stub takes and never a contract worth writing from a file the
+      # current engine may never read. It runs after every demotion — LAST of them — so an earlier
+      # pass still sees the guarded candidate as emittable: a platform-conditional override is no
+      # "unsigned subclass" ({#demote_overridden_base_methods}), {BotProposalGuard} still reads its
+      # `bot` on the discovery tables, and demoting the base for a file this platform never loads
+      # would withhold a declaration the guarded file cannot shadow here. It runs BEFORE
+      # {#shelter_withheld_classes}, which must see the final emittable set: a class left with
+      # nothing to emit only because this pass withheld its last member still needs its shell.
+      def demote_platform_guarded(candidates)
+        guarded = @platform_guarded_files
+        return candidates if guarded.nil? || guarded.empty?
+
+        providers = method_providers(candidates)
+        candidates.map do |candidate|
+          next candidate unless platform_guarded_demote?(candidate, guarded, providers)
+
+          demoted_candidate(candidate, :platform_guarded)
+        end
+      end
+
+      # `[class_name, kind, method_name]` → the expanded paths of every candidate providing it, the
+      # guarded file's own included — "another definition also provides" is the `!= own` test.
+      def method_providers(candidates)
+        candidates.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |candidate, acc|
+          next if candidate.class_name.nil?
+
+          acc[[candidate.class_name, candidate.kind, candidate.method_name]] <<
+            File.expand_path(candidate.path)
+        end
+      end
+
+      def platform_guarded_demote?(candidate, guarded, providers)
+        return false unless Classification::EMITTABLE.include?(candidate.classification)
+        return false if candidate.class_name.nil?
+
+        own = File.expand_path(candidate.path)
+        return false unless guarded.include?(own)
+
+        slot = [candidate.class_name, candidate.kind, candidate.method_name]
+        candidate.inferred_return&.erase_to_rbs == "bot" || providers[slot].any? { |path| path != own }
+      end
+
       # Issue #722 — resolves each recorded superclass token to the class Ruby means by it, and rewrites the
       # emitted spelling when the two differ.
       #
@@ -305,6 +581,10 @@ module Rigor
       def resolve_superclass_spellings(candidates)
         return candidates if @superclass_nestings.empty?
 
+        # Every shell counts here, written or not: the question is which class Ruby means by the token, and the
+        # source declares `Lib::Error` whether or not its file is written. Whether the resolved superclass reaches
+        # disk is {#demote_unresolvable_superclasses}'s question. Counting only written shells would leave `Error`
+        # unresolved, and a top-level `Error` some signature declares would then take it (#2454).
         known = candidates.each_with_object(Set.new) do |candidate, acc|
           acc << candidate.class_name if candidate.class_name
           acc.merge(candidate.class_shells || [])
@@ -324,20 +604,32 @@ module Rigor
         @superclass_nestings.each_with_object({}) do |(full, (nesting, token)), acc|
           next if token.nil? || nesting.empty?
 
-          resolved = resolve_superclass_token(token, nesting, known)
+          resolved = resolve_superclass_token(token, nesting, known, full)
           acc[full] = resolved if resolved && resolved != token
         end
       end
 
       # The first candidate spelling that names a class this run declares or the RBS environment knows, or
-      # nil when none does — an unresolvable superclass is #735's business, not this pass's.
-      def resolve_superclass_token(token, nesting, known)
+      # the token itself when none does — an unresolvable superclass is #735's business, not this pass's.
+      #
+      # `full` is the class whose header carries the token. Ruby evaluates the superclass expression before the
+      # new constant exists, so the innermost candidate `full` itself (`module A; module C; class B < B`, where
+      # `A::C::B` is the class being opened) is not yet a candidate: the lookup falls through to `A::B` (#2579).
+      def resolve_superclass_token(token, nesting, known, full)
+        # A rooted token (`::Hash`) already names one class; the nesting must not capture it (#2459).
+        return token if token.start_with?("::")
+
         base = token.sub(/\[.*\]\z/, "")
-        args = token[base.length..] || ""
         nesting.length.downto(1) do |i|
           candidate = "#{nesting[0, i].join('::')}::#{base}"
-          return "#{candidate}#{args}" if known.include?(candidate) ||
-                                          Reflection.rbs_class_known?(candidate, environment: @environment)
+          next if candidate == full
+
+          # The arguments {#record_superclass} computed belong to the top-level class of the bare name, so they are
+          # computed again for the class the token resolves to: `Hash` inside a `module Foo` declaring a plain
+          # `Foo::Hash` takes none (#2459).
+          return generic_superclass_spelling(candidate) if known.include?(candidate) ||
+                                                           Reflection.rbs_class_known?(candidate,
+                                                                                       environment: @environment)
         end
         token
       end
@@ -370,28 +662,96 @@ module Rigor
       # ran — source discovery and the plugins still type it. Emitting the class with the superclass merely
       # OMITTED would be the harmful middle: the class becomes RBS-known with only the emitted methods, so
       # every inherited call fires `call.undefined-method`.
+      #
+      # Demoting a class can leave a file with nothing to write, which takes the class shells riding on it off the
+      # emitted set, so the pass repeats until no further class becomes unresolvable. The emitted set only shrinks,
+      # so the unresolvable set only grows and the loop ends.
       def demote_unresolvable_superclasses(candidates)
         superclasses = candidates.each_with_object({}) do |candidate, acc|
           (candidate.class_superclasses || {}).each { |name, sup| acc[name] = sup }
         end
-        # Everything this run declares, superclass or not: a chain that reaches `class Record` — emitted
-        # here, with no superclass of its own — terminates in a class the next run WILL know.
-        emitted = candidates.each_with_object(Set.new) do |candidate, acc|
-          acc << candidate.class_name if candidate.class_name
-          acc.merge(candidate.class_shells || [])
+        current = candidates
+        unresolvable = {}
+        loop do
+          found = unresolvable_superclass_roots(superclasses, declared_by_run(current))
+          return current if found.size == unresolvable.size
+
+          unresolvable = found
+          current = candidates.map do |candidate|
+            owner = unresolvable_for(candidate.class_name, unresolvable)
+            candidate = record_unresolvable_superclass(candidate, owner) if owner
+            drop_unresolvable_shells(candidate, unresolvable)
+          end
+        end
+      end
+
+      # Issue #2715 — a nested declaration's class shell rides on a surviving sibling's candidate (`class QueryColumn`
+      # beside `class Query < BaseRecord` wrapping `class QueryError`), so demoting the container's own candidates
+      # leaves the shell, and the writer renders the container around it with the unresolvable superclass: the next
+      # `check` fails `RBS::NoSuperclassFoundError`. A shell inside a demoted class goes with it, like a demoted
+      # class's own members, and a demoted candidate sheds them too: a shell left on one would still count as emitted
+      # ({#declared_by_run}), so a written subclass of the dropped nested class would fail its build.
+      # Writing the container bare instead would make it RBS-known without its ancestry, which
+      # a later run (or a path-subset run) would take for a resolvable superclass of its subclasses.
+      def drop_unresolvable_shells(candidate, unresolvable)
+        shells = (candidate.class_shells || []).to_a
+        kept = shells.reject do |name|
+          owner = unresolvable_for(name, unresolvable)
+          @unresolvable_superclasses[owner.first] ||= owner.last if owner
+          owner
         end
-        unresolvable = superclasses.each_with_object({}) do |(name, _sup), acc|
+        kept.size == shells.size ? candidate : candidate.with_class_shells(kept)
+      end
+
+      def unresolvable_superclass_roots(superclasses, emitted)
+        superclasses.each_with_object({}) do |(name, _sup), acc|
           root = unresolved_superclass_root(name, superclasses, emitted)
           acc[name] = root if root
         end
-        return candidates if unresolvable.empty?
-
-        candidates.map do |candidate|
-          owner = unresolvable_for(candidate.class_name, unresolvable)
-          next candidate if owner.nil?
+      end
 
-          record_unresolvable_superclass(candidate, owner)
+      # Everything this run puts on disk, superclass or not: a chain that reaches `class Record` — emitted here, with
+      # no superclass of its own — terminates in a class the next run WILL know. Only what the writer is sure to
+      # write counts, because a subclass written against a class nothing declares fails its build
+      # (`RBS::NoSuperclassFoundError`) on the next run:
+      #
+      # - a class with a candidate the writer is sure to write ({#written?}). A class whose every method is skipped
+      #   is not written, so it does not count (#2437); a class shell on it would close it instead (#2438);
+      # - a class shell on a file with such a candidate: a shell on a file whose every method is skipped, already
+      #   declared by `sig/`, or a tighter return the writer will not apply never reaches disk (#2454);
+      # - the wrapper namespaces of either, which the writer renders around them with their recorded superclasses.
+      #
+      # Counting too few only demotes a subclass, the output before #2454 (ADR-5).
+      def declared_by_run(candidates)
+        written = candidates.select { |candidate| written?(candidate) }
+        written_paths = written.to_set(&:path)
+        declared = Set.new
+        written.each { |candidate| declared << candidate.class_name if candidate.class_name }
+        candidates.each do |candidate|
+          declared.merge(candidate.class_shells || []) if written_paths.include?(candidate.path)
         end
+        declared.flat_map { |name| wrapper_names(name) }.to_set | declared
+      end
+
+      # `A::B::C` is written inside `A` and `A::B`.
+      def wrapper_names(name)
+        segments = name.split("::")
+        (1...segments.size).map { |n| segments.first(n).join("::") }
+      end
+
+      # Whether the writer will put `candidate` on disk: a candidate it is sure to write ({Writer.writes?}), and,
+      # when the run writes or compares files (`--write`, `--check`), aimed at a target that writer will write to
+      # (#2461). Print, diff and JSON runs have no writer: where a file would go depends on the working directory
+      # the writer takes its sig root from, and their output must not.
+      def written?(candidate)
+        return false unless Writer.writes?(candidate)
+        return true if @target_writer.nil?
+
+        target = @target_writer.path_mapper.target_for(candidate.path, class_name: candidate.class_name,
+                                                                       method_name: candidate.method_name,
+                                                                       kind: candidate.rbs_kind)
+        @writable_targets[target] = @target_writer.accepts_target?(target) unless @writable_targets.key?(target)
+        @writable_targets[target]
       end
 
       # A nested class or module goes with its wrapper. `WikiPage::Webhookable`'s declaration is emitted
@@ -417,9 +777,9 @@ module Rigor
         return superclass if seen[name]
 
         seen[name] = true
-        # The recorded spelling may carry the type arguments {#generic_superclass_spelling} added; the
-        # resolvability question is about the class, so it is asked of the bare name.
-        base = superclass.sub(/\[.*\]\z/, "")
+        # The recorded spelling may carry the type arguments {#generic_superclass_spelling} added, and a rooted
+        # token its `::` (#2459); the resolvability question is about the class, so it is asked of the bare name.
+        base = bare_superclass_name(superclass)
         return nil if Reflection.rbs_class_known?(base, environment: @environment)
         return superclass unless emitted.include?(base)
 
@@ -460,30 +820,56 @@ module Rigor
         end.uniq
       end
 
-      # #1154 — the project's discovery tables, read only by the declared-parameter ivar credit: it must see the ivar
-      # writers in other files (an ancestor, another object's `instance_variable_set`, a reopening) as `rigor check`
-      # does. Built once per run over the configured project paths as well as the files sig-gen reads, so a run over
-      # one file declines what a `check` of it declines; every other part of the generator keeps its per-file scope.
-      def ivar_writer_scope(base_scope)
-        @ivar_writer_tables ||= Inference::ProjectSeedTables.for_paths(
+      # #1154 / #2300 — the project's discovery tables, built once per run over the configured project paths as well
+      # as the files sig-gen reads, so a run over one file reads what a `check` of it reads. Every file is indexed
+      # over them ({#file_base_scope}): a helper, an ancestor or a constant another file defines resolves as it does
+      # under `check` instead of reading ABSENT. The declared-parameter ivar credit reads them whole
+      # ({#ivar_writer_scope}).
+      def project_tables
+        @project_tables ||= Inference::ProjectSeedTables.for_paths(
           ((@resolved_paths || []) + resolve_paths(Array(@configuration.paths))).uniq { |path| File.expand_path(path) }
         )
-        base_scope.with_discovery(base_scope.discovery.with(**@ivar_writer_tables))
+      end
+
+      # The member layouts stay per-file. sig-gen writes a value class for every `Data.define` / `Struct.new` layout
+      # the indexed scope carries ({#collect_meta_layouts}), so a seeded layout would re-emit every value class of the
+      # project in every file.
+      PER_FILE_TABLES = %i[data_member_layouts struct_member_layouts].freeze
+      private_constant :PER_FILE_TABLES
+
+      # #1154 — the declared-parameter ivar credit must see the ivar writers in other files (an ancestor, another
+      # object's `instance_variable_set`, a reopening) as `rigor check` does.
+      def ivar_writer_scope(base_scope)
+        base_scope.with_discovery(base_scope.discovery.with(**project_tables))
       end
 
       # #1406 — sig-gen keeps the census's own answer: a declared ivar type read back would echo the declaration.
+      # #2489 — `base_scope` names the file, so the class-ivar census joins the writes another file's reopening and
+      # the class's ancestors make ({Inference::ScopeIndexer::IvarContributions}), as `rigor check`'s does.
       def index_file(root, base_scope)
         Inference::ScopeIndexer.index(
           root, default_scope: base_scope, ivar_writer_scope: ivar_writer_scope(base_scope), declared_ivar_types: false
         )
       end
 
+      # The scope each file is indexed under: the project's tables less the per-file ones ({#project_tables}), and the
+      # run's return-memo token (see {#run}), which {#ivar_writer_scope} inherits, so every reading of a callee shares
+      # one memo bucket. Built once per run.
+      def file_base_scope(environment)
+        @file_base_scope ||= begin
+          base = Scope.empty(environment: environment)
+          tables = project_tables.except(*PER_FILE_TABLES)
+          tables = tables.merge(run_generation: @run_generation) if @run_generation
+          base.with_discovery(base.discovery.with(**tables))
+        end
+      end
+
       def analyse_file(path, environment)
         source = File.read(path)
         parse_result = Prism.parse(source, filepath: path, version: @configuration.target_ruby)
         return [] if parse_result.errors.any?
 
-        scope_index = index_file(parse_result.value, Scope.empty(environment: environment))
+        scope_index = index_file(parse_result.value, file_base_scope(environment).with_source_path(path))
 
         reset_file_maps
         @meta_layouts = collect_meta_layouts(scope_index)
@@ -518,11 +904,12 @@ module Rigor
       #
       # Only a definer whose statement certainly runs can be last: a direct statement of a `class`, `module` or
       # `class << self` body, of a `Data.define` / `Struct.new` block or of the file ({#walk_statements} records
-      # them). One under a condition, in a block or a lambda, passed to a call (`private def x`), or after an
-      # uncertain `module_function` reset may not run, as far as this reading tells. A slot such a definer could
+      # them), or a `def` passed to `private`, `public` or `protected` in such a statement ({#walk_statements}, #2254).
+      # One under a condition, in a block or a lambda, or after an uncertain `module_function` reset may not run, as
+      # far as this reading tells. A slot such a definer could
       # still take over from the last certain one is contested, and nothing is written for it.
       #
-      # @return `{ [class_name, kind, method_name] => [[offset, certain], ...] }`.
+      # @return the definers of each slot as `[offset, certain]` pairs, keyed by `[class_name, kind, method_name]`.
       MEMBER_OFFSET = -1
       private_constant :MEMBER_OFFSET
 
@@ -635,6 +1022,8 @@ module Rigor
         @in_effect_refinements = nil
         out = []
         @block_depth = 0
+        @hook_blocks = {}.compare_by_identity
+        @hook_block_prefixes = []
         @certain_bodies = Set.new.compare_by_identity
         @certain_definers = Set.new.compare_by_identity
         mark_certain_body(root.statements)
@@ -649,7 +1038,9 @@ module Rigor
         when Prism::ClassNode, Prism::ModuleNode
           return if descend_into_namespace?(node, prefix, out)
         when Prism::SingletonClassNode
-          if node.expression.is_a?(Prism::SelfNode) && node.body
+          # `class << M` inside `module M` opens the same singleton as `class << self` (#3155).
+          if node.body && (node.expression.is_a?(Prism::SelfNode) ||
+                           Inference::ScopeIndexer.def_receiver_targets_lexical_self?(node.expression, prefix))
             mark_certain_body(node.body)
             walk_defs(node.body, prefix, true, false, out)
             return
@@ -677,16 +1068,37 @@ module Rigor
       # the `self` one returns above): it defines a singleton method on `obj`, not a private `Object` method.
       def walk_def_children(node, prefix, in_singleton_class, module_function_active, out)
         return if refine_block_call?(node)
+        # #2259 — a `def` in `class_methods do … end` (ActiveSupport::Concern) defines a method of the including class's
+        # singleton, not of this module. Omitted, not written class-side: no precedent places it on the singleton.
+        return if class_methods_block?(node)
 
         in_block = node.is_a?(Prism::BlockNode) || node.is_a?(Prism::LambdaNode) ||
                    node.is_a?(Prism::SingletonClassNode)
         @block_depth += 1 if in_block
+        hook_block = @hook_blocks.key?(node)
+        @hook_block_prefixes.push(prefix) if hook_block
         node.rigor_each_child do |child|
           walk_defs(child, prefix, in_singleton_class, module_function_active, out)
         end
+        @hook_block_prefixes.pop if hook_block
         @block_depth -= 1 if in_block
       end
 
+      # Issue #3015 — the `included do … end` / `prepended do … end` statements of a body that runs `extend
+      # ActiveSupport::Concern`: Ruby runs the block in the includer's class body, so a `def self.x` or `class << self`
+      # def there is the includer's singleton method, not the module's, and {#collect_def_node} leaves it out.
+      def mark_hook_blocks(namespace_node, prefix)
+        body = namespace_node.body
+        return unless namespace_node.is_a?(Prism::ModuleNode) && Inference::ScopeIndexer.concern_body?(body, prefix)
+
+        body.body.each do |statement|
+          next unless statement.is_a?(Prism::CallNode) && statement.receiver.nil? &&
+                      %i[included prepended].include?(statement.name) && statement.block.is_a?(Prism::BlockNode)
+
+          @hook_blocks[statement] = true
+        end
+      end
+
       # [#722](https://github.com/rigortype/rigor/issues/722) residue 3 — the qualified name is built by
       # `Source::ConstantPath.declaration_prefix`, the same reader the engine's declaration walks use, so a
       # ROOTED header re-anchors here too. Appending the rendered name to the enclosing prefix wrote
@@ -706,6 +1118,7 @@ module Rigor
 
         full = child_prefix.join("::")
         @namespace_kinds[full] = node.is_a?(Prism::ClassNode) ? :class : :module
+        @source_classes << full if node.is_a?(Prism::ClassNode)
         record_superclass(node, full, prefix)
         walk_namespace_body(node, child_prefix, out)
         true
@@ -725,6 +1138,17 @@ module Rigor
         !@in_effect_refinements.class_body_refine?(node)
       end
 
+      # A block call whose members are not this class body's: a `refine` block (#1763), and a `class_methods` block
+      # (#2259), whose members belong to the including class's singleton.
+      def skipped_block_call?(node)
+        refine_block_call?(node) || class_methods_block?(node)
+      end
+
+      def class_methods_block?(node)
+        node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name == :class_methods &&
+          node.block.is_a?(Prism::BlockNode)
+      end
+
       def declined_self_header?(node)
         path = node.constant_path
         path.is_a?(Prism::ConstantPathNode) && path.parent.is_a?(Prism::SelfNode) &&
@@ -750,10 +1174,43 @@ module Rigor
         # the name it resolves to may be a class another file declares. Resolved once every file has been
         # walked, in {#resolve_superclass_spellings}.
         spelling = generic_superclass_spelling(superclass)
+        # Issue #2579 — a token that names the class being opened (`class A::B < A::B`, or a top-level `class B < B`
+        # with nothing else of that name) would write a self-superclass, which RBS rejects as a recursive ancestor.
+        # No superclass is safer than that, so the declaration is written without one.
+        return if bare_superclass_name(spelling) == full
+
         # The token rides along because `@class_superclasses` is per-FILE scratch, reset before the next
         # file, while this table is whole-run.
         @superclass_nestings[full] = [prefix.dup, spelling]
         @class_superclasses[full] = spelling
+        register_core_subclass_shell(full, prefix, superclass)
+      end
+
+      # Issue #2224 — a subclass of a core or stdlib class got a declaration only when it had a method of its own to
+      # emit, so after `class MyHash < Hash; end` a method returning one was written `-> MyHash` against a class no
+      # signature declared, and `rbs validate` failed with `NoTypeFoundError`. As a class shell it is declared
+      # `class MyHash < ::Hash[untyped, untyped]` beside the file's other declarations. A class the RBS environment
+      # already declares (the project's `sig/`, an earlier run) is left to that declaration, and a superclass the
+      # header's nesting shadows is not core's: `Hash` inside a `module Foo` that declares `Foo::Hash` is the project's.
+      # A rooted `::Hash` names core's class whatever the nesting declares, so the shadow cannot capture it (#2459).
+      def register_core_subclass_shell(full, prefix, superclass)
+        return if class_known?(full)
+
+        bare = bare_superclass_name(superclass)
+        return unless @environment&.rbs_loader&.core_or_stdlib_class?(bare)
+
+        unless superclass.start_with?("::")
+          namespaces = TypeNameQualification.enclosing_namespaces(prefix.join("::"))
+          return if TypeNameQualification.shadowed?(bare.split("::").first, namespaces, method(:declared_constant?))
+        end
+
+        @class_shells << full
+      end
+
+      # The class a recorded superclass token names, as the fully qualified key every class-name set and the RBS
+      # loader use: the type arguments {#generic_superclass_spelling} added and a rooted token's `::` both dropped.
+      def bare_superclass_name(token)
+        token.sub(/\[.*\]\z/, "").delete_prefix("::")
       end
 
       # Issue #735 — a GENERIC superclass has to be written with its arguments. `class Entries < Array`
@@ -766,7 +1223,7 @@ module Rigor
         loader = @environment&.rbs_loader
         return superclass if loader.nil?
 
-        arity = loader.class_type_param_names(superclass).size
+        arity = loader.class_type_param_names(bare_superclass_name(superclass)).size
         return superclass if arity.zero?
 
         "#{superclass}[#{(['untyped'] * arity).join(', ')}]"
@@ -814,6 +1271,7 @@ module Rigor
         @meta_layouts.each do |class_name, layout|
           @namespace_kinds[class_name] = :class
           @class_shells << class_name
+          @source_classes << class_name
           @class_superclasses[class_name] = MetaClassShape::SUPERCLASSES.fetch(layout.kind)
         end
       end
@@ -840,6 +1298,7 @@ module Rigor
         return if namespace_node.body.nil?
 
         mark_certain_body(namespace_node.body)
+        mark_hook_blocks(namespace_node, prefix)
         walk_defs(namespace_node.body, prefix, false, false, out)
       end
 
@@ -862,6 +1321,8 @@ module Rigor
             @certain_definers << stmt
             # A `begin … end` statement's body (and `ensure`) runs whenever the statement does.
             mark_certain_body(stmt) if stmt.is_a?(Prism::BeginNode)
+            # A `def` passed to a visibility call (`private def x`, #2254) runs with its statement.
+            @certain_definers.merge(Inference::ModuleFunctionState.visibility_call_defs(stmt))
           end
           walk_defs(stmt, prefix, in_singleton_class, active, out)
         end
@@ -876,7 +1337,12 @@ module Rigor
           return
         end
 
-        kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+        # `def Foo.x` inside `module Foo` is `def self.x` (#2950), and a def on another object's singleton is no method
+        # of this class (#3155); the rule is the one check indexes defs by.
+        kind = Inference::ScopeIndexer.def_side(node, prefix, in_singleton_class)
+        return if kind.nil?
+        return if kind == :singleton && @hook_block_prefixes.last == prefix
+
         class_name = prefix.join("::")
         if Inference::ModuleFunctionState.sig_gen_module_function?(module_function_active, kind)
           @module_function_methods << node
@@ -959,8 +1425,8 @@ module Rigor
       # `Object#initialize: () -> void`. The mismatch surfaces a `Ruby::MethodParameterMismatch` warning even
       # when `rigor check` itself is clean.
       #
-      # Returning `nil` here causes `classify_def` to skip emission; returning `:emit_stub` causes
-      # `initialize_stub_candidate` to emit a permissive `(<param shape>) -> void` stub matching the runtime
+      # A default constructor is skipped (`classify_def` returns nil for it); a non-trivial one is not, and
+      # {#initialize_stub_candidate} emits a permissive `(<param shape>) -> void` stub matching the runtime
       # parameter list.
       def initialize_excludes?(def_node, kind)
         return false unless kind == :instance
@@ -1088,25 +1554,36 @@ module Rigor
       # return position it is not parenthesised.
       def positional_type(observations, index, prefix, owner = nil)
         types = observations.filter_map { |obs| obs.positional[index] }
-        "#{prefix}#{union_erase(types, owner: owner)}"
+        "#{prefix}#{union_erase(widen_observed_params(types), owner: owner)}"
       end
 
       def render_keyword_param(keyword, observations, owner = nil)
         optional_marker = keyword.is_a?(Prism::OptionalKeywordParameterNode) ? "?" : ""
         types = observations.filter_map { |obs| obs.keyword[keyword.name] }
-        rendered = types.empty? ? "untyped" : paren_wrap_union(union_erase(types, owner: owner))
+        rendered = types.empty? ? "untyped" : paren_wrap_union(union_erase(widen_observed_params(types), owner: owner))
         "#{optional_marker}#{keyword.name}: #{rendered}"
       end
 
+      # #2254 — an observed argument is one call's value, so a literal (`"hello"`) proposes its class (`String`), as
+      # {#widen_value_literals} does for a return. Widening always: a parameter the body only compares against a
+      # literal (a discriminant) is widened too, which loses precision and never adds a false positive.
+      def widen_observed_params(types)
+        types.map { |type| widen_value_literals(type) }
+      end
+
+      # Issue #2459 — a ROOTED path (`::Hash`, `::A::B`) keeps its leading `::`: it names exactly one class, and the
+      # passes after {#record_superclass} must not re-resolve it against the header's nesting, where a project
+      # `Foo::Hash` would capture it. Every pass that compares the token against class names strips the anchor.
       def qualified_constant_path(constant_path)
         case constant_path
         when Prism::ConstantReadNode
           constant_path.name.to_s
         when Prism::ConstantPathNode
-          parent = qualified_constant_path(constant_path.parent) if constant_path.parent
           name = constant_path.name&.to_s
           return nil if name.nil?
+          return "::#{name}" if constant_path.parent.nil?
 
+          parent = qualified_constant_path(constant_path.parent)
           parent ? "#{parent}::#{name}" : name
         end
       end
@@ -1485,7 +1962,7 @@ module Rigor
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
-        unless tighter?(declared, inferred) && !literal_decline?(inferred, def_node)
+        unless tighter?(declared, inferred) && !literal_decline?(inferred, def_node, declared)
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
@@ -1520,16 +1997,16 @@ module Rigor
       # about the return. The class's own declaration is kept whole instead: its visibility, the overload's
       # annotations, type parameters, parameters and block, with only the return replaced.
       #
-      # Three shapes are declined (`nil`):
+      # Two shapes are declined (`nil`):
       # - several overloads. The body is typed once, so the inferred return covers every overload together and
       #   says nothing about which overload returns what: collapsing them into one line would drop the
       #   overloads, and giving each the joint return would widen the overloads the author wrote narrower.
       # - a name the class's own `sig/` spells as an `alias`. Its parameters are the aliased method's, and a
       #   proposal would read as a rewrite of that method's line rather than of the alias. An alias only an
       #   ancestor declares takes the override path below, like any other ancestor declaration.
-      # - nothing else: when only an ancestor declares the method, the proposal is a new override on this
-      #   class, and is rendered from the `def`'s own shape like any new method. The ancestor's parameters
-      #   describe the ancestor's `def`, not this one, which may take other arguments (ADR-14 clause 2).
+      # A method this class does not declare is not declined: when only an ancestor declares it, the proposal is a
+      # new override on this class, rendered from the `def`'s own shape like any new method. The ancestor's
+      # parameters describe the ancestor's `def`, not this one, which may take other arguments (ADR-14 clause 2).
       def tighter_return_line(def_node, method_def, class_name, kind, inferred)
         member = signature_member(method_def, class_name)
         return render_rbs_line(def_node, inferred, class_name, kind) if member.nil?
@@ -1774,11 +2251,24 @@ module Rigor
 
       def structurally_covers?(inferred_member, declared_member)
         return true if inferred_member == declared_member
+        return true if nominal_subclass_of?(inferred_member, declared_member)
 
         result = inferred_member.accepts(declared_member)
         result.respond_to?(:yes?) && result.yes?
       end
 
+      # Issue #2914 — a proposed member that is a subclass of the declared one keeps that member: declared
+      # `Prism::Node?` against an inferred `Prism::DefNode?` narrows what a caller receives without dropping a
+      # branch the caller could observe, unlike a lost `nil` or a lost alternate. Only a bare nominal pair whose
+      # ordering the analyzer's class data decides (`Environment#class_ordering`, RBS hierarchy included) is
+      # read this way; a generic pair or an `:unknown` ordering stays uncovered, so the guard still declines.
+      def nominal_subclass_of?(inferred_member, declared_member)
+        return false unless inferred_member.is_a?(Type::Nominal) && declared_member.is_a?(Type::Nominal)
+        return false unless inferred_member.type_args.empty? && declared_member.type_args.empty?
+
+        @environment&.class_ordering(inferred_member.class_name, declared_member.class_name) == :subclass
+      end
+
       GENERIC_COLLECTION_CLASSES = %w[
         Array Hash Set Range Enumerable Enumerator Enumerator::Lazy
       ].freeze
@@ -1794,8 +2284,8 @@ module Rigor
       # The two reasons a `Type::Constant` the body proves is not the method's contract. Both say the same
       # thing from opposite ends: the precision is real about this body and says nothing about the promise
       # the method makes to its callers.
-      def literal_decline?(inferred, def_node)
-        computed_literal_tightening?(inferred, def_node) || pins_literal_over_declaration?(inferred)
+      def literal_decline?(inferred, def_node, declared)
+        computed_literal_tightening?(inferred, def_node) || pins_literal_over_declaration?(inferred, declared)
       end
 
       # Issue #837 — a proposal that erases to an RBS LITERAL type never tightens an existing declaration.
@@ -1820,9 +2310,14 @@ module Rigor
       # is refused when ANY member is a literal: a mixed `("a" | Float)` pins `"a"` just as a bare one does.
       # A literal nested inside a shape carrier (`[1, 2]`, a `HashShape` value) is a different question,
       # already answered for the collection declarations that matter by {#narrows_collection_to_shape?}.
-      def pins_literal_over_declaration?(inferred)
+      #
+      # A literal the declaration itself spells is not pinned over it (#2914): declared `Prism::Node?` against
+      # a proposed `Prism::DefNode?` carries the same `nil` member the author wrote, so only the narrowed
+      # nominal arm is new. A literal the declaration does not spell is refused as before.
+      def pins_literal_over_declaration?(inferred, declared)
         members = inferred.is_a?(Type::Union) ? inferred.members : [inferred]
-        members.any? { |member| rbs_literal?(member) }
+        declared_members = declared.is_a?(Type::Union) ? declared.members : [declared]
+        members.any? { |member| rbs_literal?(member) && !declared_members.include?(member) }
       end
 
       # `Type::Constant#erase_to_rbs` spells the values RBS writes as literal types (`true` / `false` /
@@ -1912,8 +2407,35 @@ module Rigor
       # `owner:` is the class or module the rendered member belongs to. {AliasIndex} needs it to judge whether
       # a matching alias is one this reader would expect to see; a call site that cannot supply it renders the
       # type unfolded, which is the same output as before #1002.
+      #
+      # Issue #2230 — qualified last, after the alias fold has matched the unqualified spelling it keys on, so a core
+      # name a namespace of the owner shadows (`Set` inside a `module Foo` that declares `Foo::Set`) is written `::Set`.
       def elaborated_rbs(type, owner: nil)
-        alias_index.fold(TypeElaborator.elaborate(type, environment: @environment).erase_to_rbs, owner)
+        folded = alias_index.fold(TypeElaborator.elaborate(type, environment: @environment).erase_to_rbs, owner)
+        captured = owner_type_param_names(owner)
+        TypeNameQualification.qualify(folded, owner) { |name| captured.include?(name) || declared_constant?(name) }
+      end
+
+      # Issue #2436 — inside `class Array[unchecked out E]` a bare `E` names the type variable, not a class `::E`,
+      # so a class whose spelling equals one of the owner's declared type-parameter names is anchored. The names
+      # come as `"Array::E"`, the form {TypeNameQualification.qualify} asks about for the owner's own namespace;
+      # a namespace the owner is nested in does not bind its parameters inside the owner's declaration.
+      def owner_type_param_names(owner)
+        loader = owner && @environment&.rbs_loader
+        return Set.new if loader.nil?
+
+        @owner_type_param_names ||= {}
+        @owner_type_param_names.fetch(owner) do
+          @owner_type_param_names[owner] = loader.class_declaration_type_params(owner).to_set do |p|
+            "#{owner}::#{p.name}"
+          end
+        end
+      end
+
+      # Whether a type name written as `name` resolves to a constant the run can see: one the RBS environment
+      # declares, or a class or module the project's source declares, whether or not `sig/` has caught up with it.
+      def declared_constant?(name)
+        class_known?(name) || Reflection.discovered_class?(name, scope: file_base_scope(@environment))
       end
 
       # Issue #1002 — the reverse of {#translate_method_type_return}'s `alias_expander:`. Folding happens here,
@@ -2044,7 +2566,7 @@ module Rigor
             return
           end
         when Prism::CallNode
-          return if refine_block_call?(node)
+          return if skipped_block_call?(node)
 
           collect_attr_call(node, prefix, in_singleton_class, ctx)
         end
@@ -2151,8 +2673,8 @@ module Rigor
         end
       end
 
-      # Build a { class_name => { attr_name_sym => Type } } map that records observation-derived types for
-      # ivars assigned directly from `def initialize` parameters. Only populated when `@observations` is
+      # Records the observation-derived types of ivars assigned directly from `def initialize` parameters, keyed
+      # by class name and then attribute name. Only populated when `@observations` is
       # non-empty (i.e. `--params=observed` was supplied). Matches the pattern `@ivar_name = param_name` where
       # `param_name` is a required / optional positional or keyword parameter of `initialize`.
       #
@@ -2285,7 +2807,7 @@ module Rigor
         node.rigor_each_child { |c| collect_init_ivar_obs(c, prefix, result) }
       end
 
-      # Derive { attr_name_sym => Type } for a single `def initialize` by matching `@ivar = param_name`
+      # Derives the observation-derived attribute types of a single `def initialize`, matching `@ivar = param_name`
       # assignments against the available `[class_name, :initialize]` observations.
       def ivar_obs_from_initialize(class_name, def_node)
         obs_list = @observations[[class_name, :initialize]]
@@ -2300,8 +2822,8 @@ module Rigor
         build_ivar_obs_type_map(ivar_to_param, param_index, obs_list)
       end
 
-      # Map `{ ivar_name => param_name }` → `{ attr_name_sym => Type }` by looking up each param's observation
-      # types and unioning them.
+      # Maps `{ ivar_name => param_name }` to attribute types by looking up each param's observation types and
+      # unioning them.
       def build_ivar_obs_type_map(ivar_to_param, param_index, obs_list)
         ivar_to_param.filter_map do |ivar_name, param_name|
           types = collect_param_obs_types(obs_list, param_name, param_index[param_name])