rigortype 0.3.9 → 0.4.0

data/lib/rigor/environment/rbs_loader.rb

@@ -4,7 +4,9 @@ require "rbs"
 
 require_relative "../type"
 require_relative "../inference/rbs_type_translator"
+require_relative "../builtins/imported_refinements"
 require_relative "rbs_hierarchy"
+require_relative "member_consistency"
 
 module Rigor
   class Environment
@@ -42,6 +44,19 @@ module Rigor
       # cache HIT. Never a real path, so it must never be reported as one (issue #696).
       CACHED_LOCATION_BUFFER_NAME = "<cached>"
 
+      # Issue #527 — the two directory trees whose `.rbs` files ARE Ruby's own surface: the `rbs` gem's
+      # `core/` and its bundled `stdlib/` repository. {#core_stdlib_classes} tests a declaration's file
+      # against them. Resolved once at load time, on the main Ractor: reading these constants walks a
+      # chain of non-`Ractor.shareable?` module constants and raises `Ractor::IsolationError` inside a
+      # worker (see {#prewarm}). Empty when the rbs version in use does not expose them, which switches
+      # the feature off rather than widening it.
+      CORE_STDLIB_ROOTS = begin
+        [::RBS::EnvironmentLoader::DEFAULT_CORE_ROOT, ::RBS::Repository::DEFAULT_STDLIB_ROOT]
+          .compact.map { |root| "#{root}/".freeze }.freeze
+      rescue StandardError
+        [].freeze
+      end
+
       # Cap on how many quarantined `signature_paths:` files {#warn_about_quarantined_signatures} lists by name
       # before collapsing the tail to "… and N more" — a broken generator can emit many, and a wall of parse
       # errors buries the signal.
@@ -83,9 +98,13 @@ module Rigor
           # mastodon coverage note). Per-file loading quarantines the broken file instead. Vendored / core-overlay
           # sigs are Rigor-shipped and trusted, so they stay on the loader's fast batch path.
           add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s))
-          env = RBS::Environment.from_loader(rbs_loader)
+          env = unload_upstream_core_shims(RBS::Environment.from_loader(rbs_loader), rbs_loader)
           project_files = project_sig_files(signature_paths)
-          add_project_signatures(env, signature_paths, deferred_signature_paths)
+          # Issue #1075 — decided from the inputs before either side enters `env`: the consistency rule may
+          # stand the `.rbs` member down, and that has to happen before its file is added.
+          consistency = member_consistency_for(project_files, virtual_rbs)
+          add_project_signatures(env, signature_paths, deferred_signature_paths,
+                                 standdowns: consistency.signature_standdowns)
           # Issue #928 — the capability-role catalog goes in AFTER the project's own signatures, per
           # declaration, so a project that already declares one of these interface names keeps its own
           # (`add_capability_role_signatures`). The rest of the bundled RBS cannot be ordered that way (it
@@ -93,10 +112,9 @@ module Rigor
           # instead — and losing a whole `sig/` file to a name as ordinary as `_Closable` is exactly what
           # shipping a top-level interface catalog would otherwise cost.
           add_capability_role_signatures(env)
-          # Issue #824 — the project's own signatures are already in `env` at this point, so the inline
-          # contribution can be asked the question that keeps the two from colliding: which of its members
-          # does a `.rbs` file already declare? Those stand down per member ({.add_virtual_rbs}).
-          add_virtual_rbs(env, virtual_rbs, sig_member_owners: signature_member_owners(project_files, virtual_rbs))
+          # Issues #824 / #1075 — every member a `.rbs` file also declares was ranked above; the inline side of
+          # each pair the `.rbs` won stands down here ({.add_virtual_rbs}), so the two never collide.
+          add_virtual_rbs(env, virtual_rbs, inline_standdowns: consistency.inline_standdowns)
           synthesize_missing_namespaces(env)
           # Issue #777 — resolve-time backstop: also unload colliding PROJECT buffers (class-vs-module /
           # constant redeclarations against bundled RBS). Virtual culprits are preferred when both appear.
@@ -155,6 +173,55 @@ module Rigor
           false
         end
 
+        # Issue #1109 — the `rbs` gem (a `DEFAULT_LIBRARIES` entry, so in every run) ships the shims its
+        # own Steep check needs under `sig/shims/`, and one of them reopens a core module: `enumerable.rbs`
+        # prepends a `(2) -> Enumerator[[Elem, Elem], void]` overload to `Enumerable#each_slice`. That is
+        # a claim about rbs's own call sites, not about Ruby — `[1, 2, 3].each_slice(2)` yields `[3]` last
+        # — and it leaked into every analysed project: the blockless form typed as a fixed pair (so a
+        # `nil` guard on the second slot folded away) and the block form returned `void` instead of the
+        # receiver. Unloading the file leaves core's `Enumerator[Array[Elem], self]`, which agrees with the
+        # block form's `Array[Elem]`. The other shims (`bundler.rbs`, `rubygems.rbs`) only add missing
+        # declarations and stay. Fails soft to the env as built: a relocated or absent shim, or an rbs API
+        # shape this code does not recognise, keeps the pre-#1109 behaviour rather than failing the build.
+        # Because errors are rescued, the guard spec in `rbs_loader_spec.rb` is what catches a broken unload,
+        # so it must stay green on both lines of the RBS compatibility matrix.
+        RBS_LIBRARY = "rbs"
+        private_constant :RBS_LIBRARY
+        UNSOUND_CORE_SHIMS = %w[shims/enumerable.rbs].freeze
+        private_constant :UNSOUND_CORE_SHIMS
+
+        def unload_upstream_core_shims(env, rbs_loader)
+          return env unless env.respond_to?(:unload)
+
+          shim_names = upstream_core_shim_names(rbs_loader)
+          return env if shim_names.empty?
+
+          buffers = loaded_signature_buffers(env)&.select { |buffer| shim_names.include?(buffer.name.to_s) }
+          buffers.nil? || buffers.empty? ? env : env.unload(buffers)
+        rescue StandardError
+          env
+        end
+
+        # rbs 4.x lists its sources through `each_rbs_source`; rbs 3.x keys `signatures` by `Buffer`, and its
+        # `unload` matches those very objects with `include?`, so the env's own keys are what it must receive.
+        def loaded_signature_buffers(env)
+          if env.respond_to?(:each_rbs_source)
+            env.each_rbs_source.map(&:buffer)
+          elsif env.respond_to?(:signatures)
+            env.signatures.keys
+          end
+        end
+
+        def upstream_core_shim_names(rbs_loader)
+          names = Set.new
+          rbs_loader.each_dir do |source, dir|
+            next unless source.respond_to?(:name) && source.name == RBS_LIBRARY
+
+            UNSOUND_CORE_SHIMS.each { |relative| names << Pathname(dir).join(relative).to_s }
+          end
+          names
+        end
+
         # True when `content` parses as an RBS signature. {#virtual_rbs_collision_quarantined} uses this to
         # tell a collision-dropped virtual entry (parses, but absent from the env) from a parse-failed one
         # (the synthesizer's own WD6 skip, reported separately).
@@ -333,16 +400,21 @@ module Rigor
         # Buffer names are the file's absolute path (matching {.project_sig_files}) so {.project_entry?} — which
         # attributes a `class_decls` entry to the project by buffer name — still recognises these declarations.
         # Sorted for a deterministic add order (the env feeds the cache, ADR-54).
-        def add_project_signatures(env, signature_paths, deferred_paths = [])
+        #
+        # @param standdowns — issue #1075 — `{signature_path => Set[[class, method, kind]]}`, the members an
+        #   inline declaration displaced because it was the more precise side of a consistent pair
+        #   ({MemberConsistency::Resolution#signature_standdowns}). They are removed before the file is added.
+        def add_project_signatures(env, signature_paths, deferred_paths = [], standdowns: {})
           deferred = project_sig_files(deferred_paths)
           (project_sig_files(signature_paths) - deferred).sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
             buffer, directives, decls = parsed
+            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             add_project_parsed_decls(env, buffer, directives, decls)
           end
-          add_deferred_signatures(env, deferred)
+          add_deferred_signatures(env, deferred, standdowns)
         end
 
         # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
@@ -380,7 +452,7 @@ module Rigor
         # (rigor-activerecord's is `relation.rbs`, declaring exactly `Relation`), so dropping the file drops
         # exactly the conflicting declaration. Splitting a plugin file that mixes a colliding class with
         # innocent ones is the change to make if that ever stops being true.
-        def add_deferred_signatures(env, deferred_files)
+        def add_deferred_signatures(env, deferred_files, standdowns = {})
           deferred_files.sort.each do |file|
             parsed = parse_signature_file(file)
             next if parsed.nil?
@@ -388,6 +460,7 @@ module Rigor
             buffer, directives, decls = parsed
             next if generic_arity_conflict(env, decls)
 
+            strip_members!(decls, standdowns[file]) if standdowns.key?(file)
             add_project_parsed_decls(env, buffer, directives, decls)
           end
         end
@@ -827,12 +900,13 @@ module Rigor
         # provenance (RBS parse errors cite it) — it is not a real file path. Per WD6 the synthesizer-emit
         # path is responsible for catching its own parse errors and returning `nil` rather than garbage; this
         # method assumes its input is parseable and only rescues `RBS::ParsingError` as a fail-soft.
-        # @param sig_member_owners — issue #824 — `{[class, method, kind] => signature_path}`
-        #   from {.signature_member_owners}. Every member it names is removed from the inline contribution
-        #   before the declaration is added, so `sig/` wins per MEMBER instead of the two colliding and
-        #   costing the whole class its method surface (ADR-32 WD13). The stand-down is reported, never
-        #   silent: {RbsLoader#inline_member_standdowns} re-derives the same set for the run's `:info` row.
-        def add_virtual_rbs(env, virtual_rbs, sig_member_owners: {})
+        # @param inline_standdowns — issue #1075 — the `[class, method, kind]` keys whose inline member
+        #   stands down because a project `.rbs` declares the same member and ADR-112 WD5's consistency rule
+        #   let the `.rbs` bind ({MemberConsistency::Resolution#inline_standdowns}). Removing them before the
+        #   declaration is added keeps the two from colliding and costing the whole class its method surface.
+        #   The outcome is reported, never silent: {RbsLoader#member_consistency} re-derives the same records
+        #   for the run's rows.
+        def add_virtual_rbs(env, virtual_rbs, inline_standdowns: Set.new)
           return if virtual_rbs.nil? || virtual_rbs.empty?
 
           virtual_rbs.each do |filename, content|
@@ -843,7 +917,7 @@ module Rigor
 
             buffer = ::RBS::Buffer.new(name: filename.to_s, content: content.to_s)
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
-            strip_members_declared_in_signatures!(decls, sig_member_owners) unless sig_member_owners.empty?
+            strip_members!(decls, inline_standdowns) unless inline_standdowns.empty?
             add_parsed_decls(env, buffer, directives, decls)
           rescue ::RBS::BaseError
             # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down — for
@@ -863,7 +937,8 @@ module Rigor
           end
         end
 
-        # Issue #824 / ADR-32 WD13 — the member-level half of inline-vs-`sig/` precedence.
+        # Issue #1075 / ADR-112 WD5 — the member-level half of inline-vs-`sig/` consistency, which replaced
+        # #824's "`sig/` wins per member" (ADR-32 WD13).
         #
         # A method declared BOTH by a project `.rbs` and by an inline annotation in its own `.rb` lands twice
         # in one `RBS::Environment`: rbs merges the two sources into a single `ClassEntry` and ranks neither,
@@ -872,135 +947,149 @@ module Rigor
         # it, real methods and typos alike, reads `Dynamic[top]`. Measured on Rigor's own tree while
         # [#779](https://github.com/rigortype/rigor/pull/779) was evaluated: 17 of 234 annotated files
         # overlapped `sig/`, and the collision took 44 classes down. Steep 2.1 / rbs 4.1 have no precedence
-        # rule to follow here (Steep reports the same collision as a signature diagnostic and the class still
-        # fails to build), so the spec's "SHOULD follow Steep 2.0" pointer resolves to nothing and the choice
-        # is Rigor's: the reviewed, `sig-gen`-managed `.rbs` wins, per member.
+        # rule to follow here (ADR-32 WD13), so exactly one of the two members has to go before the
+        # environment is built. {MemberConsistency} decides which: the more precise of two consistent
+        # declarations binds, and on a contradiction or an undecidable pair the `.rbs` does.
         #
-        # @return `{[class_name, method_name, kind] => signature_path}` for every
-        #   method-shaped member the project's own `signature_paths:` files declare and the inline sources
-        #   also name. Empty — and free — for a project that contributes no inline RBS, which is every
-        #   project without a `source_rbs_synthesizer:` plugin.
+        # @return a {MemberConsistency::Resolution}. {MemberConsistency::EMPTY} — and free — for a project
+        #   that contributes no inline RBS, which is every project without a `source_rbs_synthesizer:` plugin.
+        #
+        # Derived from the loader's INPUTS — the synthesized sources and the project's signature files —
+        # never from a built environment, for {RbsLoader#quarantined_signatures}' reason turned inside out: a
+        # cache HIT never runs the build, and a stripped member leaves no trace in the environment to read
+        # back. The build and {RbsLoader#member_consistency} call this same function on the same two inputs,
+        # so the members they strip and the rows they report agree warm and cold.
+        def member_consistency_for(project_files, virtual_rbs, proof: nil)
+          return MemberConsistency::EMPTY if virtual_rbs.nil? || virtual_rbs.empty?
+
+          signature_members, shadowable = signature_member_index(project_files, virtual_rbs)
+          inline_members = inline_member_entries(virtual_rbs, all: !signature_members.empty?)
+          MemberConsistency.resolve(signature_members, inline_members, shadowable: shadowable, proof: proof)
+        end
+
+        # `[owners, shadowable]`. `owners` is `{[class_name, method_name, kind] => [signature_path, member,
+        # visibility]}` for every method-shaped member the project's own `signature_paths:` files declare and
+        # the inline sources also name; the first file in sorted order owns a key two `.rbs` files declare
+        # (that pair fails the definition build anyway). `shadowable` is every `::` segment of every class /
+        # module name the inline sources and the signature files declare — the names a relative reference
+        # might resolve to inside an enclosing namespace ({MemberConsistency::Comparator#faithful?}).
         #
         # The parse is scoped by a substring pre-filter over each file's text: a declaration has to spell its
         # own name, so a signature file mentioning none of the names the inline sources declare cannot
         # collide with them. The filter over-approximates (it matches a name in a comment or a type position
         # too), so it can only cost an unnecessary parse, never miss a collision.
-        def signature_member_owners(project_files, virtual_rbs)
-          return {} if project_files.nil? || virtual_rbs.nil? || virtual_rbs.empty?
-
+        def signature_member_index(project_files, virtual_rbs)
           names = inline_declared_name_segments(virtual_rbs)
-          return {} if names.empty?
+          return [{}, names] if project_files.nil? || project_files.empty? || names.empty?
 
-          project_files.to_a.sort.each_with_object({}) do |file, owners|
-            decls = parse_signature_file_if_mentions(file, names)
-            next if decls.nil?
+          shadowable = names.dup
+          owners = project_files.to_a.sort.each_with_object({}) do |file, index|
+            content = read_signature_text(file)
+            next if content.nil?
 
-            each_declared_member(decls) do |class_name, member|
-              member_method_keys(member).each do |method_name, kind|
-                owners[[class_name, method_name, kind]] ||= file
-              end
-            end
+            merge_declared_segments(content, shadowable)
+            next if names.none? { |name| content.include?(name) }
+
+            index_signature_members(index, file, parse_signature_source(file, content))
           end
+          [owners, shadowable]
         end
 
-        # The `[class, method, kind, signature_path, virtual_buffer_name]` record for every inline member
-        # {.add_virtual_rbs} stands down, sorted and deduplicated.
-        #
-        # Derived from the loader's own INPUTS — the synthesized sources and the project's signature files —
-        # never from the built environment, for {RbsLoader#quarantined_signatures}' reason turned inside out:
-        # a cache HIT never runs the build, and the stripped member leaves no trace in the environment to
-        # read back. The same two inputs answer identically warm and cold, which is what makes the reported
-        # set independent of cache state.
-        def inline_member_standdowns_for(signature_paths:, virtual_rbs:)
-          owners = signature_member_owners(project_sig_files(signature_paths), virtual_rbs)
-          return [].freeze if owners.empty?
-
-          records = virtual_rbs.flat_map do |name, content|
-            next [] if content.nil? || content.empty? || invalid_encoding?(content.to_s)
-
-            decls = parse_signature_source(name, content.to_s)
-            decls.nil? ? [] : member_standdowns_in(name, decls, owners)
+        def index_signature_members(index, file, decls)
+          return if decls.nil?
+
+          each_declared_member(decls) do |class_name, member, visibility|
+            member_method_keys(member).each do |method_name, kind|
+              index[[class_name, method_name, kind]] ||= [file, member, visibility].freeze
+            end
           end
-          records.uniq.sort_by { |record| [record[0], record[1].to_s, record[2].to_s] }.freeze
         end
 
-        def member_standdowns_in(virtual_name, decls, owners)
-          records = []
-          each_declared_member(decls) do |class_name, member|
-            member_method_keys(member).each do |method_name, kind|
-              signature_path = owners[[class_name, method_name, kind]]
-              next if signature_path.nil?
+        # The directive heads a refinement {MemberConsistency.refinement_conflicts} checks, used to skip
+        # parsing an inline source that carries none when no `.rbs` overlaps it. Narrower than `rigor:v1:` on
+        # purpose: rbs-inline's output marks every skeleton `%a{rigor:v1:inferred-return}`, so that prefix is
+        # in nearly every synthesized source.
+        REFINEMENT_DIRECTIVE_MARKS = ["rigor:v1:return:", "rigor:v1:param:"].freeze
+        private_constant :REFINEMENT_DIRECTIVE_MARKS
 
-              records << [class_name, method_name, kind, signature_path, virtual_name.to_s].freeze
+        # `[[virtual_name, class_name, member], ...]` for the inline members {MemberConsistency.resolve}
+        # reads: every member when a `.rbs` file may overlap them (`all:`), otherwise only the members of a
+        # source that carries a `rigor:v1:return:` / `rigor:v1:param:` refinement, which is checked against
+        # its own declared type. Entries {.add_virtual_rbs} would skip are skipped here too.
+        def inline_member_entries(virtual_rbs, all:)
+          virtual_rbs.each_with_object([]) do |(name, content), entries|
+            content = content.to_s
+            next if content.empty? || invalid_encoding?(content)
+            next unless all || REFINEMENT_DIRECTIVE_MARKS.any? { |mark| content.include?(mark) }
+
+            decls = parse_signature_source(name, content)
+            next if decls.nil?
+
+            each_declared_member(decls) do |class_name, member, visibility|
+              entries << [name.to_s, class_name, member, visibility]
             end
           end
-          records
         end
 
-        # Removes, in place, every member `owners` says a project signature already declares. Nested
-        # declarations are descended into after the rejection, and a declaration member contributes no method
-        # key, so nesting is never itself removed.
-        def strip_members_declared_in_signatures!(decls, owners, prefix = [])
+        # Removes, in place, every member contributing a key in `keys` (a Set of `[class, method, kind]`).
+        # Nested declarations are descended into after the rejection, and a declaration member contributes no
+        # method key, so nesting is never itself removed.
+        def strip_members!(decls, keys, prefix = [])
           Array(decls).each do |decl|
             next unless declaration_with_members?(decl)
 
             inner = prefix + [decl.name.to_s.delete_prefix("::")]
             class_name = inner.join("::")
             decl.members.reject! do |member|
-              member_method_keys(member).any? { |method_name, kind| owners.key?([class_name, method_name, kind]) }
+              member_method_keys(member).any? { |method_name, kind| keys.include?([class_name, method_name, kind]) }
             end
-            strip_members_declared_in_signatures!(decl.members, owners, inner)
+            strip_members!(decl.members, keys, inner)
           end
         end
 
-        # Yields `[class_name, member]` for every member of every class / module declaration in `decls`,
-        # descending through nesting. The enclosing path is accumulated and the name rendered `::`-stripped,
-        # so a `module Foo; class Bar` and a `class Foo::Bar` elsewhere key the same — which is what makes a
-        # `sig/` declaration and an inline one comparable at all.
+        # Yields `[class_name, member, visibility]` for every member of every class / module declaration in
+        # `decls`, descending through nesting. The enclosing path is accumulated and the name rendered
+        # `::`-stripped, so a `module Foo; class Bar` and a `class Foo::Bar` elsewhere key the same — which is
+        # what makes a `sig/` declaration and an inline one comparable at all. `visibility` is the member's
+        # own (`private def x`) or else the one the enclosing `private` / `public` section sets; a singleton
+        # method takes no section, as in Ruby.
         def each_declared_member(decls, prefix = [], &block)
           Array(decls).each do |decl|
             next unless declaration_with_members?(decl)
 
             inner = prefix + [decl.name.to_s.delete_prefix("::")]
             class_name = inner.join("::")
-            decl.members.each { |member| block.call(class_name, member) }
+            section = :public
+            decl.members.each do |member|
+              case member
+              when ::RBS::AST::Members::Private then section = :private
+              when ::RBS::AST::Members::Public then section = :public
+              else block.call(class_name, member, member_visibility(member, section))
+              end
+            end
             each_declared_member(decl.members, inner, &block)
           end
         end
 
+        def member_visibility(member, section)
+          own = member.respond_to?(:visibility) ? member.visibility : nil
+          return own if own
+
+          member.respond_to?(:kind) && member.kind == :singleton ? :public : section
+        end
+
         def declaration_with_members?(decl)
           (decl.is_a?(::RBS::AST::Declarations::Module) || decl.is_a?(::RBS::AST::Declarations::Class)) &&
             decl.respond_to?(:members)
         end
 
-        # The `[method_name, kind]` pairs one RBS member contributes to a definition build, mirroring
-        # `RBS::DefinitionBuilder::MethodBuilder#build_instance` / `#build_singleton` — which is what decides
-        # whether two members collide. An attribute contributes its reader and / or writer name (`foo`,
-        # `foo=`), an alias its new name, and `def self?.x` both sides. An `overloading?` member (`def x: ...
-        # | ...`) contributes NOTHING: rbs files those under `overloads` rather than `originals`, so they are
-        # designed to compose with an existing declaration and must not stand down against it.
+        # {MemberConsistency.member_method_keys} — the `[method_name, kind]` pairs a member contributes to a
+        # definition build, which is what decides whether two members collide.
         def member_method_keys(member)
-          case member
-          when ::RBS::AST::Members::MethodDefinition then method_definition_keys(member)
-          when ::RBS::AST::Members::AttrReader then [[member.name, member.kind]]
-          when ::RBS::AST::Members::AttrWriter then [[:"#{member.name}=", member.kind]]
-          when ::RBS::AST::Members::AttrAccessor then [[member.name, member.kind], [:"#{member.name}=", member.kind]]
-          when ::RBS::AST::Members::Alias then [[member.new_name, member.kind]]
-          else []
-          end
+          MemberConsistency.member_method_keys(member)
         end
 
-        def method_definition_keys(member)
-          return [] if member.respond_to?(:overloading?) && member.overloading?
-
-          case member.kind
-          when :instance then [[member.name, :instance]]
-          when :singleton then [[member.name, :singleton]]
-          else [[member.name, :instance], [member.name, :singleton]] # `def self?.x` defines both sides
-          end
-        end
-
-        # A class / module declaration header, as the pre-filter in {.signature_member_owners} reads it out of
+        # A class / module declaration header, as the pre-filter in {.signature_member_index} reads it out of
         # synthesized RBS text.
         INLINE_DECLARATION_NAME = /^[ \t]*(?:class|module)[ \t]+([A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)/
         private_constant :INLINE_DECLARATION_NAME
@@ -1016,18 +1105,20 @@ module Rigor
             content = content.to_s
             next if content.empty? || invalid_encoding?(content)
 
-            content.scan(INLINE_DECLARATION_NAME) { |(declared)| acc.merge(declared.split("::")) }
+            merge_declared_segments(content, acc)
           end
         end
 
-        # Parses one project signature file, or nil when it is unreadable, not valid UTF-8, unparseable, or
-        # mentions none of `names` (so nothing in it can collide with the inline sources).
-        def parse_signature_file_if_mentions(file, names)
-          content = File.read(file, encoding: "UTF-8")
-          return nil if invalid_encoding?(content)
-          return nil if names.none? { |name| content.include?(name) }
+        # Adds every `::` segment of every class / module header in `content` to `segments`. The pattern has
+        # one capture group, which every match fills.
+        def merge_declared_segments(content, segments)
+          content.scan(INLINE_DECLARATION_NAME) { segments.merge(Regexp.last_match(1).to_s.split("::")) }
+        end
 
-          parse_signature_source(file, content)
+        # One project signature file's text, or nil when it is unreadable or not valid UTF-8.
+        def read_signature_text(file)
+          content = File.read(file, encoding: "UTF-8")
+          invalid_encoding?(content) ? nil : content
         rescue Errno::ENOENT, Errno::EISDIR, Errno::EACCES
           nil
         end
@@ -1056,9 +1147,10 @@ module Rigor
         private_constant :VENDORED_GEM_SIGS_ROOT
 
         # Rigor-owned core-overlay RBS (`data/core_overlay/`). Reopens Ruby core classes to add methods
-        # upstream `ruby/rbs` omits but which every concrete value answers at runtime — loaded last so
-        # upstream always wins on conflict. Public so the cache descriptor can digest these files into the
-        # env-blob key.
+        # upstream `ruby/rbs` omits but which every concrete value answers at runtime. A direct `def` that
+        # another source also declares is a `DuplicatedMethodDefinitionError`, not a precedence question, so a
+        # method a project `sig/` or a later rbs is likely to declare goes on a module the class extends
+        # (`process.rbs`). Public so the cache descriptor can digest these files into the env-blob key.
         CORE_OVERLAY_SIGS_ROOT = File.expand_path(
           "../../../data/core_overlay",
           __dir__
@@ -1128,6 +1220,10 @@ module Rigor
         # `core_overlay/pathname.rbs` also carries an `| ...` continuation but is deliberately NOT listed:
         # its base (`Pathname#expand_path`) lives in rbs's `core/pathname.rbs` on every supported rbs
         # release (3.10 / 4.0 / 4.1), so the continuation is safe — and applicable — with no library loaded.
+        # `core_overlay/string_io.rbs` re-opens a class the `stringio` library declares yet is NOT listed
+        # either: `RBS::EnvironmentLoader#load` adds that library itself whenever it loads core (rbs 3.7+),
+        # and earlier releases declare `StringIO` in core, so gating would only drop its `Enumerable` mixin
+        # where `StringIO` is present anyway.
         #
         # Keyed by `data/vendored_gem_sigs/` directory basename.
         LIBRARY_SUPPLEMENT_VENDORED_DIRS = {
@@ -1144,12 +1240,23 @@ module Rigor
         }.freeze
         private_constant :LIBRARY_SUPPLEMENT_CORE_OVERLAYS
 
+        # `data/core_overlay/` files that fill a hole only one `rbs` release line has, keyed by file basename
+        # to the `rbs` version requirement they load under. Each carries an `| ...` continuation of overloads a
+        # later line declares upstream, so loading it there would add a second copy of them. The env-cache key
+        # already carries `RBS::VERSION` ({Cache::RbsDescriptor.rbs_gem_entry}), so switching lines re-keys.
+        # The requirement is a String, not a `Gem::Requirement`, so the constant stays `Ractor.shareable?`.
+        RBS_LINE_CORE_OVERLAYS = {
+          "hash_rbs3.rbs" => "< 4.0"
+        }.freeze
+        private_constant :RBS_LINE_CORE_OVERLAYS
+
         # Adds the Rigor-shipped signature sources to `rbs_loader`: every `data/vendored_gem_sigs/<gem>/`
-        # directory, then the `data/core_overlay/` files — the overlay LAST so an upstream declaration
-        # always wins on conflict (these reopenings only fill genuine holes, e.g. `Numeric#to_f`/`to_i`/
-        # `to_r`, which upstream RBS declares on the concrete subclasses but not on the abstract `Numeric`
-        # that Rigor's arithmetic-chain widening produces). The overlay is added per-file, not
-        # per-directory, because the `LIBRARY_SUPPLEMENT_CORE_OVERLAYS` files must be gated individually.
+        # directory, then the `data/core_overlay/` files, which fill genuine holes only (e.g. `Numeric#to_f`/
+        # `to_i`/`to_r`, which upstream RBS declares on the concrete subclasses but not on the abstract `Numeric`
+        # that Rigor's arithmetic-chain widening produces). Load order does not settle a conflict: a method
+        # both sides declare directly raises `DuplicatedMethodDefinitionError` for the whole class. The
+        # overlay is added per-file, not per-directory, because the `LIBRARY_SUPPLEMENT_CORE_OVERLAYS` and
+        # `RBS_LINE_CORE_OVERLAYS` files must be gated individually.
         #
         # @param loaded_library_names — libraries that actually resolved on this loader.
         def add_bundled_signatures(rbs_loader, loaded_library_names)
@@ -1165,6 +1272,7 @@ module Rigor
             dir.children.sort.each do |file|
               next unless file.file? && file.extname == ".rbs"
               next unless supplement_dependency_loaded?(LIBRARY_SUPPLEMENT_CORE_OVERLAYS, file, loaded_library_names)
+              next unless rbs_line_matches?(file)
 
               rbs_loader.add(path: file)
             end
@@ -1180,6 +1288,13 @@ module Rigor
           library.nil? || loaded_library_names.include?(library)
         end
 
+        # @param path — a `data/core_overlay/` file.
+        # @return true when `path` is not tied to an `rbs` release line, or the running `rbs` is on its line.
+        def rbs_line_matches?(path)
+          requirement = RBS_LINE_CORE_OVERLAYS[path.basename.to_s]
+          requirement.nil? || Gem::Requirement.new(requirement).satisfied_by?(Gem::Version.new(::RBS::VERSION))
+        end
+
         # Rigor-owned per-gem RBS overlays (`data/gem_overlay/<gem>/`), ADR-72. Unlike the unconditional
         # `core_overlay`, each gem's overlay is loaded ONLY when that gem is locked in the project's
         # Gemfile.lock but ships no RBS of its own — {Environment.for_project} decides eligibility and passes
@@ -1362,7 +1477,7 @@ module Rigor
         # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:definition_build_warned`,
         # `:definition_build_details`, `:definition_build_reported`, `:definition_build_failures`,
         # `:definition_build_deferred_count`, `:definition_build_deferred_first`,
-        # `:definition_build_summary_warned`, `:inline_member_standdowns`, `:internal_demand`,
+        # `:definition_build_summary_warned`, `:member_consistency`, `:member_consistency_proven`, `:internal_demand`,
         # `:internal_demand_status`, `:builder`, `:reflection`,
         # `:instance_definitions_table`, `:singleton_definitions_table`.
         # Constructed via `Hash.new` (NOT a `{ ... }` literal) so Rigor's `HashShape` narrowing doesn't
@@ -1457,11 +1572,94 @@ module Rigor
       end
       private :build_project_declared_classes
 
+      # Issue #527 — the class / module names whose PRIMARY declaration lives in the `rbs` gem's own
+      # `core/` or `stdlib/` tree, top-level prefix stripped.
+      #
+      # The distinction it draws is narrower than {#project_declared_classes}'s: not "who wrote this
+      # signature" but "is this Ruby's own documented surface". A core / stdlib signature is the method
+      # set every negative check rule already trusts for a direct receiver of the class, which is what
+      # lets a Ruby-source SUBCLASS of one resolve its inherited calls there (`RbsDispatch`'s
+      # `core_stdlib_ancestor_method`). A GEM's RBS is a different claim — routinely partial, which is
+      # ADR-43's whole reason for declining blanket inherited resolution — so it is deliberately outside
+      # this set even when the gem ships signatures and even when it is one of {DEFAULT_LIBRARIES}
+      # (`prism`, `rbs` are gems whose signatures ship with the gem, not entries of rbs's `stdlib/`).
+      #
+      # Attribution is by buffer NAME, the same mechanism and the same limits as
+      # {#project_declared_classes}: it survives the ADR-54 environment cache, and an old blob's
+      # `<cached>` sentinel lands every class OUTSIDE the set — the feature switches off rather than
+      # widening, which is the direction ADR-5 wants. Memoised per loader; one pass over `class_decls`.
+      def core_stdlib_classes
+        @state[:core_stdlib_classes] ||= build_core_stdlib_classes
+      end
+
+      def build_core_stdlib_classes
+        environment = env
+        return Set.new.freeze if environment.nil? || CORE_STDLIB_ROOTS.empty?
+
+        names = environment.class_decls.each_with_object(Set.new) do |(rbs_name, entry), acc|
+          decl = self.class.primary_decl_for(entry)
+          next if decl.nil?
+
+          path = self.class.declaration_buffer_name(decl)
+          next if path.nil?
+
+          acc << rbs_name.to_s.delete_prefix("::") if CORE_STDLIB_ROOTS.any? { |root| path.start_with?(root) }
+        end
+        names.freeze
+      rescue ::RBS::BaseError
+        Set.new.freeze
+      end
+      private :build_core_stdlib_classes
+
+      # True when `class_name` is declared by Ruby core or a stdlib library (see {#core_stdlib_classes}).
+      def core_or_stdlib_class?(class_name)
+        core_stdlib_classes.include?(class_name.to_s.delete_prefix("::"))
+      end
+
       # True when `class_name`'s RBS declaration is one the project wrote (see {#project_declared_classes}).
       def project_declared_class?(class_name)
         project_declared_classes.include?(class_name.to_s.delete_prefix("::"))
       end
 
+      # Issue #1362 — the translated type of the RBS declaration of the global variable `name` (`:$stdout`, declared
+      # `IO` by the core signatures), or nil when no loaded signature declares it. Translated without an alias
+      # expander, as {#constant_type} translates a constant, so `$DEBUG: boolish` reads `Dynamic[top]` rather than
+      # `top`.
+      def global_type(name)
+        global_declarations[name.to_sym]&.first
+      end
+
+      # True when `name`'s RBS declaration lives in the `rbs` gem's own `core/` or `stdlib/` tree: a global the
+      # interpreter or a default library sets. Attributed by buffer name, as {#core_or_stdlib_class?} is, with the
+      # same limit: an environment blob without buffer names answers false for every global.
+      def core_or_stdlib_global?(name)
+        global_declarations[name.to_sym]&.last || false
+      end
+
+      # `name => [type, core_or_stdlib]` for every global the environment declares; a declaration whose type
+      # translates to `bot` is left out. Memoised per loader: the core signatures declare about fifty.
+      def global_declarations
+        @state[:global_declarations] ||= build_global_declarations
+      end
+      private :global_declarations
+
+      def build_global_declarations
+        environment = env
+        return {}.freeze if environment.nil?
+
+        table = environment.global_decls.each_with_object({}) do |(name, entry), acc|
+          type = Inference::RbsTypeTranslator.translate(entry.decl.type)
+          next if type.is_a?(Type::Bot)
+
+          path = self.class.declaration_buffer_name(entry.decl)
+          acc[name.to_sym] = [type, !path.nil? && CORE_STDLIB_ROOTS.any? { |root| path.start_with?(root) }].freeze
+        end
+        table.freeze
+      rescue ::RBS::BaseError
+        {}.freeze
+      end
+      private :build_global_declarations
+
       # The total RBS-environment build failure captured this run, or nil when the env built. Unlike
       # {#quarantined_signatures} — which the env survives, one file lighter, and which is re-derived so a
       # cache HIT reports it too — a total failure collapses the WHOLE env to nil. Project-vs-bundled
@@ -1495,9 +1693,10 @@ module Rigor
       # definition-build failure leaves no trace in the env at all — the env is fine; it is the BUILD over it
       # that raised — so the rescue is the only place that ever knows.
       #
-      # @return `[class_name, error_class_name,
-      #   first_error_line, conflicting_buffer_names]`, one per class, in first-failure order. Empty for a
-      #   healthy sig set, which is the common case.
+      # @return `[class_name, error_class_name, member, conflicting_buffer_names,
+      #   unresolved_type_name_detail]`, one per class, in first-failure order (issue #997 added the fifth
+      #   slot; see {#unresolved_type_name_detail} — `nil` there for every failure kind but an unresolvable
+      #   type name). Empty for a healthy sig set, which is the common case.
       def definition_build_failures
         (@state[:definition_build_failures] || []).dup.freeze
       end
@@ -1524,10 +1723,11 @@ module Rigor
         end
       end
 
-      # Issue #824 / ADR-32 WD13 — the inline (rbs-inline) members that stood down because the project's own
-      # `signature_paths:` already declare the same `(class, method, kind)`. The `.rbs` wins per member; the
-      # rest of the file's annotations still bind, and the class keeps its method surface instead of failing
-      # its definition build.
+      # Issue #1075 / ADR-112 WD5 — one {MemberConsistency::Record} per `(class, method, kind)` the project's
+      # own `signature_paths:` and an inline (rbs-inline) source both declare, saying which side bound and
+      # why, plus one per `rigor:v1:return:` / `rigor:v1:param:` refinement that exceeds its member's own
+      # declared type. The rest of the file's annotations still bind either way, and the class keeps its
+      # method surface instead of failing its definition build.
       #
       # The sibling of {#virtual_rbs_collision_quarantined} one granularity finer: that one names a whole
       # inline FILE dropped for a class-level duplicate, this one names a single member. Both are derived
@@ -1535,12 +1735,15 @@ module Rigor
       # derivation reads the loader's inputs rather than the built env, because a stripped member leaves no
       # trace in the env at all.
       #
-      # @return `[class_name, method_name, kind, signature_path,
-      #   virtual_buffer_name]` records, sorted. Empty (and free) whenever the project contributes no inline
-      #   RBS or none of it overlaps a signature file.
-      def inline_member_standdowns
-        @state[:inline_member_standdowns] ||=
-          self.class.inline_member_standdowns_for(signature_paths: @signature_paths, virtual_rbs: @virtual_rbs)
+      # @return the records, sorted. Empty (and free) whenever the project contributes no inline RBS.
+      #
+      # @param proof — a {MemberConsistency::RbsProof} over this loader, without which no pair is reported
+      #   as a contradiction (only the severity of a row depends on it, never which declaration binds).
+      def member_consistency(proof: nil)
+        key = proof ? :member_consistency_proven : :member_consistency
+        @state[key] ||= self.class.member_consistency_for(
+          self.class.project_sig_files(@signature_paths), @virtual_rbs, proof: proof
+        ).records
       end
 
       # The referenced-but-undeclared types {.stub_missing_referenced_types} stubbed so the project classes
@@ -2025,11 +2228,21 @@ module Rigor
       # Building it digests every `.rbs` file under `signature_paths` + the vendored gem sigs, and the
       # result is identical across producers, so one build is memoised per loader (on `@state`, alongside
       # `:env` — the env itself is loader-lifetime-memoised, so this adds no new staleness class).
+      #
+      # Issue #1014 — nil when the engine's source cannot be digested ({Cache::EngineSource::Unavailable});
+      # {Cache::RbsCacheProducer.fetch} then computes uncached. Memoised through `key?` rather than `||=` so
+      # that answer is reached once: rebuilding it would re-digest the whole signature tree per producer to
+      # arrive at the same nil.
       def rbs_cache_descriptor
-        @state[:rbs_cache_descriptor] ||= begin
-          require_relative "../cache/rbs_descriptor"
-          Cache::RbsDescriptor.build(self)
-        end
+        return @state[:rbs_cache_descriptor] if @state.key?(:rbs_cache_descriptor)
+
+        require_relative "../cache/rbs_descriptor"
+        @state[:rbs_cache_descriptor] =
+          begin
+            Cache::RbsDescriptor.build(self)
+          rescue Cache::EngineSource::Unavailable
+            nil
+          end
       end
 
       # ADR-15 Phase 2b — return the loader's read-only query surface as a frozen, `Ractor.shareable?`
@@ -2397,7 +2610,60 @@ module Rigor
         return if details.key?(key)
 
         details[key] = [key, error.class.name.to_s, definition_build_member(error),
-                        definition_build_conflict_buffers(error)].freeze
+                        definition_build_conflict_buffers(error), unresolved_type_name_detail(error)].freeze
+      end
+
+      # Issue #997 — the `RBS::NoTypeFoundError` twin of {#definition_build_member}: `nil` for every other
+      # error class, so the cached tuple gains a populated fifth slot only for the failure kind it
+      # distinguishes — "one declaration names a type that does not exist" from "two declarations collide"
+      # ({DiagnosticAggregator#definition_build_advice}, which folds this in).
+      #
+      # Computed once, at RAISE time, and frozen into the cached detail rather than re-derived when a warm
+      # run replays the tuple from {IncrementalSnapshot} — there is no live `RBS::NoTypeFoundError` to
+      # re-inspect on that path, only the plain strings this method already reduced it to.
+      #
+      # `[token, location, refinement_hint]`:
+      # - `token` is the unresolved name exactly as `RBS::NoTypeFoundError#type_name` carries it — the ONLY
+      #   name that ever reaches RBS. A hyphenated payload (`finite-float`) is truncated to its first
+      #   segment by rbs-inline's own tolerant type parse (`RBS::Parser.parse_type(..., require_eof: false)`
+      #   stops at the first complete type and silently discards the rest), so `-float` never becomes a
+      #   token RBS itself can name or complain about.
+      # - `location` is `error.location.to_s` verbatim (`"virtual:rbs-inline:<path>:line:col...line:col"`)
+      #   — the position the error already carries, per issue #997, named rather than re-derived. It is a
+      #   position in the SYNTHESIZED buffer for an inline annotation, not necessarily the `.rb` line the
+      #   author wrote: {Effects::InlineAnchor} maps a known `%a{...}` spelling back by ordinal, which does
+      #   not apply to an arbitrary broken type token, so no such mapping is attempted here.
+      # - `refinement_hint` is the full compound name (`"finite-float"`) when the SAME synthesized buffer —
+      #   rbs-inline re-emits the author's original `# @rbs name: TYPE` comment verbatim above the member it
+      #   generates — carries `token` immediately followed by a hyphenated continuation that is ITSELF a
+      #   registered {Builtins::ImportedRefinements} name; `nil` otherwise. Exact-match only: a near-miss
+      #   compound name says nothing, so a coincidental `token-suffix` that is not a real refinement can
+      #   never manufacture a misleading "did you mean" (false positives outrank worst-case reading).
+      def unresolved_type_name_detail(error)
+        return nil unless error.is_a?(::RBS::NoTypeFoundError)
+
+        token = error.type_name.to_s.delete_prefix("::")
+        [token, error.location&.to_s, refinement_hint_for(token, error)].freeze
+      rescue ::RBS::BaseError, StandardError
+        nil
+      end
+
+      # The buffer rbs-inline synthesized still carries the author's own comment line verbatim (the
+      # "annotation echo" {Effects::InlineAnchor} documents), so a hyphenated refinement name truncated out
+      # of the parsed type ({#unresolved_type_name_detail}) is still readable a few characters further along
+      # the SAME text the error's own location already points into.
+      def refinement_hint_for(token, error)
+        return nil if token.empty?
+
+        content = error.location&.buffer&.content
+        return nil if content.nil?
+
+        candidate = content[/\b#{Regexp.escape(token)}-[A-Za-z0-9][\w-]*/]
+        return nil if candidate.nil?
+
+        Builtins::ImportedRefinements.known?(candidate) ? candidate : nil
+      rescue ::RBS::BaseError, StandardError
+        nil
       end
 
       # Issue #696 — the REPORTING half: promote a remembered detail into {#definition_build_failures}