rigortype 0.1.14 → 0.1.16

data/lib/rigor/cli/plugins_renderer.rb

@@ -13,7 +13,7 @@ module Rigor
     # tooling (SKILLs, CI, editor integrations) while text is
     # for interactive inspection. Rows are printed in the order
     # the loader resolved them.
-    class PluginsRenderer
+    class PluginsRenderer # rubocop:disable Metrics/ClassLength
       def initialize(rows:, configuration_path:)
         @rows = rows
         @configuration_path = configuration_path
@@ -42,8 +42,74 @@ module Rigor
         )
       end
 
+      # ADR-37 § "Machine-readable capability catalogue" — the focused
+      # per-plugin extension-protocol dump. Only loaded plugins appear
+      # (a plugin that failed to load contributes no capabilities), and
+      # each carries only the gate values an agent enumerates to learn
+      # what the plugin does: node-rule node types, dynamic-return
+      # receivers, type-specifier methods, and produced / consumed facts.
+      def capabilities_json
+        JSON.pretty_generate(
+          {
+            "configuration" => @configuration_path,
+            "capabilities" => loaded_rows.map { |row| capabilities_json_for(row) }
+          }
+        )
+      end
+
+      def capabilities_text
+        lines = ["Plugin capability catalogue (ADR-37 narrow extension protocols)", ""]
+        loaded = loaded_rows
+        if loaded.empty?
+          lines << "  (no plugins loaded)"
+        else
+          loaded.each_with_index do |row, index|
+            lines.concat(capability_lines(row))
+            lines << "" unless index == loaded.size - 1
+          end
+        end
+        lines.join("\n")
+      end
+
       private
 
+      def loaded_rows
+        @rows.select { |r| r[:status] == :loaded }
+      end
+
+      def capability_lines(row)
+        lines = ["  #{row[:id]}  v#{row[:version]}  (#{row[:gem]})"]
+        capability_surfaces(row).each { |surface| lines << "        #{surface}" }
+        lines << "        (no narrow extension protocols declared)" if lines.size == 1
+        lines
+      end
+
+      # The non-empty capability surfaces for a plugin, each as a
+      # `label: a, b, c` string. Data-driven so the catalogue stays a
+      # single source of truth shared between the text and JSON views.
+      def capability_surfaces(row)
+        [
+          ["node_rule", row[:node_rule_types]],
+          ["dynamic_return receivers", row[:dynamic_return_receivers]],
+          ["type_specifier methods", row[:type_specifier_methods]],
+          ["produces", row[:produces]],
+          ["consumes", row[:consumes]]
+        ].filter_map { |label, values| "#{label}: #{values.join(', ')}" if values.any? }
+      end
+
+      def capabilities_json_for(row)
+        {
+          "id" => row[:id],
+          "gem" => row[:gem],
+          "version" => row[:version],
+          "node_rule_types" => row[:node_rule_types],
+          "dynamic_return_receivers" => row[:dynamic_return_receivers],
+          "type_specifier_methods" => row[:type_specifier_methods],
+          "produces" => row[:produces],
+          "consumes" => row[:consumes]
+        }
+      end
+
       def header
         loaded = @rows.count { |r| r[:status] == :loaded }
         errored = @rows.count { |r| r[:status] == :load_error }
@@ -99,6 +165,22 @@ module Rigor
         lines << "        owns_receivers: #{row[:owns_receivers].join(', ')}" if row[:owns_receivers].any?
         lines << "        produces: #{row[:produces].join(', ')}" if row[:produces].any?
         lines << "        consumes: #{row[:consumes].join(', ')}" if row[:consumes].any?
+        lines.concat(narrow_protocol_lines(row))
+        lines
+      end
+
+      # ADR-37 narrow extension protocols (node_rule / dynamic_return /
+      # type_specifier). Surfaced in the full report alongside the
+      # declarative surfaces; `--capabilities` is the focused view.
+      def narrow_protocol_lines(row)
+        lines = []
+        lines << "        node_rule: #{row[:node_rule_types].join(', ')}" if row[:node_rule_types].any?
+        if row[:dynamic_return_receivers].any?
+          lines << "        dynamic_return receivers: #{row[:dynamic_return_receivers].join(', ')}"
+        end
+        if row[:type_specifier_methods].any?
+          lines << "        type_specifier methods: #{row[:type_specifier_methods].join(', ')}"
+        end
         lines
       end
 
@@ -157,6 +239,9 @@ module Rigor
           "hkt_definitions" => row[:hkt_definitions],
           "protocol_contracts" => row[:protocol_contracts],
           "source_rbs_synthesizer" => row[:source_rbs_synthesizer],
+          "node_rule_types" => row[:node_rule_types],
+          "dynamic_return_receivers" => row[:dynamic_return_receivers],
+          "type_specifier_methods" => row[:type_specifier_methods],
           "load_error" => row[:load_error]
         }
       end

data/lib/rigor/cli.rb

@@ -33,6 +33,7 @@ module Rigor
       "triage" => :run_triage,
       "coverage" => :run_coverage,
       "plugins" => :run_plugins,
+      "plugin" => :run_plugin,
       "playground" => :run_playground,
       "skill" => :run_skill
     }.freeze
@@ -77,11 +78,7 @@ module Rigor
     end
 
     def run_check
-      require_relative "analysis/runner"
-      require_relative "analysis/buffer_binding"
-      require_relative "analysis/baseline"
-      require_relative "cache/store"
-
+      load_check_dependencies
       options = parse_check_options
       buffer = resolve_buffer_binding(options)
       return EXIT_USAGE if buffer == :usage_error
@@ -99,6 +96,7 @@ module Rigor
 
       write_result(result, options.fetch(:format))
       write_run_stats(result.stats) if result.stats
+      write_trace_appendices
       write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
 
       exit_code = result.success? ? 0 : 1
@@ -401,6 +399,139 @@ module Rigor
       stats.format(@err)
     end
 
+    # Opt-in developer diagnostics printed after the run: the
+    # inference-cutoff trace (RIGOR_BUDGET_TRACE) and the heap-attribution
+    # profile (RIGOR_HEAP_PROFILE). Each gates itself, so this is a no-op
+    # on a normal run.
+    def write_trace_appendices
+      write_budget_trace
+      write_heap_profile
+    end
+
+    # Dumps the opt-in inference-cutoff counters (RIGOR_BUDGET_TRACE).
+    # These are the hard-coded "budget" guards that silently degrade
+    # to `Dynamic[top]` / a fallback bound — counting them shows where
+    # inference actually stopped. Process-global counters: meaningful
+    # only on a single-process run (`--workers 0`), since they do not
+    # cross fork boundaries.
+    def write_budget_trace
+      return unless Inference::BudgetTrace.enabled?
+
+      counts = Inference::BudgetTrace.snapshot
+      @err.puts("")
+      @err.puts("Inference cutoffs (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
+      @err.puts("  recursion-guard hits:      #{counts[Inference::BudgetTrace::RECURSION_GUARD]}")
+      @err.puts("  ancestor-walk-limit hits:  #{counts[Inference::BudgetTrace::ANCESTOR_WALK_LIMIT]}")
+      @err.puts("  hkt-fuel-exhausted hits:   #{counts[Inference::BudgetTrace::HKT_FUEL_EXHAUSTED]}")
+      write_budget_distributions
+    end
+
+    # Dumps the read-only size distributions (ADR-41 Slice 2a). These
+    # observe how large unions actually get, with no cap enforced — the
+    # data the `union_size` budget default should be chosen from. The
+    # `over` thresholds bracket the TypeProf prior (10) and Rigor's spec
+    # default (24).
+    def write_budget_distributions
+      summary = Inference::BudgetTrace.summarize(Inference::BudgetTrace::UNION_ARITY, over: [10, 24, 40])
+      pct = summary[:percentiles]
+      @err.puts("  union arity:  n=#{summary[:count]} max=#{summary[:max]} " \
+                "p50=#{pct[:p50]} p90=#{pct[:p90]} p99=#{pct[:p99]}")
+      over = summary[:over]
+      @err.puts("    unions ≥10: #{over[10]}  ≥24: #{over[24]}  ≥40: #{over[40]}")
+    end
+
+    # Dumps a live-heap class breakdown (RIGOR_HEAP_PROFILE) — retained
+    # objects by class after a forced GC, ranked by total memsize. The
+    # tool for attributing where the analyzer's resident memory goes
+    # (ADR-41 Slice 2b): it answers whether the heap is type carriers,
+    # RBS objects, Prism nodes, or fact-store Hashes/Strings. Walking the
+    # whole heap is slow — a dev probe, not a normal diagnostic. Run
+    # single-process (`--workers 0`) so the parent heap is the analysis
+    # heap; the gem is required lazily so a normal run never loads it.
+    def write_heap_profile
+      return if ENV["RIGOR_HEAP_PROFILE"].to_s.empty?
+
+      by_class, total = tally_live_heap
+      @err.puts("")
+      @err.puts("Heap profile (RIGOR_HEAP_PROFILE; live objects after GC, by class)")
+      @err.puts("  total tracked: #{heap_mb(total)} across #{by_class.size} classes")
+      by_class.sort_by { |_, (_, bytes)| -bytes }.first(30).each do |name, (count, bytes)|
+        @err.puts("  #{heap_mb(bytes).rjust(10)}  #{count.to_s.rjust(9)} obj  #{name}")
+      end
+      write_string_allocation_sites
+    end
+
+    # Loads the analysis-path dependencies lazily (so non-check commands
+    # stay light) and starts heap-allocation tracing if requested, before
+    # any analysis object is allocated.
+    def load_check_dependencies
+      require_relative "analysis/runner"
+      require_relative "analysis/buffer_binding"
+      require_relative "analysis/baseline"
+      require_relative "cache/store"
+      start_heap_trace_if_requested
+    end
+
+    # Starts allocation tracing (RIGOR_HEAP_TRACE) as early as possible so
+    # the heap profile can attribute retained Strings to their allocation
+    # `file:line`. Very high overhead — run on a small file subset only.
+    def start_heap_trace_if_requested
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      require "objspace"
+      ObjectSpace.trace_object_allocations_start
+    end
+
+    # When RIGOR_HEAP_TRACE is on, groups the live String objects by their
+    # allocation site (`sourcefile:sourceline`) and prints the top sites by
+    # count — pinpointing which engine code retains the millions of strings
+    # that dominate the large-app heap (ADR-41 Slice 2b). Strings allocated
+    # before tracing started report `(pre-trace)`.
+    def write_string_allocation_sites
+      return if ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+
+      by_site = Hash.new(0)
+      ObjectSpace.each_object(String) do |str|
+        file = ObjectSpace.allocation_sourcefile(str)
+        line = ObjectSpace.allocation_sourceline(str)
+        by_site[file ? "#{file}:#{line}" : "(pre-trace)"] += 1
+      end
+      @err.puts("")
+      @err.puts("  String allocation sites (top 25 by live count)")
+      by_site.sort_by { |_, n| -n }.first(25).each do |site, n|
+        @err.puts("  #{n.to_s.rjust(9)}  #{site}")
+      end
+    end
+
+    # Walks the whole live heap (after a forced GC) and tallies
+    # `{class_name => [count, memsize]}` plus the grand total. Returns
+    # `[by_class, total]`. Slow — a dev probe only.
+    def tally_live_heap
+      require "objspace"
+      GC.start
+      by_class = Hash.new { |h, k| h[k] = [0, 0] }
+      total = 0
+      ObjectSpace.each_object do |obj|
+        size = ObjectSpace.memsize_of(obj)
+        entry = by_class[heap_class_name(obj)]
+        entry[0] += 1
+        entry[1] += size
+        total += size
+      end
+      [by_class, total]
+    end
+
+    def heap_class_name(obj)
+      klass = Object.instance_method(:class).bind_call(obj)
+      klass.name || klass.inspect
+    rescue StandardError
+      "(unknown)"
+    end
+
+    def heap_mb(bytes)
+      Kernel.format("%.1f MB", bytes / 1_048_576.0)
+    end
+
     def write_cache_stats(cache_root, runtime_store)
       inv = Cache::Store.disk_inventory(root: cache_root)
 
@@ -642,6 +773,12 @@ module Rigor
       CLI::SkillCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_plugin
+      require_relative "cli/plugin_command"
+
+      CLI::PluginCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -688,6 +825,7 @@ module Rigor
           triage     Summarise diagnostics: distribution, hotspots, hints (ADR-23)
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
           plugins    Report activation status of every configured plugin
+          plugin     Browse bundled plugin source as worked examples (list/path/print/root)
           playground Start the browser playground (requires rigor-playground gem)
           skill      List or print bundled Agent Skills (rigor-project-init, ...)
           version    Print the Rigor version

data/lib/rigor/configuration/severity_profile.rb

@@ -51,6 +51,9 @@ module Rigor
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
           "def.method-visibility-mismatch" => :warning,
+          "def.override-visibility-reduced" => :off,
+          "def.override-return-widened" => :off,
+          "def.override-param-narrowed" => :off,
           "def.ivar-write-mismatch" => :warning
         }.freeze,
         balanced: {
@@ -67,6 +70,9 @@ module Rigor
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
           "def.method-visibility-mismatch" => :error,
+          "def.override-visibility-reduced" => :warning,
+          "def.override-return-widened" => :warning,
+          "def.override-param-narrowed" => :warning,
           "def.ivar-write-mismatch" => :warning
         }.freeze,
         strict: {
@@ -83,6 +89,9 @@ module Rigor
           "dump.type" => :error,
           "def.return-type-mismatch" => :error,
           "def.method-visibility-mismatch" => :error,
+          "def.override-visibility-reduced" => :error,
+          "def.override-return-widened" => :error,
+          "def.override-param-narrowed" => :error,
           "def.ivar-write-mismatch" => :error
         }.freeze
       }.freeze

data/lib/rigor/environment/rbs_loader.rb

@@ -30,6 +30,24 @@ module Rigor
     # See docs/internal-spec/inference-engine.md for the binding contract.
     # rubocop:disable Metrics/ClassLength
     class RbsLoader
+      # Buffer name stamped on the `module` declarations synthesized by
+      # {.synthesize_missing_namespaces}. Re-read off the built env by
+      # {#synthesized_namespaces} so the analysis layer can surface an
+      # `:info` diagnostic naming the project's malformed-RBS namespaces
+      # — robust across the marshalled env cache, since the sentinel
+      # rides along on each synthetic declaration's location.
+      SYNTHETIC_NAMESPACE_BUFFER = "(rigor: synthesized namespaces)"
+
+      # Buffer name stamped on the stub `class` / `module` declarations
+      # synthesized by {.stub_missing_referenced_types} for types the
+      # project's RBS references but no loaded signature declares.
+      # {#synthesized_stub_types} reads them back off the built env (so
+      # the answer survives the marshalled env cache), and
+      # {#synthesized_type_names} folds them together with the
+      # namespace stubs into the set {MethodDispatcher} resolves to
+      # `Dynamic[Top]` (no false `call.undefined-method`).
+      SYNTHETIC_STUB_BUFFER = "(rigor: synthesized stub types)"
+
       class << self
         def default
           @default ||= new.freeze
@@ -72,7 +90,172 @@ module Rigor
           end
           env = RBS::Environment.from_loader(rbs_loader)
           add_virtual_rbs(env, virtual_rbs)
-          env.resolve_type_names
+          synthesize_missing_namespaces(env)
+          resolved = env.resolve_type_names
+          stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
+        end
+
+        # ADR-5 robustness, second tier. A project `signature_paths:`
+        # RBS that *references* a type no loaded signature declares —
+        # `def x: () -> DRb::DRbServer` when the `drb` RBS is not
+        # available, or a stale reference to its own removed
+        # `Textbringer::EditorError` — makes
+        # `RBS::DefinitionBuilder#build_instance` raise
+        # `NoTypeFoundError`, and (per RBS's all-or-nothing per-class
+        # build) that single unresolved reference takes down EVERY
+        # method on the class, not just the one signature. Observed on
+        # shugo/textbringer: one `DRb::DRbServer` reference left the
+        # whole `Textbringer::Commands` module — including its
+        # 186-call-site `define_command` DSL — resolving as
+        # `Dynamic[Top]`.
+        #
+        # We synthesize an empty stub for each such referenced-but-
+        # undeclared type so the rest of the class builds. A leaf type
+        # is stubbed as `class`, its enclosing namespaces as `module`.
+        # Stubbed types carry no methods, so a call against a value of
+        # a stubbed type would otherwise mis-fire `call.undefined-method`;
+        # {MethodDispatcher} consults {#synthesized_type_names} and
+        # resolves such 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.
+        MAX_STUB_PASSES = 5
+
+        def stub_missing_referenced_types(base_env, resolved, project_files)
+          return resolved if project_files.empty?
+
+          MAX_STUB_PASSES.times do
+            missing = unresolved_referenced_types(resolved, project_files)
+            break if missing.empty?
+
+            append_stub_declarations(base_env, missing)
+            resolved = base_env.resolve_type_names
+          end
+          resolved
+        end
+
+        # Robustness (ADR-5): a project whose RBS declares qualified
+        # names (`class Foo::Bar`) without ever declaring the enclosing
+        # namespace (`module Foo`) is invalid by upstream RBS rules —
+        # `RBS::DefinitionBuilder#build_instance` raises
+        # `NoTypeFoundError: Could not find ::Foo`, which the loader's
+        # fail-soft rescue turns into a silent dispatch miss (every
+        # method on every such class degrades to `Dynamic[Top]`). This
+        # is a common authoring mistake (e.g. shugo/textbringer ships a
+        # `sig/` that `rbs validate` itself rejects). Rather than let an
+        # otherwise-usable signature set contribute nothing, synthesize
+        # an empty `module` declaration for each undeclared enclosing
+        # namespace so the definitions build. We only ever add names
+        # that are absent — a genuinely-declared namespace (module or
+        # class, here or in a loaded gem) is left untouched.
+        def synthesize_missing_namespaces(env)
+          missing = collect_missing_namespaces(env)
+          return if missing.empty?
+
+          source = missing.map { |name| "module #{name}\nend\n" }.join
+          buffer = ::RBS::Buffer.new(name: SYNTHETIC_NAMESPACE_BUFFER, content: source)
+          _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+          env.add_source(::RBS::Source::RBS.new(buffer, directives || [], decls || []))
+        rescue ::RBS::BaseError
+          # Fail-soft: synthesis is an opportunistic uplift, never a
+          # hard requirement. A parse failure here just leaves the env
+          # as it was (dispatch misses on the affected classes).
+          nil
+        end
+
+        # Returns the `::`-stripped names of every enclosing namespace
+        # that some declaration references but no declaration defines,
+        # shallowest-first so the synthesized source declares `Foo`
+        # before `Foo::Bar`.
+        def collect_missing_namespaces(env)
+          declared = env.class_decls.keys.to_set
+          missing = {}
+          env.class_decls.each_key do |type_name|
+            path = type_name.namespace.path
+            path.each_index do |i|
+              prefix = path[0..i]
+              full = ::RBS::TypeName.parse("::#{prefix.join('::')}")
+              missing[prefix.join("::")] = prefix.length unless declared.include?(full)
+            end
+          end
+          missing.sort_by { |_name, depth| depth }.map(&:first)
+        end
+
+        # The absolute paths of every `.rbs` file under the project's
+        # `signature_paths:` (NOT vendored / stdlib RBS — those are
+        # well-formed, so attempting to build them would only waste
+        # time). Used to scope the referenced-type build sweep.
+        def project_sig_files(signature_paths)
+          signature_paths.flat_map do |path|
+            path = Pathname(path) unless path.is_a?(Pathname)
+            next [] unless path.directory?
+
+            Dir.glob(path.join("**", "*.rbs")).map { |p| File.expand_path(p) }
+          end.to_set
+        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.
+        def unresolved_referenced_types(env, project_files)
+          builder = ::RBS::DefinitionBuilder.new(env: env)
+          missing = []
+          env.class_decls.each do |type_name, 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.
+            end
+          end
+          missing.uniq
+        end
+
+        # True when a `class_decls` entry was declared in one of the
+        # project's own signature files (by declaration location), so
+        # the sweep skips the bundled stdlib / vendored universe.
+        def project_entry?(entry, project_files)
+          decl = entry.respond_to?(:primary_decl) ? entry.primary_decl : nil
+          location = decl&.location
+          buffer_name = location&.buffer&.name
+          return false unless buffer_name
+
+          project_files.include?(File.expand_path(buffer_name.to_s))
+        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).
+        def append_stub_declarations(base_env, missing)
+          names = missing.to_set
+          missing.each do |name|
+            parts = name.split("::")
+            (1...parts.length).each { |i| names << parts[0, i].join("::") }
+          end
+          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"
+          end.join
+          buffer = ::RBS::Buffer.new(name: SYNTHETIC_STUB_BUFFER, content: source)
+          _, directives, decls = ::RBS::Parser.parse_signature(buffer)
+          base_env.add_source(::RBS::Source::RBS.new(buffer, directives || [], decls || []))
+        rescue ::RBS::BaseError
+          nil
         end
 
         # ADR-32 WD4 — merge synthesised-from-source RBS strings
@@ -192,6 +375,40 @@ module Rigor
         @hierarchy = RbsHierarchy.new(self)
       end
 
+      # The enclosing namespaces {.synthesize_missing_namespaces} had to
+      # invent because the project's `signature_paths:` RBS declared
+      # qualified names (`class Foo::Bar`) without ever declaring `Foo`.
+      # Recovered by scanning the built env for class/module entries
+      # whose every declaration originated from the synthetic buffer, so
+      # the answer survives the marshalled-env cache (where no build-time
+      # collector would). Returns `::`-stripped names, shallowest-first.
+      # Empty for a well-formed sig set (the common case) and whenever
+      # the env failed to build.
+      def synthesized_namespaces
+        names_synthesized_in(SYNTHETIC_NAMESPACE_BUFFER)
+      end
+
+      # The referenced-but-undeclared types
+      # {.stub_missing_referenced_types} stubbed so the project classes
+      # 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.
+      def synthesized_stub_types
+        names_synthesized_in(SYNTHETIC_STUB_BUFFER)
+      end
+
+      # Every type name Rigor invented to make an otherwise-inert /
+      # unbuildable project signature set resolve — both the namespace
+      # stubs and the referenced-type stubs. {MethodDispatcher} resolves
+      # a call whose receiver is one of these (and that no real
+      # signature answered) to `Dynamic[Top]`, so the empty stub never
+      # mis-fires `call.undefined-method`. Memoised; empty (and cheap)
+      # for the common well-formed sig set.
+      def synthesized_type_names
+        @state[:synthesized_type_names] ||= (synthesized_namespaces + synthesized_stub_types).to_set
+      end
+
       # Returns true when an RBS class or module declaration with the given
       # name is loaded. Accepts unprefixed or top-level-prefixed names
       # ("Integer" or "::Integer"). Memoized per-name (positive and
@@ -546,6 +763,47 @@ module Rigor
 
       private
 
+      # The `::`-stripped names of every class/module entry whose
+      # declarations ALL originated from the given sentinel buffer —
+      # i.e. names Rigor synthesized, not names the project declared.
+      # Reads off the built env so the answer survives the marshalled
+      # env cache; shallowest-first. Empty when the env failed to build.
+      def names_synthesized_in(buffer_name)
+        e = env
+        return [] if e.nil?
+
+        names = e.class_decls.filter_map do |type_name, entry|
+          decls = entry_declarations(entry)
+          next if decls.empty?
+          next unless decls.all? { |decl| synthetic_decl?(decl, buffer_name) }
+
+          type_name.to_s.sub(/\A::/, "")
+        end
+        names.sort_by { |name| name.count("::") }
+      end
+
+      # Collects the AST declaration nodes behind a `class_decls`
+      # entry. RBS 4's `ModuleEntry` / `ClassEntry` expose `each_decl`;
+      # the older 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?(: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)
+        location = decl.respond_to?(:location) ? decl.location : nil
+        location&.buffer&.name.to_s == buffer_name
+      end
+
       def constant_type_table
         @constant_type_table ||= begin
           require_relative "../cache/rbs_constant_table"

data/lib/rigor/environment.rb

@@ -512,8 +512,14 @@ module Rigor
     # presence check without materialising a type carrier.
     def class_known?(name)
       return true if class_registry.nominal_for_name(name)
-
-      class_known_in_rbs?(name)
+      return true if class_known_in_rbs?(name)
+
+      # ADR-36 nested-class emission — a variant subclass the
+      # substrate synthesised (e.g. `Shape::Circle` from a
+      # `variants do variant Circle, Float end` block) is a real
+      # class for resolution purposes even though no RBS / source
+      # declares it.
+      @synthetic_method_index&.knows_class?(name) || false
     end
 
     # ADR-15 Phase 2b — returns the loader's read-only,