rigortype 0.3.7 → 0.3.8

data/lib/rigor/environment/rbs_loader.rb

@@ -84,11 +84,14 @@ module Rigor
           # 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)
+          project_files = project_sig_files(signature_paths)
           add_project_signatures(env, signature_paths, deferred_signature_paths)
           add_virtual_rbs(env, virtual_rbs)
           synthesize_missing_namespaces(env)
-          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs)
-          stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
+          # 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.
+          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: project_files)
+          stub_missing_referenced_types(env, resolved, project_files)
         end
 
         # rbs ships `stdlib/bigdecimal/` and `stdlib/bigdecimal-math/` as two libraries, so
@@ -157,32 +160,61 @@ module Rigor
           false
         end
 
-        # Backstop for a virtual-vs-anything `RBS::DuplicatedDeclarationError` that only materialises at
-        # `resolve_type_names` (which rebuilds the env from `sources`). {.add_virtual_rbs}'s transactional
-        # rescue already handles the add-time case — empirically everything on rbs 4.x — but the rbs gemspec
-        # range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an rbs-internal choice
-        # this code must not depend on. Resolution rule is the same as the add-time path: the explicit
-        # signature wins, the colliding VIRTUAL buffer is dropped whole (`RBS::Environment#unload`) and
-        # resolution retries; every pass removes at least one virtual buffer, so the loop is bounded by the
-        # virtual-entry count. A duplicate involving no virtual buffer (sig-vs-sig), or an env without
-        # `#unload` (rbs 3.x), re-raises into the existing one-warning degrade path.
+        # Backstop for a `RBS::DuplicatedDeclarationError` that only materialises at `resolve_type_names`
+        # (which rebuilds the env from `sources`). {.add_virtual_rbs} / {.add_project_parsed_decls}
+        # transactionally handle the add-time case — empirically everything on rbs 4.x — but the rbs
+        # gemspec range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an
+        # rbs-internal choice this code must not depend on. Resolution preference: drop colliding VIRTUAL
+        # buffers first (explicit `.rbs` wins), else drop colliding PROJECT `signature_paths:` buffers
+        # (issue #777 — bundled RBS wins over a kind-colliding project file), then retry. Every pass
+        # removes at least one buffer, so the loop is bounded. A duplicate with neither virtual nor
+        # project culprits (bundled-vs-bundled), or an env without `#unload` (rbs 3.x), re-raises into
+        # the existing one-warning total-failure path.
         #
         # The dropped set is not returned: consumers recover it from the built env via
         # {#virtual_rbs_collision_quarantined}, which also works on a cache HIT where this build never ran.
-        def resolve_quarantining_virtual_collisions(env, virtual_rbs)
+        def resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: [])
           virtual_names = virtual_rbs.to_set { |name, _content| name.to_s }
-          (virtual_names.size + 1).times do
+          project_names = Array(project_files).to_set(&:to_s)
+          # Bound by virtual + project culprit candidates: each pass removes at least one buffer.
+          (virtual_names.size + project_names.size + 1).times do
             return [env, env.resolve_type_names]
           rescue ::RBS::DuplicatedDeclarationError => e
-            raise unless env.respond_to?(:unload)
+            env = unload_duplicated_declaration_culprits(
+              env, e, virtual_names: virtual_names, project_names: project_names
+            )
+          end
+          [env, env.resolve_type_names]
+        end
+
+        # Prefer dropping colliding VIRTUAL buffers (explicit `.rbs` wins), else PROJECT `signature_paths:`
+        # buffers (issue #777 — bundled RBS wins over a kind-colliding project file). A duplicate with
+        # neither virtual nor project culprits (bundled-vs-bundled), or an env without `#unload`, re-raises.
+        def unload_duplicated_declaration_culprits(env, error, virtual_names:, project_names:)
+          raise unless env.respond_to?(:unload)
 
-            culprits = e.decls.filter_map { |decl| decl.location&.buffer&.name }
-                        .uniq.select { |name| virtual_names.include?(name) }
-            raise if culprits.empty?
+          culprits = duplicated_declaration_buffer_names(error)
+          virtual_culprits = culprits.select { |name| virtual_names.include?(name.to_s) }
+          return env.unload(virtual_culprits) unless virtual_culprits.empty?
+
+          # Prefer dropping the project buffer(s): the bundled declaration stays, Greeter/core stay
+          # usable, and only the conflicting file is absent.
+          project_culprits = select_project_collision_culprits(culprits, project_names)
+          raise if project_culprits.empty?
+
+          env.unload(project_culprits)
+        end
 
-            env = env.unload(culprits)
+        def duplicated_declaration_buffer_names(error)
+          error.decls.filter_map { |decl| decl.location&.buffer&.name }.uniq
+        end
+
+        def select_project_collision_culprits(culprits, project_names)
+          culprits.select do |name|
+            project_names.include?(File.expand_path(name.to_s))
+          rescue ArgumentError, TypeError
+            project_names.include?(name.to_s)
           end
-          [env, env.resolve_type_names]
         end
 
         # ADR-5 robustness, second tier. A project `signature_paths:` RBS that *references* a type no loaded
@@ -298,11 +330,26 @@ module Rigor
             next if parsed.nil? # quarantined (unparseable) or unreadable — skip so the env survives
 
             buffer, directives, decls = parsed
-            add_parsed_decls(env, buffer, directives, decls)
+            add_project_parsed_decls(env, buffer, directives, decls)
           end
           add_deferred_signatures(env, deferred)
         end
 
+        # Issue #777 — add one project signature transactionally. `RBS::Environment#add_source` appends to
+        # `sources` BEFORE inserting decls, so a mid-insert `RBS::DuplicatedDeclarationError` (class-vs-module
+        # kind collision against bundled RBS, or a constant redeclared from core) would otherwise leave a
+        # poisoned source that `resolve_type_names` re-raises outside every per-file rescue, collapsing the
+        # WHOLE env to nil. Mirror {.add_virtual_rbs}: drop the poisoned source and continue so Greeter /
+        # core / every non-conflicting project file still load. Without a `sources` table (rbs 3.x) re-raise
+        # into the existing total-failure path — we cannot make the skip transactional there.
+        def add_project_parsed_decls(env, buffer, directives, decls)
+          add_parsed_decls(env, buffer, directives, decls)
+        rescue ::RBS::DuplicatedDeclarationError
+          raise unless env.respond_to?(:sources)
+
+          env.sources.reject! { |source| source.buffer.name == buffer.name }
+        end
+
         # Issue #610 — the DEFERRED half: signature files a bundled plugin contributes through its manifest,
         # added after every other source so each can be asked a question the eager half cannot be asked —
         # "does something already declare this class, at a different generic arity?".
@@ -331,7 +378,7 @@ module Rigor
             buffer, directives, decls = parsed
             next if generic_arity_conflict(env, decls)
 
-            add_parsed_decls(env, buffer, directives, decls)
+            add_project_parsed_decls(env, buffer, directives, decls)
           end
         end
 
@@ -436,6 +483,55 @@ module Rigor
           end
         end
 
+        # Issue #777 — project `signature_paths:` files that PARSE but are absent from the built env because
+        # {.add_project_parsed_decls} / {.resolve_quarantining_virtual_collisions} quarantined a duplicated
+        # declaration (typically class-vs-module or a constant already shipped by bundled RBS). Derived from
+        # the env like {#virtual_rbs_collision_quarantined}, so a cache HIT reports the same condition.
+        #
+        # Path membership alone is not enough: the suite's {RbsEnvMemo} reuses a byte-identical env across
+        # `Dir.mktmpdir` roots when `signature_paths:` are relative (`sig/sink.rbs`), leaving buffers named
+        # after the FIRST path. A later example's absolute path is then absent from `present` even though
+        # the declarations loaded — that used to spam `duplicated declaration against bundled RBS` banners
+        # (~60 per CI shard) for fixtures that never collided. Basename + content equality catches that
+        # reuse without hiding a real quarantine (e.g. project `class Base64` vs bundled `module Base64`,
+        # same basename, different bytes).
+        COLLISION_QUARANTINE_NOTE =
+          "duplicated declaration against bundled RBS — quarantined so the rest of the RBS env still loads"
+
+        def collision_quarantined_project_signatures(env, signature_paths)
+          return [] if env.nil?
+
+          present = env.buffers.to_set do |buffer|
+            name = buffer.name
+            next name.to_s unless name
+
+            File.expand_path(name.to_s)
+          rescue ArgumentError, TypeError
+            name.to_s
+          end
+          buffers_by_basename = env.buffers.group_by { |buffer| File.basename(buffer.name.to_s) }
+          project_sig_files(signature_paths).sort.filter_map do |file|
+            next if present.include?(file)
+            next if parse_signature_file(file).nil? # parse / encoding quarantine owns these
+            next if project_signature_loaded_under_other_path?(file, buffers_by_basename)
+
+            [file, "#{file}: #{COLLISION_QUARANTINE_NOTE}"]
+          end
+        end
+
+        # True when `file`'s bytes are already in `env` under a different absolute path (same basename).
+        # See {#collision_quarantined_project_signatures} — keeps memoised env reuse from looking like a
+        # collision quarantine.
+        def project_signature_loaded_under_other_path?(file, buffers_by_basename)
+          peers = buffers_by_basename[File.basename(file)]
+          return false if peers.nil? || peers.empty?
+
+          content = File.read(file, encoding: "UTF-8")
+          peers.any? { |buffer| buffer.content == content }
+        rescue Errno::ENOENT, Errno::EISDIR, Errno::EACCES
+          false
+        end
+
         # The `::`-stripped names of every type a PROJECT signature references that no loaded declaration
         # provides — the input to {.append_stub_declarations}.
         #
@@ -1000,8 +1096,10 @@ module Rigor
         # `.freeze`d (per ADR-15 reflection-facade contract) without losing the lazy-memo behaviour. Slot
         # names currently consulted: `:env`, `:env_loaded`, `:env_build_warned`, `:definition_build_warned`,
         # `:definition_build_details`, `:definition_build_reported`, `:definition_build_failures`,
-        # `:internal_demand`, `:builder`, `:reflection`, `:instance_definitions_table`,
-        # `:singleton_definitions_table`.
+        # `:definition_build_deferred_count`, `:definition_build_deferred_first`,
+        # `:definition_build_summary_warned`, `: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
         # infer a fixed key set from the initial state and fold post-initial slot reads (e.g.
         # `@state[:env_loaded]`) to a constant `nil`.
@@ -1031,7 +1129,17 @@ module Rigor
       #
       # @return [Array<Array(String, String)>] empty when every `signature_paths:` file parses.
       def quarantined_signatures
-        @state[:quarantined] ||= self.class.quarantined_project_signatures(@signature_paths).freeze
+        @state[:quarantined] ||= begin
+          parse_quarantined = self.class.quarantined_project_signatures(@signature_paths)
+          collision_quarantined = self.class.collision_quarantined_project_signatures(
+            @state[:env], @signature_paths
+          )
+          parse_paths = parse_quarantined.to_set { |path, _note| path }
+          (
+            parse_quarantined +
+            collision_quarantined.reject { |entry| parse_paths.include?(entry[0]) }
+          ).freeze
+        end
       end
 
       # Issue #610 — plugin-contributed signature files that stood down against a colliding generic arity,
@@ -1083,12 +1191,13 @@ module Rigor
       end
 
       # 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 by
-      # re-parsing so a cache HIT reports it too — a total failure (typically `RBS::DuplicatedDeclarationError`:
-      # a `signature_paths:` entry redeclaring a constant/class Rigor's bundled RBS already ships) collapses the
-      # WHOLE env to nil. A failed build produces no cached success to hide behind (nothing is persisted, so
-      # every run re-attempts and re-raises), so this is captured directly in {#env}'s rescue rather than
-      # re-derived. Forcing `env` (any query does) populates it.
+      # {#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
+      # `RBS::DuplicatedDeclarationError`s are quarantined per-file since #777; this slot remains for
+      # unrecoverable build errors (e.g. bundled-vs-bundled collisions, or hosts without a transactional
+      # `sources`/`unload` API). A failed build produces no cached success to hide behind (nothing is
+      # persisted, so every run re-attempts and re-raises), so this is captured directly in {#env}'s rescue
+      # rather than re-derived. Forcing `env` (any query does) populates it.
       #
       # @return [Array(String, String, Array<String>), nil] `[error_class_name, first_error_line,
       #   conflicting_buffer_names]`, or nil when the environment built successfully.
@@ -1736,11 +1845,10 @@ module Rigor
       end
 
       # The RBS environment for this loader. Memoised both on success AND on failure: when the env build
-      # raises (typically `RBS::DuplicatedDeclarationError` because a `signature_paths:` entry redeclares a
-      # constant or class already shipped by stdlib RBS), retrying on every subsequent `env` call would
-      # re-parse and re-resolve the whole sig set per AST node touched during analysis, multiplying per-file
-      # analysis cost by ~100x. Failures short-circuit to `nil` here and are surfaced to the user via
-      # `warn_about_env_build_failure_once` so the broken `signature_paths:` entry is identifiable.
+      # raises an *unrecoverable* `RBS::BaseError` (project-vs-bundled duplicates are quarantined per-file
+      # since #777), retrying on every subsequent `env` call would re-parse and re-resolve the whole sig set
+      # per AST node touched during analysis, multiplying per-file analysis cost by ~100x. Failures
+      # short-circuit to `nil` here and are surfaced to the user via `warn_about_env_build_failure_once`.
       def env
         return @state[:env] if @state[:env_loaded]
 
@@ -1778,10 +1886,11 @@ module Rigor
         lines = listed.map { |_path, first_line| "    - #{first_line}" }
         lines << "    … and #{more} more" if more.positive?
         warn(
-          "rigor: skipped #{quarantined.size} unparseable RBS file(s) under `signature_paths:`.\n  " \
-          "They were QUARANTINED so the rest of your RBS env still loads, but the types they\n  " \
-          "declare are absent — calls into them read `Dynamic[top]`, so coverage and diagnostics\n  " \
-          "are reduced. Fix the parse error(s) to restore that coverage:\n" \
+          "rigor: skipped #{quarantined.size} RBS file(s) under `signature_paths:` (unparseable or\n  " \
+          "duplicated against bundled RBS). They were QUARANTINED so the rest of your RBS env\n  " \
+          "still loads, but the types they declare are absent — calls into them read\n  " \
+          "`Dynamic[top]`, so coverage and diagnostics are reduced. Fix the parse error(s) or\n  " \
+          "remove the conflicting declaration(s) to restore that coverage:\n" \
           "#{lines.join("\n")}"
         )
       end
@@ -1870,8 +1979,8 @@ module Rigor
       #
       # {#during_internal_demand} (issue #696) — these two walk EVERY known class, so a failure they hit is a
       # failure of the sig set, not of anything the run asked about, and it must not reach
-      # {#definition_build_failures}. The stderr banner is deliberately left armed here, byte-for-byte as
-      # before.
+      # {#definition_build_failures}. The stderr fallback stays armed, but {#during_internal_demand} folds
+      # every failure found by one outermost walk into one bounded summary (issue #718).
       def instance_definitions_table
         @state[:instance_definitions_table] ||= during_internal_demand do
           build_definitions_table { |name| build_instance_definition(name) }
@@ -2005,7 +2114,9 @@ module Rigor
       # review, second pass).
       #
       # Save-and-restore rather than a bare flag: `#prewarm` wraps a body whose members wrap themselves, and
-      # a nested demand must not un-mark its caller on the way out.
+      # a nested demand must not un-mark its caller on the way out. A successful outermost exit flushes the
+      # deferred stderr summary; an outermost exit that raises keeps the detailed fallback banner armed even
+      # when an earlier internal-demand episode already emitted the loader-instance summary.
       #
       # Per LOADER, not per thread. Nesting and a raise mid-demand are both handled, and the fork pool forks
       # after `#prewarm` returns, so no CLI path shares a loader across concurrent analyses. An in-process
@@ -2013,10 +2124,29 @@ module Rigor
       # silence another's reporting; not reachable today, and not worth a thread-local until it is.
       def during_internal_demand
         previous = @state[:internal_demand]
+        outermost = !previous
+        if outermost
+          @state[:definition_build_deferred_count] = 0
+          @state[:definition_build_deferred_first] = nil
+        end
         @state[:internal_demand] = true
-        yield
-      ensure
-        @state[:internal_demand] = previous
+        # `rescue`/`else` keeps the normal block result precise for the analyzer; the pending marker covers
+        # non-local exits (e.g. `throw`) that unwind through `ensure` without entering either branch.
+        @state[:internal_demand_status] = :pending if outermost
+        begin
+          result = yield
+          @state[:internal_demand_status] = :completed if outermost
+        rescue StandardError, ScriptError => e
+          @state[:internal_demand_status] = :aborted if outermost
+          warn_about_aborted_definition_build_failures if outermost
+          raise e
+        else
+          warn_about_deferred_definition_build_failures if outermost
+          result
+        ensure
+          @state[:internal_demand] = previous
+          warn_about_aborted_definition_build_failures if outermost && @state[:internal_demand_status] == :pending
+        end
       end
 
       # The third twin of {#warn_about_quarantined_signatures} / {#warn_about_virtual_rbs_collisions}: name,
@@ -2029,21 +2159,33 @@ module Rigor
       # {#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).
+      # affected classes even exist. An ordinary demand therefore warns inline at the rescue site; Rigor's
+      # own internal demand defers until its outermost boundary and collapses the whole walk to one summary
+      # (issue #718). Both routes share `@state[:definition_build_warned]` (keyed by normalized class name),
+      # so the instance and singleton sides — and any re-entry once the per-loader-instance definition caches memoize
+      # the failure — count or warn at most once per class name, cache-hit runs included.
+      #
+      # `@state` is per LOADER INSTANCE, not process-global. A fork-pool prewarm finishes before the fork, so
+      # that loader instance emits its summary once in the parent and its dedupe state is inherited by the
+      # workers. A separate loader instance (for example, a parameter-inference pre-pass) has its own summary
+      # budget. A failure first reached by an ordinary demand can still warn once in each worker that reaches
+      # it; 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
+        key = class_name.to_s.delete_prefix("::")
         return if warned[key]
 
         warned[key] = true
+        if @state[:internal_demand]
+          @state[:definition_build_deferred_count] = @state.fetch(:definition_build_deferred_count, 0) + 1
+          @state[:definition_build_deferred_first] ||= [class_name.to_s, error]
+          return
+        end
+
+        warn(definition_build_failure_warning(class_name, error))
+      end
+
+      def definition_build_failure_warning(class_name, error)
         first_line = error.message.to_s.lines.first.to_s.strip
         buffers = definition_build_conflict_buffers(error)
         collisions =
@@ -2056,13 +2198,42 @@ module Rigor
             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: 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
+
+      def warn_about_deferred_definition_build_failures
+        return if @state[:definition_build_summary_warned]
+
+        count = @state[:definition_build_deferred_count]
+        return if count.nil? || count.zero?
+
+        @state[:definition_build_summary_warned] = true
+        first_class, first_error = @state[:definition_build_deferred_first]
+        affected = if count == 1
+                     "1 class affected"
+                   else
+                     more = count - 1
+                     noun = more == 1 ? "class" : "classes"
+                     "… and #{more} more #{noun} affected (#{count} total)"
+                   end
+        warn(
+          "#{definition_build_failure_warning(first_class, first_error)}\n  " \
+          "Internal whole-universe demand found #{affected}; the " \
+          "`rbs.coverage.definition-build-failed` diagnostic reports the classes the analysis demanded and " \
+          "the culprit member and signature files."
         )
       end
 
+      def warn_about_aborted_definition_build_failures
+        count = @state[:definition_build_deferred_count]
+        return if count.nil? || count.zero?
+
+        first_class, first_error = @state[:definition_build_deferred_first]
+        warn(definition_build_failure_warning(first_class, first_error))
+      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

data/lib/rigor/environment.rb

@@ -8,6 +8,7 @@ require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
 require_relative "environment/reporters"
 require_relative "environment/hkt_registry_holder"
+require_relative "environment/failure_slot"
 require_relative "environment/constant_type_cache_holder"
 require_relative "environment/missing_gem_constant_index"
 require_relative "environment/bundle_sig_discovery"
@@ -88,6 +89,10 @@ module Rigor
       # --no-stats` from doing the RBS env build at all.
       @hkt_registry_base = hkt_registry || Inference::HktRegistry::EMPTY
       @hkt_registry_holder = HktRegistryHolder.new
+      # Issue #784 — where either stage of the HKT-registry build (the plugin overlay, #791; the RBS
+      # `type`-alias scan) records a raise, so it surfaces once for the run instead of once per file — or,
+      # for the overlay, instead of aborting the run outright (see {#hkt_registry}).
+      @hkt_scan_failure = FailureSlot.new
       @constant_type_cache = ConstantTypeCacheHolder.new
       # ADR-82 WD9 — `[gem_name, version]` pairs for the locked gems with no resolvable RBS. The
       # root-constant ownership index over them is built lazily (first unresolved constant read) so runs
@@ -104,21 +109,93 @@ module Rigor
     # beat plugin entries, which beat the bundled JSON_VALUE. Memoised; single-threaded use only (under the
     # Ractor pool path each worker has its own Environment so cross-worker mutation is impossible; the LSP
     # single-publish-at-a-time invariant serialises here).
+    #
+    # BOTH stages are guarded (#784, #791): whichever raises is recorded on {#hkt_scan_failure} with the
+    # stage that failed and the other stage still runs, so this getter never raises into its callers —
+    # neither into a file's `analyze_body` rescue nor out of the run-owned demands, which have no rescue
+    # above them at all.
     def hkt_registry
       @hkt_registry_holder.fetch do
-        with_plugin_overlay = if @plugin_registry.respond_to?(:hkt_overlay_registry)
-                                @hkt_registry_base.merge(@plugin_registry.hkt_overlay_registry)
-                              else
-                                @hkt_registry_base
-                              end
-        Inference::HktRegistry.scan_rbs_loader(
-          @rbs_loader,
-          base: with_plugin_overlay,
-          reporter: rbs_extended_reporter
-        )
+        pre_scan = pre_scan_hkt_registry
+        begin
+          Inference::HktRegistry.scan_rbs_loader(
+            @rbs_loader,
+            base: pre_scan,
+            reporter: rbs_extended_reporter
+          )
+        rescue StandardError => e
+          # Issue #784 — the seam. This build is shared and memoised, and it is first demanded from inside
+          # a file's analysis, so a raise here would otherwise land in every file's `analyze_body` rescue
+          # and turn the whole run into N identical `internal analyzer error` rows (issue #776). Record it
+          # and degrade to the pre-scan registry: analysis proceeds, HKT inference from RBS `type` aliases
+          # reads its bound (`Dynamic[top]`, ADR-20 WD2), and the run surfaces ONE
+          # `rbs.coverage.hkt-scan-failed` row. Not a silent skip — the row is `:error` and names the
+          # exception and raise site — and the same shape as `RbsLoader#record_env_build_failure`.
+          # Memoising the degraded registry is what keeps the scan from being re-attempted per file.
+          record_hkt_registry_failure(e, stage: :scan)
+          pre_scan
+        end
       end
     end
 
+    # Issue #791 — the OTHER build behind {#hkt_registry}, and the reason the seam covers two stages
+    # rather than one. Aggregating the loaded plugins' manifest-declared HKT entries runs plugin-authored
+    # code (`Plugin::Registry#hkt_overlay_registry` reads each manifest); before this it sat one line ABOVE
+    # the #784 rescue, so a raise there escaped {#hkt_registry} entirely. Post-#788 that is not a per-file
+    # crash storm but an uncaught abort: {HktRegistryHolder#fetch} memoises only on success, so the raise
+    # is re-attempted at every demand, and the run-owned demands (`Runner::PoolCoordinator#hkt_scan_outcome`
+    # after the file loop, `Analysis::WorkerSession#drain_reporters`) sit outside any rescue.
+    #
+    # The degradation is narrower than the scan's: only the plugin overlay is dropped, and the RBS scan
+    # still runs on top of the bundled base, so a user's own `.rbs` HKT registrations survive a plugin
+    # defect. First-write-wins on the slot means a run whose overlay AND scan both raise reports the
+    # overlay — the actionable one, since the plugin is what a user can remove.
+    #
+    # @return [Rigor::Inference::HktRegistry] the registry the RBS scan is layered on top of.
+    def pre_scan_hkt_registry
+      return @hkt_registry_base unless @plugin_registry.respond_to?(:hkt_overlay_registry)
+
+      @hkt_registry_base.merge(@plugin_registry.hkt_overlay_registry)
+    rescue StandardError => e
+      record_hkt_registry_failure(e, stage: :overlay)
+      @hkt_registry_base
+    end
+    private :pre_scan_hkt_registry
+
+    # Issue #784 — the `[error_class_name, first_message_line, raw_frame_or_nil, stage]` tuple the seam in
+    # {#hkt_registry} recorded, or nil when both stages built (or were never demanded). `stage` is `:scan`
+    # for the RBS `type`-alias scan and `:overlay` for the plugin-manifest aggregation (#791); it decides
+    # the row's wording, because "the implicit HKT scan over RBS `type` aliases raised" would point a user
+    # at their own `.rbs` for a plugin's defect. The run reads the tuple only after demanding
+    # {#hkt_registry} itself — after the file loop on the sequential paths, at drain time in each pool
+    # worker (the coordinator never analyses a file under the pool, so the drain is how its snapshot learns
+    # the outcome: the #696 lesson), and from a resolved environment when the analyze set is empty — so the
+    # row never depends on which files happened to be analysed.
+    #
+    # @return [Array(String, String, String, Symbol), Array(String, String, nil, Symbol), nil]
+    def hkt_scan_failure
+      @hkt_scan_failure.value
+    end
+
+    def record_hkt_registry_failure(error, stage:)
+      frames = error.backtrace || []
+      frame = frames.find { |f| f.include?("/lib/rigor/") } || frames.first
+      # `Class#name` is nil for an anonymous exception class; its nearest NAMED ancestor is the stable
+      # description (`inspect` embeds an object address, which would make the row's text differ across
+      # processes). Each String is frozen individually, not just the Array: the tuple crosses the fork
+      # boundary Marshal-clean and the drain channel's stated invariant
+      # ({Analysis::WorkerSession#drain_reporters}) is that its payload is also `Ractor.shareable?`, which a
+      # shallow freeze over `chomp`'s fresh String would not satisfy.
+      named = error.class.ancestors.find { |a| a.is_a?(Class) && a.name }
+      @hkt_scan_failure.record([
+                                 (error.class.name || "anonymous #{named&.name || 'Exception'}").dup.freeze,
+                                 error.message.to_s.lines.first.to_s.chomp.freeze,
+                                 frame&.dup&.freeze,
+                                 stage
+                               ])
+    end
+    private :record_hkt_registry_failure
+
     # ADR-82 WD9 — the gem name owning `root_constant_name`, when that gem is locked in the project's
     # Gemfile.lock, ships no resolvable RBS, and its entry file declares the constant at top level. Nil for
     # everything else — the caller then keeps the generic provenance cause. The index is built once, lazily,

data/lib/rigor/inference/hkt_registry.rb

@@ -150,7 +150,9 @@ module Rigor
       # loaded RBS env, parse them via {Rigor::RbsExtended::HktDirectives}, and return a new
       # registry that is the union of `base` and every parsed entry. Last-write-wins on URI
       # collisions per {#merge}'s contract. Fail-soft on per-annotation parse errors (the reporter
-      # records an `:info` entry; the other annotations still apply).
+      # records an entry the run surfaces as one `dynamic.rbs-extended.hkt-directive-invalid` `:info`
+      # diagnostic; the other annotations still apply). That claim was false until issue #785: the
+      # production reporter has no `#record`, so every declined directive was dropped silently.
       #
       # @param rbs_loader [Rigor::Environment::RbsLoader]
       # @param base [HktRegistry] starting registry (typically the bundled
@@ -158,8 +160,9 @@ module Rigor
       # @param name_scope [Rigor::Environment::NameScope, nil] threaded through to the bound
       #   resolver for class-name lookups; safe to omit during scanning since hkt bounds are
       #   typically `untyped` or stdlib classes.
-      # @param reporter [#record, nil] same fail-soft reporter contract the other RBS-extended
-      #   parsers use.
+      # @param reporter [Rigor::RbsExtended::Reporter, #record, nil] same fail-soft reporter contract
+      #   the other RBS-extended parsers use; a collecting double that responds only to `#record` /
+      #   `#<<` still works (see {Rigor::RbsExtended::HktDirectives.record_hkt_error}).
 
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
       def self.scan_rbs_loader(rbs_loader, base: EMPTY, name_scope: nil, reporter: nil)
@@ -198,7 +201,16 @@ module Rigor
             params = decl.type_params.map(&:name)
             params_set = params.to_set
 
-            translator = HktSugarTranslator.new(uri: uri, params_set: params_set, name_scope: name_scope)
+            # No rescue around this translate. HktSugarTranslator degrades every alias shape it
+            # cannot model (a non-recursive alias, a malformed self-reference) to a leaf, so a
+            # parseable `type` alias never raises here — that is the fix for issue #776, where an
+            # unknown keyword aborted this shared, memoised build and turned every file into an
+            # `internal analyzer error`. An exception that still reaches this point is an analyzer
+            # bug and MUST propagate rather than silently dropping the alias, matching
+            # RbsLoader#each_known_class_name's fail-soft contract. It propagates to the seam in
+            # `Environment#hkt_registry` (issue #784), which records it and degrades to the pre-scan
+            # registry so it surfaces once per run instead of reaching every file's analysis.
+            translator = HktSugarTranslator.new(uri: uri, params_set: params_set)
             body_tree = translator.translate(decl.type)
 
             next unless translator.recursive