rigortype 0.3.1 → 0.3.2

data/lib/rigor/environment/rbs_loader.rb

@@ -65,9 +65,11 @@ module Rigor
         # intentionally read-only and appended LAST so user-supplied `signature_paths` win on name conflicts.
         def build_env_for(libraries:, signature_paths:, virtual_rbs: [])
           rbs_loader = RBS::EnvironmentLoader.new
-          libraries.each do |library|
-            next unless rbs_loader.has_library?(library: library, version: nil)
-
+          libraries = libraries_without_shadowed_bigdecimal_math(libraries)
+          loaded_libraries = libraries.select do |library|
+            rbs_loader.has_library?(library: library, version: nil)
+          end
+          loaded_libraries.each do |library|
             rbs_loader.add(library: library, version: nil)
           end
           # Project `signature_paths:` are loaded per-file by {.add_project_signatures} AFTER `from_loader`,
@@ -76,16 +78,7 @@ module Rigor
           # type-of query then degrades to `Dynamic[top]` — the "sig looks harmful" failure of the 2026-07-06
           # 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.
-          vendored_gem_sig_paths.each do |path|
-            rbs_loader.add(path: path) if path.directory?
-          end
-          # Rigor-owned core overlay — loaded 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).
-          core_overlay_sig_paths.each do |path|
-            rbs_loader.add(path: path) if path.directory?
-          end
+          add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s))
           env = RBS::Environment.from_loader(rbs_loader)
           add_project_signatures(env, signature_paths)
           add_virtual_rbs(env, virtual_rbs)
@@ -94,10 +87,66 @@ module Rigor
           stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
         end
 
+        # rbs ships `stdlib/bigdecimal/` and `stdlib/bigdecimal-math/` as two libraries, so
+        # `Environment::DEFAULT_LIBRARIES` names both. But `RBS::EnvironmentLoader` resolves a library to an
+        # INSTALLED GEM's `sig/` in preference to rbs's own `stdlib/` copy, and the `bigdecimal` gem has
+        # shipped `sig/big_math.rbs` — declaring the very same `BigMath` module — since 4.0. On such a host
+        # both declarations land in one environment, `RBS::DefinitionBuilder` raises
+        # `DuplicatedMethodDefinitionError` on `BigMath.E`, and the WHOLE module silently degrades to
+        # `Dynamic[top]` (issue #299) — every `BigMath` call, real method and typo alike, stops being
+        # witnessed.
+        #
+        # `bigdecimal-math` is the entry to drop, not `bigdecimal`: the gem's copy is maintained alongside
+        # the implementation, types `log10` / `log1p` / `expm1` / `tan` / `tanh` (which rbs's copy omits
+        # outright), and accepts `real | BigDecimal` where rbs's accepts only `BigDecimal`. Dropping it is
+        # therefore a strict typing gain, not a trade.
+        #
+        # Host-dependent by construction, and deliberately so: where `bigdecimal` resolves to rbs's own
+        # `stdlib/bigdecimal/` (an older gem with no `sig/`, or no gem at all), nothing collides, nothing is
+        # dropped, and `bigdecimal-math` still supplies `BigMath`.
+        BIGDECIMAL_LIBRARY = "bigdecimal"
+        private_constant :BIGDECIMAL_LIBRARY
+        BIGDECIMAL_MATH_LIBRARY = "bigdecimal-math"
+        private_constant :BIGDECIMAL_MATH_LIBRARY
+        # The one basename that decides it: `BigMath` lives in `big_math.rbs` on both sides.
+        BIG_MATH_SIG_BASENAME = "big_math.rbs"
+        private_constant :BIG_MATH_SIG_BASENAME
+
+        # @param libraries [Array<String>] the resolved library list, `DEFAULT_LIBRARIES` included.
+        # @return [Array<String>] the same list, minus `bigdecimal-math` when `bigdecimal` already brings
+        #   `BigMath` in.
+        def libraries_without_shadowed_bigdecimal_math(libraries)
+          return libraries unless libraries.include?(BIGDECIMAL_LIBRARY) && libraries.include?(BIGDECIMAL_MATH_LIBRARY)
+          return libraries unless bigdecimal_library_declares_big_math?
+
+          libraries - [BIGDECIMAL_MATH_LIBRARY]
+        end
+
+        # Resolves `library: "bigdecimal"` on a THROWAWAY loader (never the one building the env) and reports
+        # whether any directory it resolves to ships `big_math.rbs`. Fails soft to `false`: an unresolvable
+        # library must not take the whole environment build down, and keeping both entries is the
+        # pre-existing behaviour.
+        def bigdecimal_library_declares_big_math?
+          probe = ::RBS::EnvironmentLoader.new(core_root: nil)
+          return false unless probe.has_library?(library: BIGDECIMAL_LIBRARY, version: nil)
+
+          probe.add(library: BIGDECIMAL_LIBRARY, version: nil)
+          shadowed = false
+          probe.each_dir { |_source, dir| shadowed ||= dir.join(BIG_MATH_SIG_BASENAME).file? }
+          shadowed
+        rescue StandardError
+          false
+        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).
         def parseable_rbs?(content)
+          # Pre-parser encoding guard ({.invalid_encoding?}): invalid UTF-8 raises `ArgumentError` (not
+          # `ParsingError`) out of `RBS::Parser.magic_comment`'s regex on rbs 4.1, escaping the rescue below,
+          # and could hang the C lexer outright on the older releases the gemspec supports.
+          return false if invalid_encoding?(content)
+
           ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: "(rigor: virtual parse check)", content: content))
           true
         rescue ::RBS::BaseError
@@ -148,21 +197,29 @@ module Rigor
         # calls to `Dynamic[Top]` instead (the same no-false-positive contract as the dependency-source
         # tier).
         #
-        # Detection re-uses RBS's own builder (correct by construction): build every PROJECT class and read
-        # the missing name out of the raised error. Bounded to `signature_paths` classes (stdlib / vendored
-        # RBS is well-formed) and to {MAX_STUB_PASSES} iterations — a fresh stub can expose a deeper
-        # reference the first build error hid, but empty stubs reference nothing, so the fixpoint converges
-        # quickly.
+        # Detection reads the PROJECT declarations and mirrors rbs's own membership test
+        # ({.unresolved_referenced_types}); it is bounded to `signature_paths` classes (stdlib / vendored RBS
+        # is well-formed) and to {MAX_STUB_PASSES} iterations — a fresh stub can expose a deeper reference the
+        # first pass could not see past, but empty stubs reference nothing, so the fixpoint converges quickly.
         MAX_STUB_PASSES = 5
 
         def stub_missing_referenced_types(base_env, resolved, project_files)
           return resolved if project_files.empty?
 
+          previous = nil
           MAX_STUB_PASSES.times do
             missing = unresolved_referenced_types(resolved, project_files)
             break if missing.empty?
 
-            append_stub_declarations(base_env, missing)
+            # Bound the fixpoint by PROGRESS, not by the cap alone. A pass that appends no declaration, or
+            # that re-detects the set it already saw, cannot converge — and before this guard the cap was the
+            # only stop, so the pathological input paid the full detection sweep five times over (measured on
+            # herb: five passes, nothing synthesized). The cap stays as the backstop for a genuinely deepening
+            # chain of references.
+            current = missing.to_set
+            break if current == previous || !append_stub_declarations(base_env, missing)
+
+            previous = current
             resolved = base_env.resolve_type_names
           end
           resolved
@@ -240,25 +297,48 @@ module Rigor
           end
         end
 
+        # The quarantine note for a file rejected by {.invalid_encoding?} — worded to be distinct from any
+        # rbs-emitted parse error so specs (and users) can tell Rigor's pre-parser skip from the parser's own
+        # UTF-8 diagnostics.
+        INVALID_ENCODING_NOTE = "not valid UTF-8 — skipped before reaching the RBS parser"
+
+        # Pre-parser guard for content Rigor hands to `RBS::Parser`. On rbs 4.1+ an invalid UTF-8 byte is a
+        # clean `ParsingError` (ruby/rbs#2983), but on the older releases the gemspec supports (`>= 3.0,
+        # < 5.0`) the C lexer could infinite-loop or abort on it (fixed upstream in ruby/rbs#2973) — a hang no
+        # `rescue` can catch, and the one failure mode the quarantine's fail-soft rescues cannot absorb. So
+        # the check runs before the parser on every rbs version: uniform behaviour, and the quarantine note
+        # stays actionable ("fix the file's encoding") rather than version-dependent.
+        def invalid_encoding?(content)
+          !content.valid_encoding?
+        end
+
         # Parse one project `.rbs` into `[buffer, directives, decls]`, or nil when it is unparseable /
-        # unreadable. Mirrors `RBS::EnvironmentLoader#each_signature`'s per-file parse so the decls register
-        # identically to the loader's batch path.
+        # unreadable / not valid UTF-8. Mirrors `RBS::EnvironmentLoader#each_signature`'s per-file parse so
+        # the decls register identically to the loader's batch path.
         def parse_signature_file(file)
-          buffer = ::RBS::Buffer.new(name: file, content: File.read(file, encoding: "UTF-8"))
+          content = File.read(file, encoding: "UTF-8")
+          return nil if invalid_encoding?(content)
+
+          buffer = ::RBS::Buffer.new(name: file, content: content)
           _buffer, directives, decls = ::RBS::Parser.parse_signature(buffer)
           [buffer, directives, decls]
         rescue ::RBS::ParsingError, Errno::ENOENT, Errno::EISDIR, Errno::EACCES
           nil
         end
 
-        # The project `signature_paths:` files that FAIL to parse, as `[absolute_path, first_error_line]` pairs
-        # (sorted, deterministic). Detection is independent of {.add_project_signatures} so the warning fires
-        # even on a cache hit (where the env was already built with the file quarantined). Cheap: it only
-        # re-parses the user's own (usually small) `sig/` set, and returns empty immediately when there is no
-        # `signature_paths:`.
+        # The project `signature_paths:` files that FAIL to parse (or are not valid UTF-8), as
+        # `[absolute_path, first_error_line]` pairs (sorted, deterministic). Detection is independent of
+        # {.add_project_signatures} so the warning fires even on a cache hit (where the env was already built
+        # with the file quarantined). Cheap: it only re-parses the user's own (usually small) `sig/` set, and
+        # returns empty immediately when there is no `signature_paths:`.
         def quarantined_project_signatures(signature_paths)
           project_sig_files(signature_paths).sort.filter_map do |file|
-            buffer = ::RBS::Buffer.new(name: file, content: File.read(file, encoding: "UTF-8"))
+            # The note carries the path itself because the warn composer prints only this element — a
+            # `ParsingError` message embeds its `path:line:` prefix, so the composer never adds one.
+            content = File.read(file, encoding: "UTF-8")
+            next [file, "#{file}: #{INVALID_ENCODING_NOTE}"] if invalid_encoding?(content)
+
+            buffer = ::RBS::Buffer.new(name: file, content: content)
             ::RBS::Parser.parse_signature(buffer)
             nil
           rescue ::RBS::ParsingError => e
@@ -268,26 +348,122 @@ module Rigor
           end
         end
 
-        # Builds every project class (instance + singleton side) and returns the `::`-stripped names of the
-        # types whose absence raised `NoTypeFoundError`. Only the FIRST missing reference per class surfaces
-        # per build, which is why the caller loops.
+        # The `::`-stripped names of every type a PROJECT signature references that no loaded declaration
+        # provides — the input to {.append_stub_declarations}.
+        #
+        # Detection READS the declarations; it does not build them. Until #207 it built every project class
+        # instance- and singleton-side with a throwaway `RBS::DefinitionBuilder` and recovered the name from
+        # the raised `NoTypeFoundError` — correct by construction, and **7.84M allocations, a third of a cold
+        # `check lib`** on Rigor's own tree, to find nothing once `sig/` is self-consistent. The walk below
+        # costs ~21k.
+        #
+        # It mirrors rbs's raise sites, so the answer is the builder's:
+        #
+        # * `DefinitionBuilder#validate_type_presence` over the ARGS of a super class, a module `self` type,
+        #   and a mixin. The name itself is deliberately NOT checked: a missing super class or mixin raises
+        #   `NoSuperclassFoundError` / `NoMixinFoundError`, which this pass has never stubbed.
+        # * `VarianceCalculator#type` over every method type `validate_type_params` reaches, which raises for
+        #   `ClassInstance` / `Interface` / `Alias` only. It skips `initialize`, and it is not called for the
+        #   singleton side — so a name reachable only through `def initialize:` or `def self.x:` is not
+        #   reported here, exactly as the builder did not report it. Stubbing those names anyway cost
+        #   allocations on the corpus and changed no diagnostic.
+        #
+        # Membership is decided with the builder's own predicate ({.declared_reference?}), so a name reported
+        # here is one no declaration in the env provides. A resolvable name can never be reported, which is
+        # what keeps the stub safe: ADR-5 tier 2 trades precision for a fail-soft, and a stub for a name that
+        # WOULD have resolved would shadow a real type instead.
+        #
+        # One reduction in scope. The builder also walked each project class's ANCESTORS, so a dangling
+        # reference inside a *gem's* signature reachable from a project class was reported too; this walk
+        # reads project declarations only. No such name occurs across the eight RBS-shipping projects the
+        # change was measured on, and the cost of missing one is the fail-soft `Dynamic` ADR-5 tier 2 already
+        # accepts — not a false diagnostic. A project INTERFACE's own dangling reference is likewise not
+        # reported, and likewise was not by the builder (`validate_type_params` does not variance-walk the
+        # methods a class imports from an interface) — pinned by spec so the two stay together.
+        #
+        # Equivalence with the builder sweep is pinned by spec, which keeps the sweep as its oracle. Full
+        # evaluation: `docs/notes/20260730-stub-pass1-static-detection-evaluation.md`.
         def unresolved_referenced_types(env, project_files)
-          builder = ::RBS::DefinitionBuilder.new(env: env)
-          missing = []
-          env.class_decls.each do |type_name, entry|
+          missing = {}
+          checked = {}
+          env.class_decls.each_value do |entry|
             next unless project_entry?(entry, project_files)
 
-            %i[build_instance build_singleton].each do |build|
-              builder.public_send(build, type_name)
-            rescue ::RBS::NoTypeFoundError => e
-              name = e.message[/Could not find (\S+)/, 1]
-              missing << name.sub(/\A::/, "") if name
-            rescue ::RBS::BaseError
-              # Other build failures (duplicate decl, mixin cycle, ...) are not ours to repair here — leave
-              # them fail-soft.
+            entry_declarations(entry).each { |decl| collect_declaration_references(env, decl, missing, checked) }
+          end
+          missing.keys
+        end
+
+        # Decl-level references the builder validates: a super class's / module self type's / mixin's type
+        # ARGUMENTS, plus every member. `super_class` is a `Declarations::Class` accessor and `self_types` a
+        # `Declarations::Module` one, so both are reached behind a shape check.
+        def collect_declaration_references(env, decl, missing, checked)
+          if decl.respond_to?(:super_class)
+            decl.super_class&.args&.each { |arg| collect_type_references(env, arg, missing, checked) }
+          end
+          if decl.respond_to?(:self_types)
+            decl.self_types&.each do |self_type|
+              self_type.args.each { |arg| collect_type_references(env, arg, missing, checked) }
+            end
+          end
+          collect_member_references(env, decl.members, missing, checked)
+        end
+
+        # Member-level references. `initialize` and the singleton side are skipped because
+        # `validate_type_params` never reaches them (see {.unresolved_referenced_types}); `:singleton_instance`
+        # (`def self?.x`) defines the instance side too, so it is NOT skipped.
+        def collect_member_references(env, members, missing, checked)
+          members.each do |member|
+            next if member.respond_to?(:kind) && member.kind == :singleton
+
+            case member
+            when ::RBS::AST::Members::MethodDefinition
+              next if member.name == :initialize
+
+              member.overloads.each do |overload|
+                collect_type_references(env, overload.method_type, missing, checked)
+              end
+            when ::RBS::AST::Members::AttrReader, ::RBS::AST::Members::AttrWriter,
+                 ::RBS::AST::Members::AttrAccessor
+              collect_type_references(env, member.type, missing, checked)
+            when ::RBS::AST::Members::Include, ::RBS::AST::Members::Extend,
+                 ::RBS::AST::Members::Prepend
+              member.args.each { |arg| collect_type_references(env, arg, missing, checked) }
             end
           end
-          missing.uniq
+        end
+
+        # Walks one type (or method type) and appends the names no declaration provides. Only the three node
+        # classes `VarianceCalculator#type` raises for carry a checkable name; everything else is traversed for
+        # the types nested inside it.
+        def collect_type_references(env, type, missing, checked)
+          return if type.nil?
+
+          case type
+          when ::RBS::Types::ClassInstance, ::RBS::Types::Interface, ::RBS::Types::Alias
+            name = type.name
+            name = name.absolute! unless name.absolute?
+            missing[name.to_s.sub(/\A::/, "")] = true unless declared_reference?(env, name, checked)
+          end
+          return unless type.respond_to?(:each_type)
+
+          type.each_type do |nested|
+            collect_type_references(env, nested, missing, checked)
+          end
+        end
+
+        # `DefinitionBuilder#validate_type_name`'s membership test, memoised per env walk (a project's method
+        # signatures name the same handful of types over and over). A name whose normalization raises is
+        # treated as declared: repairing it is not this pass's job, and a wrong stub is the worse failure.
+        def declared_reference?(env, name, checked)
+          key = name.to_s
+          return checked[key] if checked.key?(key)
+
+          checked[key] = begin
+            env.type_name?(env.normalize_type_name(name))
+          rescue StandardError
+            true
+          end
         end
 
         # Normalises a `class_decls` entry's representative declaration across the gemspec's supported RBS
@@ -304,6 +480,24 @@ module Rigor
           end
         end
 
+        # Collects the AST declaration nodes behind a `class_decls` entry across the supported RBS range (`rbs
+        # >= 3.0, < 5.0`). RBS 4's `ModuleEntry` / `ClassEntry` expose `each_decl` yielding bare AST
+        # declarations; RBS 3.x exposes `decls`, an array of `MultiEntry::D` wrappers whose `#decl` is the AST
+        # declaration. The single-`decl` shape is handled defensively so the loader survives an rbs-gem minor
+        # bump. Class-side because both the env-build detection walk and the instance-side
+        # `#names_synthesized_in` need it, and the guard must stay single-rooted.
+        def entry_declarations(entry)
+          if entry.respond_to?(:each_decl)
+            [].tap { |acc| entry.each_decl { |decl| acc << decl } }
+          elsif entry.respond_to?(:decls)
+            entry.decls.map { |d| d.respond_to?(:decl) ? d.decl : d }
+          elsif entry.respond_to?(:decl)
+            [entry.decl]
+          else
+            []
+          end
+        end
+
         # Appends freshly-parsed declarations to an `RBS::Environment` across the gemspec's supported RBS
         # range (`rbs >= 3.0, < 5.0`). RBS 4.x wraps the declarations in an `RBS::Source::RBS` and takes them
         # through `env.add_source`; RBS 3.x has neither `RBS::Source` nor `add_source` and instead registers
@@ -336,9 +530,17 @@ module Rigor
         end
 
         # Adds empty stub declarations for the missing referenced types (and any enclosing namespace they
-        # need) to the pre-resolve env, tagged with {SYNTHETIC_STUB_BUFFER}. A name that is a prefix of
-        # another name is declared `module` (it is a namespace); a leaf is declared `class` (referenced types
-        # appear in instance position far more often than as mixins).
+        # need) to the pre-resolve env, tagged with {SYNTHETIC_STUB_BUFFER}. Returns true when at least one
+        # declaration landed, so {.stub_missing_referenced_types} can stop on a pass that made no progress.
+        #
+        # Each name gets the declaration kind its own syntax requires ({.stub_declaration_for}), and each
+        # declaration is validated ALONE before it joins the buffer. Declaring every name `class` — the shape
+        # before #237 — made a dangling interface (`_Foo`) or type-alias (`foo`) reference unparseable, and
+        # since the batch shares one buffer the `RBS::BaseError` rescue below then discarded every stub in it,
+        # well-formed ones included. Measured on herb, whose 74 missing names are all dangling type aliases:
+        # the pass synthesized nothing at all, leaving the project's 48 signature files inert, while still
+        # paying for the detection sweep. A per-declaration check costs one small parse per name and bounds
+        # the damage of one bad name to itself.
         #
         # Names already declared in `base_env` are skipped — exactly the `declared.include?` guard
         # {.collect_missing_namespaces} applies. Without it, stubbing a nested reference (`Foo::Bar::Baz`)
@@ -356,17 +558,45 @@ module Rigor
             (1...parts.length).each { |i| names << parts[0, i].join("::") }
           end
           names = names.reject { |name| declared.include?(name) }.to_set
-          return if names.empty?
+          return false if names.empty?
 
-          source = names.sort_by { |n| n.count(":") }.map do |name|
-            keyword = names.any? { |other| other != name && other.start_with?("#{name}::") } ? "module" : "class"
-            "#{keyword} #{name}\nend\n"
+          source = names.sort_by { |n| n.count(":") }.filter_map do |name|
+            declaration = stub_declaration_for(name, names)
+            declaration if parseable_rbs?(declaration)
           end.join
+          return false if source.empty?
+
           buffer = ::RBS::Buffer.new(name: SYNTHETIC_STUB_BUFFER, content: source)
           _, directives, decls = ::RBS::Parser.parse_signature(buffer)
           add_parsed_decls(base_env, buffer, directives, decls)
+          true
         rescue ::RBS::BaseError
-          nil
+          false
+        end
+
+        # The declaration one stubbed name needs, keyed on the syntax of its leaf:
+        #
+        # * a name other stubbed names nest inside is a namespace, so `module`;
+        # * an RBS interface name (`_Foo`) may only be declared `interface`;
+        # * a type-alias name (`foo`) may only be declared `type`, and aliases `untyped` so a value of that
+        #   type reads as `Dynamic[Top]` — the honest answer for a type Rigor invented;
+        # * anything else is `class` (referenced types appear in instance position far more often than as
+        #   mixins).
+        #
+        # The interface stub is FP-safe without joining {#synthesized_type_names}: {RbsTypeTranslator} maps
+        # every interface type to untyped, and the nil / non-nil acceptance guards in {Analysis::CheckRules}
+        # treat a method-less interface as accepting everything.
+        def stub_declaration_for(name, names)
+          leaf = name.split("::").last.to_s
+          if names.any? { |other| other != name && other.start_with?("#{name}::") }
+            "module #{name}\nend\n"
+          elsif leaf.start_with?("_")
+            "interface #{name}\nend\n"
+          elsif leaf.match?(/\A[a-z]/)
+            "type #{name} = untyped\n"
+          else
+            "class #{name}\nend\n"
+          end
         end
 
         # The `::`-stripped names of every class / module / class-alias declaration already present in
@@ -389,6 +619,9 @@ module Rigor
 
           virtual_rbs.each do |filename, content|
             next if content.nil? || content.empty?
+            # Same pre-parser guard as {.parse_signature_file}: a synthesizer echoing project bytes can carry
+            # invalid UTF-8, which pre-4.1 rbs lexers could hang on — and a hang escapes the rescue below.
+            next if invalid_encoding?(content.to_s)
 
             buffer = ::RBS::Buffer.new(name: filename.to_s, content: content.to_s)
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
@@ -437,6 +670,71 @@ module Rigor
           [Pathname(CORE_OVERLAY_SIGS_ROOT)]
         end
 
+        # Bundled signature sources that SUPPLEMENT a stdlib library's own declarations rather than stand
+        # alone: each re-opens a class the named `RBS::EnvironmentLoader` library declares with a mixin
+        # (`CGI::QueryExtension`), a superclass (`Prism::Result`), or an `| ...` overload continuation
+        # (`StringScanner#[]`, `Resolv#initialize`). Loading one into an environment built WITHOUT its
+        # library does not fail the env build — `RBS::DefinitionBuilder` raises later
+        # (`NoMixinFoundError` / `NoSuperclassFoundError` / `InvalidOverloadMethodError`), Rigor fails soft,
+        # and the WHOLE re-opened class silently degrades to `Dynamic[top]` (issue #299's narrow-environment
+        # tail). So each supplement is loaded ONLY when its library actually resolved; in production every
+        # gating library is in `Environment::DEFAULT_LIBRARIES`, so the full environment is unchanged.
+        #
+        # `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.
+        #
+        # Keyed by `data/vendored_gem_sigs/` directory basename.
+        LIBRARY_SUPPLEMENT_VENDORED_DIRS = {
+          "cgi" => "cgi",
+          "prism" => "prism"
+        }.freeze
+        private_constant :LIBRARY_SUPPLEMENT_VENDORED_DIRS
+
+        # Keyed by `data/core_overlay/` file basename. Files not listed here re-open Ruby-core classes (or
+        # add self-contained declarations) and stay unconditional.
+        LIBRARY_SUPPLEMENT_CORE_OVERLAYS = {
+          "resolv.rbs" => "resolv",
+          "string_scanner.rbs" => "strscan"
+        }.freeze
+        private_constant :LIBRARY_SUPPLEMENT_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.
+        #
+        # @param loaded_library_names [Set<String>] libraries that actually resolved on this loader.
+        def add_bundled_signatures(rbs_loader, loaded_library_names)
+          vendored_gem_sig_paths.each do |path|
+            next unless path.directory?
+            next unless supplement_dependency_loaded?(LIBRARY_SUPPLEMENT_VENDORED_DIRS, path, loaded_library_names)
+
+            rbs_loader.add(path: path)
+          end
+          core_overlay_sig_paths.each do |dir|
+            next unless dir.directory?
+
+            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)
+
+              rbs_loader.add(path: file)
+            end
+          end
+        end
+
+        # @param supplements [Hash{String => String}] basename → gating library map.
+        # @param path [Pathname] the vendored directory or overlay file to test.
+        # @param loaded_library_names [Set<String>] libraries that actually resolved on this loader.
+        # @return [Boolean] true when `path` carries no library dependency, or its library loaded.
+        def supplement_dependency_loaded?(supplements, path, loaded_library_names)
+          library = supplements[path.basename.to_s]
+          library.nil? || loaded_library_names.include?(library)
+        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
@@ -506,10 +804,11 @@ module Rigor
         @virtual_rbs = virtual_rbs.map { |name, content| [name.to_s.dup.freeze, content.to_s.dup.freeze].freeze }.freeze
         # Per-loader memoization bucket. Held as a single mutable Hash so the loader instance itself can be
         # `.freeze`d (per ADR-15 reflection-facade contract) without losing the lazy-memo behaviour. Slot
-        # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:builder`, `:reflection`,
-        # `:instance_definitions_table`, `:singleton_definitions_table`. Constructed via `Hash.new` (NOT a
-        # `{ ... }` literal) so Rigor's `HashShape` narrowing doesn't infer a fixed key set from the initial
-        # state and fold post-initial slot reads (e.g. `@state[:env_loaded]`) to a constant `nil`.
+        # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:definition_build_warned`,
+        # `:builder`, `:reflection`, `:instance_definitions_table`, `:singleton_definitions_table`.
+        # Constructed via `Hash.new` (NOT a `{ ... }` literal) so Rigor's `HashShape` narrowing doesn't
+        # infer a fixed key set from the initial state and fold post-initial slot reads (e.g.
+        # `@state[:env_loaded]`) to a constant `nil`.
         @state = Hash.new # rubocop:disable Style/EmptyLiteral
         @instance_definition_cache = {}
         @singleton_definition_cache = {}
@@ -580,6 +879,11 @@ module Rigor
       # that mention them could build (e.g. an unavailable `DRb::DRbServer`, or a stale
       # `Textbringer::EditorError`). Recovered off the built env like {#synthesized_namespaces}, so it
       # survives the marshalled-env cache.
+      #
+      # Class / module stubs only — the `interface` and `type` stubs {.stub_declaration_for} also emits live in
+      # `interface_decls` / `type_alias_decls`, not `class_decls`. That is deliberate: this list exists to feed
+      # {#synthesized_type_names}, whose consumers key on a nominal receiver's class name, and both of those
+      # kinds already read as untyped through {Inference::RbsTypeTranslator}.
       def synthesized_stub_types
         names_synthesized_in(SYNTHETIC_STUB_BUFFER)
       end
@@ -963,7 +1267,7 @@ module Rigor
         return [] if e.nil?
 
         names = e.class_decls.filter_map do |type_name, entry|
-          decls = entry_declarations(entry)
+          decls = self.class.entry_declarations(entry)
           next if decls.empty?
           next unless decls.all? { |decl| synthetic_decl?(decl, buffer_name) }
 
@@ -972,23 +1276,6 @@ module Rigor
         names.sort_by { |name| name.count("::") }
       end
 
-      # Collects the AST declaration nodes behind a `class_decls` entry across the supported RBS range (`rbs
-      # >= 3.0, < 5.0`). RBS 4's `ModuleEntry` / `ClassEntry` expose `each_decl` yielding bare AST
-      # declarations; RBS 3.x exposes `decls`, an array of `MultiEntry::D` wrappers whose `#decl` is the AST
-      # declaration. The single-`decl` shape is handled defensively so the loader survives an rbs-gem minor
-      # bump.
-      def entry_declarations(entry)
-        if entry.respond_to?(:each_decl)
-          [].tap { |acc| entry.each_decl { |decl| acc << decl } }
-        elsif entry.respond_to?(:decls)
-          entry.decls.map { |d| d.respond_to?(:decl) ? d.decl : d }
-        elsif entry.respond_to?(:decl)
-          [entry.decl]
-        else
-          []
-        end
-      end
-
       # True when an AST declaration was emitted into `buffer_name` (one of the synthetic-source sentinels)
       # — identified by the buffer name on its location.
       def synthetic_decl?(decl, buffer_name)
@@ -1230,7 +1517,8 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_instance(rbs_name)
-      rescue ::RBS::BaseError
+      rescue ::RBS::BaseError => e
+        warn_about_definition_build_failure(class_name, e)
         nil
       end
 
@@ -1243,10 +1531,81 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_singleton(rbs_name)
-      rescue ::RBS::BaseError
+      rescue ::RBS::BaseError => e
+        warn_about_definition_build_failure(class_name, e)
         nil
       end
 
+      # The third twin of {#warn_about_quarantined_signatures} / {#warn_about_virtual_rbs_collisions}: name,
+      # once per class per PROCESS, a `RBS::DefinitionBuilder` failure caught in
+      # {#build_instance_definition} / {#build_singleton_definition}'s rescue. Without it, `class_known?`
+      # stays true (it only consults {#known_class_names_set}, never a definition build), so every call on
+      # the class — real methods and typos alike — silently degrades to `Dynamic[top]`.
+      #
+      # STRUCTURAL DIVERGENCE from its two siblings: they fire from the single central site at the end of
+      # {#env}, because the whole env is built eagerly and every quarantine/collision is already known by
+      # then. Definition builds are LAZY (ADR-54 WD1 — built on demand per class the FIRST time a caller asks,
+      # long after {#env} has already run), so there is no later central checkpoint to fire from before the
+      # affected classes even exist. This warns inline at the rescue site instead, gated on
+      # `@state[:definition_build_warned]` (keyed by class name) so the instance and singleton sides — and
+      # any re-entry once the per-process `@instance_definition_cache` / `@singleton_definition_cache`
+      # memoize the failure — warn at most once per class name, cache-hit runs included (a definition build
+      # is per-process regardless of the RBS-env cache tier). `@state` is per-LOADER-INSTANCE, not
+      # process-global, so under the fork-based analysis pool each worker holds its own loader and its own
+      # `@state`: a class whose definition fails can print its warning once per worker that happens to touch
+      # it, i.e. more than once in a single `rigor check` run. Deduplicating that across processes is out of
+      # scope here — see [#295](https://github.com/rigortype/rigor/issues/295).
+      def warn_about_definition_build_failure(class_name, error)
+        warned = (@state[:definition_build_warned] ||= {})
+        key = class_name.to_s
+        return if warned[key]
+
+        warned[key] = true
+        first_line = error.message.to_s.lines.first.to_s.strip
+        buffers = definition_build_conflict_buffers(error)
+        collisions =
+          if buffers.empty?
+            ""
+          else
+            listed = buffers.first(QUARANTINE_WARN_LIMIT)
+            more = buffers.size - listed.size
+            lines = listed.map { |name| "    - #{name}" }
+            lines << "    … and #{more} more" if more.positive?
+            "\n  Colliding declaration(s):\n#{lines.join("\n")}"
+          end
+        warn(
+          "rigor: RBS definition build failed for `#{class_name}`: #{error.class}: #{first_line}\n  " \
+          "Rigor still treats the class as known, so calls into it now silently degrade to\n  " \
+          "`Dynamic[top]` — real methods and typos alike — instead of resolving normally.#{collisions}"
+        )
+      end
+
+      # The definition-build twin of {#env_build_conflict_buffers}: the declaration source file(s) named by a
+      # `RBS::DefinitionBuilder` failure, so {#warn_about_definition_build_failure} can name the colliding
+      # declarations rather than only the exception's class and message. The payload shape varies by error
+      # class (`references/rbs`'s `lib/rbs/errors.rb`): `DuplicatedMethodDefinitionError` and
+      # `InvalidOverloadMethodError` carry `#members` (each with a `#location`);
+      # `DuplicatedInterfaceMethodDefinitionError` carries a single `#member`; most others
+      # (`NoSuperclassFoundError`, `UnknownMethodAliasError`, `RecursiveAncestorError`, …) carry only a bare
+      # `#location`. Falls back to an empty list — the warning still names the class and the exception's own
+      # message — for the remainder (e.g. `SuperclassMismatchError`, which carries neither).
+      def definition_build_conflict_buffers(error)
+        locations =
+          if error.respond_to?(:members) && error.members
+            Array(error.members).map(&:location)
+          elsif error.respond_to?(:member) && error.member
+            [error.member.location]
+          elsif error.respond_to?(:location)
+            [error.location]
+          else
+            []
+          end
+
+        locations.compact.filter_map { |loc| loc.buffer&.name }.map(&:to_s).uniq.freeze
+      rescue ::RBS::BaseError, StandardError
+        [].freeze
+      end
+
       # Resolve an RBS class/module ALIAS to its canonical declared name. `class Mutex = Thread::Mutex`
       # lives only in `class_alias_decls`, so `class_known?` reports it (it checks that table) but the
       # definition builder — which only knows `class_decls` — could not enumerate its methods, leaving alias