rigortype 0.3.8 → 0.3.9

data/lib/rigor/plugin/registry.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "blueprint"
+# Issue #806 — {Registry#guarded_manifest} constructs one. `Rigor::Plugin::LoadError` MUST be defined by
+# then: an unresolved bare `LoadError` in this lexical scope silently falls back to Ruby's own ::LoadError.
+require_relative "load_error"
 
 module Rigor
   module Plugin
@@ -217,23 +220,26 @@ module Rigor
     class Registry
       attr_reader :plugins, :load_errors, :blueprints, :contribution_index, :resolved_gem_paths
 
-      # @param plugins [Array<Rigor::Plugin::Base>] instantiated plugin instances in deterministic order.
-      # @param load_errors [Array<Rigor::Plugin::LoadError>] failures surfaced during loading. Each error is
+      # @param plugins — instantiated plugin instances in deterministic order.
+      # @param load_errors — failures surfaced during loading. Each error is
       #   also turned into a diagnostic by the runner.
-      # @param blueprints [Array<Rigor::Plugin::Blueprint>] frozen, Ractor-shareable replay descriptors
+      # @param blueprints — frozen, Ractor-shareable replay descriptors
       #   aligned 1:1 with `plugins`. The loader fills this in; callers that construct Registry manually MAY
       #   pass `[]` and accept that {.materialize} cannot replay the set.
-      # @param resolved_gem_paths [Hash{String=>String,nil}] #194 slice 1 — `gem name => resolved file path`
+      # @param resolved_gem_paths — #194 slice 1 — `gem name => resolved file path`
       #   for each successfully required plugin gem, so `rigor plugins` can print where a loaded (and
       #   possibly frozen) plugin actually loaded from. Defaults to empty; a worker registry built by
       #   {.materialize} carries none (the provenance surface runs only on the coordinator).
       def initialize(plugins: [], load_errors: [], blueprints: [], resolved_gem_paths: {})
         @plugins = plugins.dup.freeze
-        @load_errors = load_errors.dup.freeze
         @blueprints = blueprints.dup.freeze
         @resolved_gem_paths = resolved_gem_paths.dup.freeze
         @contribution_index = ContributionIndex.new(@plugins)
-        compile_aggregates
+        # Issue #806 — every manifest the construction-time aggregates need is read ONCE here, behind a
+        # per-plugin rescue, and a plugin that raises joins `load_errors` instead of taking the run down.
+        manifest_errors = []
+        compile_aggregates(@plugins.map { |plugin| guarded_manifest(plugin, manifest_errors) })
+        @load_errors = (load_errors + manifest_errors).freeze
         # ADR-52 WD4 — the single engine-owned node-rule walk, compiled once per run from the node-rule
         # plugin subset (registry order). The runner reuses it for every file; it builds fresh per-file
         # state internally, so it is safe to freeze and share.
@@ -306,9 +312,14 @@ module Rigor
       # in plugin registration order. `Environment#build_name_scope` builds a `TypeNode::ResolverChain` from
       # this list (environment.rb). The first non-nil `#resolve(node, scope)` return wins per ADR-13 WD3 /
       # WD5 — registration order is the user's lever.
-      def type_node_resolvers
-        plugins.flat_map { |plugin| plugin.manifest.type_node_resolvers }
-      end
+      #
+      # Issue #806 — compiled at construction alongside its `compile_aggregates` siblings, and for a second
+      # reason beyond theirs: `Environment#build_name_scope` demands it during Environment CONSTRUCTION, so
+      # the previous per-call `plugin.manifest` read had no rescue above it anywhere — a plugin raising here
+      # aborted every `Environment.for_project`, i.e. the whole run, before any seam could record it. The
+      # guard has to sit at registry construction because that is the last point at which a failure can still
+      # join `load_errors` (the registry freezes immediately after).
+      attr_reader :type_node_resolvers
 
       # ADR-20 slice 6 — aggregate every loaded plugin's manifest-declared HKT registrations + definitions
       # into a single `Inference::HktRegistry` overlay that `Environment#hkt_registry` merges on top of the
@@ -419,10 +430,14 @@ module Rigor
       # compiled once at construction (the registry is frozen, so the flat_map-on-every-call versions
       # re-derived an invariant). `@contracts_by_path` is a mutable per-path memo inside the frozen registry
       # — safe because the contract set and the glob semantics are fixed for the lifetime of the run.
-      def compile_aggregates
-        @additional_initializers = @plugins.flat_map { |p| safe_manifest(p)&.additional_initializers || [] }.freeze
-        @open_receivers = @plugins.flat_map { |p| (safe_manifest(p)&.open_receivers || []).map(&:to_s) }.uniq.freeze
+      #
+      # @param manifests — one entry per plugin, positionally aligned with `@plugins`;
+      #   nil where {#guarded_manifest} caught a raising manifest read.
+      def compile_aggregates(manifests)
+        @additional_initializers = manifests.flat_map { |m| m&.additional_initializers || [] }.freeze
+        @open_receivers = manifests.flat_map { |m| (m&.open_receivers || []).map(&:to_s) }.uniq.freeze
         @open_receivers_set = @open_receivers.to_set.freeze
+        @type_node_resolvers = manifests.flat_map { |m| m&.type_node_resolvers || [] }.freeze
         @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
         @contracts_by_path = {}
         @effect_memo = {}
@@ -466,6 +481,21 @@ module Rigor
         nil
       end
 
+      # Issue #806 — {#safe_manifest} with a receipt. The construction-time aggregates degraded silently
+      # when a manifest read raised, so a plugin that contributed nothing looked identical to a plugin that
+      # was never asked; the load-error channel is where "a plugin could not be loaded" already lives, and
+      # `Analysis::Runner` turns each entry into one `plugin_loader.load-error` row naming the plugin. The
+      # plugin ref is the CLASS, not `manifest.id`: the manifest is the surface that just failed.
+      def guarded_manifest(plugin, errors)
+        plugin.manifest
+      rescue StandardError => e
+        errors << LoadError.new(
+          "plugin #{plugin.class} raised while reading its manifest: #{e.class}: #{e.message}",
+          plugin_ref: plugin.class.to_s, cause: e
+        )
+        nil
+      end
+
       def safe_protocol_contracts(plugin)
         plugin.protocol_contracts || []
       rescue StandardError

data/lib/rigor/plugin/source_rbs_synthesis_reporter.rb

@@ -25,15 +25,26 @@ module Rigor
 
       def initialize
         @entries = []
+        @seen = {}
       end
 
+      # Identical entries are collapsed. Each becomes one `:info` row, and two rows saying the same thing
+      # about the same file carry nothing the first does not: the synthesizer's own per-file notices are
+      # already `uniq`, but a worker pool re-runs the whole env build in EVERY worker over the same project
+      # file list and then drains each worker's stream into this one reporter, so without the dedup a
+      # `--workers N` run printed N copies of a row a `--workers=0` run printed once. The same collapse the
+      # {RbsExtended::Reporter} drain documents, for the same reason.
       def record(plugin_id:, path:, message:, kind: :failed)
-        @entries << Entry.new(
+        entry = Entry.new(
           plugin_id: plugin_id.to_s.dup.freeze,
           path: path.to_s.dup.freeze,
           message: message.to_s.dup.freeze,
           kind: kind
         )
+        return nil if @seen.key?(entry)
+
+        @seen[entry] = true
+        @entries << entry
         nil
       end
 

data/lib/rigor/plugin/trust_policy.rb

@@ -45,8 +45,7 @@ module Rigor
         freeze
       end
 
-      # @param path [String]
-      # @return [Boolean] true when the absolute path falls inside any allowed read root. Symlinks are
+      # @return true when the absolute path falls inside any allowed read root. Symlinks are
       #   resolved through `File.expand_path` only (no `realpath`); plugins with adversarial intent are out of
       #   scope per ADR-2.
       def allow_read?(path)
@@ -58,8 +57,7 @@ module Rigor
         @network_policy != :disabled
       end
 
-      # @param url [String, URI]
-      # @return [Boolean] true when the URL scheme is `https` and the parsed hostname is in
+      # @return true when the URL scheme is `https` and the parsed hostname is in
       #   `allowed_url_hosts`. Always `false` while `network_policy` is `:disabled`.
       def allow_url?(url)
         return false if @network_policy == :disabled

data/lib/rigor/plugin/type_node_resolver.rb

@@ -28,11 +28,11 @@ module Rigor
     # Resolvers SHOULD be stateless and re-entrant; the registry builds the chain once per
     # `Analysis::Runner.run` and may consult any resolver multiple times for the same node.
     class TypeNodeResolver
-      # @param node [Rigor::TypeNode::Identifier, Rigor::TypeNode::Generic] the parser-emitted node the chain is
+      # @param node — the parser-emitted node the chain is
       #   asking about.
-      # @param scope [Rigor::TypeNode::NameScope] companion value object (slice 3); slice 2 invocations MAY pass
+      # @param scope — companion value object (slice 3); slice 2 invocations MAY pass
       #   `nil` because the chain doesn't exist yet.
-      # @return [Rigor::Type::Base, nil] resolved type, or `nil` to fall through.
+      # @return resolved type, or `nil` to fall through.
       def resolve(node, scope) # rubocop:disable Lint/UnusedMethodArgument
         nil
       end

data/lib/rigor/plugin_gap_advisory.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "plugin/bundled_catalog"
+require_relative "environment/lockfile_resolver"
+
+module Rigor
+  # ADR-96 WD2 — the plugin-gap advisory: a gem the project itself depends on that a bundled plugin declares
+  # in `target_gems:`, with that plugin absent from `plugins:`.
+  #
+  # One home for a fact that ADR-96 found in four hand-maintained copies, none of which was the plugin.
+  # `rigor doctor` and `rigor skill describe`'s project probe both route through here, so the two can no
+  # longer disagree — they were byte-identical Rails tables by luck, not by construction.
+  #
+  # The advisory is deliberately advice, not activation: naming a plugin never loads it (ADR-96 Criterion 2),
+  # and declining a plugin is a legitimate choice, which is why a gap is a warning and never a failure.
+  module PluginGapAdvisory
+    # One unenabled plugin and the depended-on gems that make it relevant.
+    Gap = Data.define(:plugin_gem, :plugin_id, :locked_gems)
+
+    # A gem whose whole point is to pull its constituents in. A Rails application's `Gemfile` says `rails`
+    # and never `activerecord`, so a direct-dependency match alone would silence the entire Rails family for
+    # the projects the advisory exists for. The table is explicit rather than derived: expanding whatever a
+    # gem happens to resolve to is the transitive read this advisory is here to avoid, and the set of gems
+    # that are genuinely umbrellas is small and known.
+    UMBRELLA_GEMS = {
+      "rails" => %w[
+        actioncable actionmailer actionpack actiontext actionview activejob activemodel
+        activerecord activestorage activesupport railties
+      ].freeze
+    }.freeze
+
+    class << self
+      # @param project_root — the directory whose `Gemfile.lock` and `plugins:` list are read.
+      # @param plugins — the configuration's raw `plugins:` entries (String or Hash form).
+      # @return the gaps, sorted by plugin gem name; empty when the project declares no dependency.
+      def gaps(project_root:, plugins:)
+        depended = depended_gems(project_root)
+        return [] if depended.empty?
+
+        listed = listed_plugin_names(plugins)
+        Plugin::BundledCatalog.entries.filter_map do |entry|
+          next if listed?(entry, listed)
+
+          matched = entry.target_gems.select { |gem| depended.include?(gem) }
+          next if matched.empty?
+
+          Gap.new(plugin_gem: entry.gem_name, plugin_id: entry.plugin_id, locked_gems: matched.freeze)
+        end.sort_by(&:plugin_gem)
+      end
+
+      # Whether the project enables no bundled plugin at all for the gems it depends on — ADR-96's preserved
+      # `:fail` case, generalised off the Rails-only table it replaces. A project that enables *some* of the
+      # matching plugins has made choices; one that enables none of them is unconfigured for its own stack.
+      def unconfigured?(project_root:, plugins:)
+        found = gaps(project_root: project_root, plugins: plugins)
+        return false if found.empty?
+
+        listed = listed_plugin_names(plugins)
+        Plugin::BundledCatalog.entries.none? { |entry| listed?(entry, listed) }
+      end
+
+      private
+
+      # The gems the project chose, which is the `DEPENDENCIES` section and never the resolved graph. A
+      # transitive `minitest` / `i18n` / `ffi` is somebody else's dependency, and advising on it fires on
+      # correct configuration — including, through {unconfigured?}, as a hard failure.
+      def depended_gems(project_root)
+        direct = Environment::LockfileResolver.direct_dependency_names(
+          lockfile_path: nil, project_root: project_root
+        )
+        return direct if direct.empty?
+
+        direct + direct.flat_map { |gem| UMBRELLA_GEMS.fetch(gem, []) }
+      end
+
+      # Both spellings a `plugins:` entry may use for the same plugin — the gem name and the manifest id.
+      # An `enabled: false` entry still counts as naming it: the user has demonstrably found the plugin, so
+      # advising them to add what is already there would be worse than staying quiet.
+      def listed_plugin_names(plugins)
+        Array(plugins).flat_map do |raw|
+          case raw
+          when String then [raw]
+          when Hash
+            keyed = raw.to_h { |key, value| [key.to_s, value] }
+            [keyed["gem"], keyed["id"]].compact.map(&:to_s)
+          else []
+          end
+        end.to_set
+      end
+
+      def listed?(entry, listed)
+        listed.include?(entry.gem_name) || listed.include?(entry.plugin_id)
+      end
+    end
+  end
+end

data/lib/rigor/project_environment.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "environment"
+require_relative "plugin"
+require_relative "plugin/loader"
+require_relative "plugin/services"
+require_relative "reflection"
+require_relative "type/combinator"
+
+module Rigor
+  # Shared construction of the project environment for every command that types against the project WITHOUT
+  # driving a full {Analysis::Runner}: the single-shot probes (`type-of`, `type-scan`, `trace`, `annotate`) and
+  # the `sig-gen` generator / observation collector. Each of these answers "what does the engine see here?" for
+  # a hand-picked file, position or class, so the type universe they read MUST match the one `rigor check`
+  # analyses against — otherwise the command reports, or declines to emit, against a universe the real run never
+  # had.
+  #
+  # Two gaps this closes, both the same shape:
+  #
+  # - The probes historically built their environment with `Environment.for_project(libraries:,
+  #   signature_paths:)` only — no plugin registry, no `source_files:`. The `source_rbs_synthesizer` plugin hook
+  #   (ADR-32 / ADR-93's auto-wired `rigor-rbs-inline`) therefore never ran there, so a class whose only
+  #   signature comes from an inline `#: () -> void` annotation typed as `Dynamic[top]` under a probe while
+  #   `check` resolved it through the synthesized RBS. That divergence misattributed a dispatch tier during the
+  #   #162 transitive-void design pass (see the 2026-07-19 addendum in
+  #   docs/adr/100-static-diagnostic-family-and-void-origins.md).
+  # - Neither the probes nor `sig-gen` passed the dependency-discovery axes — the `rbs collection` lockfile, the
+  #   bundle's per-gem `sig/`, the Gemfile.lock gating them — that `check` reads straight off the same
+  #   configuration. On a Rails project with `rbs collection install` run, `sig-gen` therefore could not see
+  #   `ActiveRecord::Base` at all, and its superclass-without-RBS skip guard declined to emit every model
+  #   (issue #821). The advice the guard prints — install the collection — had no effect, because the command
+  #   never looked at it.
+  #
+  # {.dependency_discovery_options} is the single spelling of those axes; `Runner`'s build path
+  # (`Analysis::Runner::PoolCoordinator#build_runner_environment`), the worker session and the LSP project
+  # context read it too, so a new axis cannot be added to `check` and silently missed here.
+  #
+  # A non-`check` command legitimately simplifies in two places: no synthesis-failure reporter (there is no
+  # diagnostic pipeline) and no synthesis cache store (a single-position probe recomputes cheaply). Plugin
+  # loading itself matches check — same `.rigor.yml` `plugins:` config, same ADR-93 auto-wire (already applied
+  # by `Configuration.load`), same `enabled:` / `require_magic_comment` semantics via `Plugin::Loader.load`.
+  #
+  # Fail-soft is the invariant: a project with no plugins, an unresolvable plugin gem, or any error during the
+  # plugin-aware build degrades — never crashes. `Plugin::Loader` already isolates per-entry load failures onto
+  # the registry; the `rescue` here is the belt-and-suspenders around anything the loader or the plugin-aware
+  # env build itself might raise.
+  module ProjectEnvironment
+    module_function
+
+    # Builds the plugin-aware, dependency-aware {Rigor::Environment} a non-`check` command works against.
+    #
+    # @param configuration — the loaded project configuration (already carries the
+    #   ADR-93 auto-wired `rigor-rbs-inline` entry when the library is resolvable).
+    # @param source_files — the file(s) the command inspects. Threaded so each loaded plugin's
+    #   `source_rbs_synthesizer` runs over them at env-build time; an empty list contributes no synthesized RBS.
+    def build(configuration:, source_files:)
+      Environment.for_project(
+        libraries: configuration.libraries,
+        signature_paths: configuration.signature_paths,
+        plugin_registry: load_plugin_registry(configuration),
+        source_files: source_files,
+        **dependency_discovery_options(configuration)
+      )
+    rescue StandardError
+      bare(configuration)
+    end
+
+    # The dependency-discovery axes `check` reads off the configuration, as a keyword hash. Extracted so the
+    # list lives in one place: every command that types against the project's real dependencies passes exactly
+    # these, and adding an axis to `Environment.for_project` means adding it here once.
+    def dependency_discovery_options(configuration)
+      {
+        bundler_bundle_path: configuration.bundler_bundle_path,
+        bundler_auto_detect: configuration.bundler_auto_detect,
+        bundler_lockfile: configuration.bundler_lockfile,
+        rbs_collection_lockfile: configuration.rbs_collection_lockfile,
+        rbs_collection_auto_detect: configuration.rbs_collection_auto_detect
+      }
+    end
+
+    # Loads the project's configured plugins the same way the plugin-inspection commands (`rigor plugins`,
+    # `rigor doctor`) do: a `Plugin::Services` with no cache store (these commands recompute) driving
+    # `Plugin::Loader.load`. Returns `nil` — so `Environment.for_project` skips the plugin tier entirely — when
+    # the project declares no plugins.
+    def load_plugin_registry(configuration)
+      return nil if configuration.plugins.empty?
+
+      services = Plugin::Services.new(
+        reflection: Reflection,
+        type: Type::Combinator,
+        configuration: configuration,
+        cache_store: nil
+      )
+      registry = Plugin::Loader.load(configuration: configuration, services: services)
+      run_plugin_prepare(registry)
+      registry
+    end
+
+    # `Analysis::WorkerSession#run_plugin_prepare` runs every plugin's `#prepare(services)` before the real
+    # `check` pipeline reads `services.fact_store` — an ADR-9 fact published there (#921's `:factory_index`,
+    # `rigor-activerecord`'s `:model_index`, …) is otherwise invisible. The probe commands built on
+    # {ProjectEnvironment} share the same plugin registry and the same `read_fact` call sites, so they need
+    # the same step; skipping it made every cross-plugin fact silently read nil under `type-of` / `annotate`
+    # / `trace` / `sig-gen` even once a plugin published it correctly. Per-plugin `rescue` keeps one plugin's
+    # `#prepare` failure from costing the rest — the probes have no diagnostic pipeline to report it through,
+    # so it is swallowed the same way the rest of this module fails soft.
+    def run_plugin_prepare(registry)
+      return if registry.nil? || registry.empty?
+
+      registry.plugins.each do |plugin|
+        plugin.prepare(plugin.services)
+      rescue StandardError
+        next
+      end
+    end
+
+    # The first fail-soft floor: no plugin tier and no synthesized RBS, but still the project's own dependency
+    # sources — dropping those is what issue #821 was, so a plugin-loading failure must not cost them.
+    def bare(configuration)
+      Environment.for_project(
+        libraries: configuration.libraries,
+        signature_paths: configuration.signature_paths,
+        **dependency_discovery_options(configuration)
+      )
+    rescue StandardError
+      minimal(configuration)
+    end
+
+    # The last floor: RBS core plus the project's own signature paths, which cannot fail on anything outside
+    # the project itself.
+    def minimal(configuration)
+      Environment.for_project(
+        libraries: configuration.libraries,
+        signature_paths: configuration.signature_paths
+      )
+    end
+  end
+end

data/lib/rigor/protection/analysis_guard.rb

@@ -10,7 +10,24 @@ module Rigor
     # A named class, not a bare RuntimeError: {MutationScanner#classify} already folds a per-mutant
     # `StandardError` into the `:harness_error` bucket, and the scanner's file-level rescue must catch THIS
     # and nothing else, so the two failure modes stay distinguishable at every site that handles either.
-    class AnalyzerCrashed < StandardError; end
+    #
+    # Issue #790 — it says WHICH of the two refusals below fired, because they want different recovery. A
+    # crashed check rule left the Environment as it found it; an analyzer defect (the #784 HKT registry
+    # build) recorded itself ON that Environment and is memoised there, so the caller that owns the
+    # Environment has to replace it before the next mutant is scored. {#analyzer_defect?} is how a caller
+    # tells the two apart without re-deriving the classification from the message it was handed.
+    class AnalyzerCrashed < StandardError
+      def initialize(message = nil, analyzer_defect: false)
+        super(message)
+        @analyzer_defect = analyzer_defect
+      end
+
+      # True when the refusal was an analyzer defect rather than a crashed check rule — the shape whose
+      # cause outlives the run that observed it.
+      def analyzer_defect?
+        @analyzer_defect
+      end
+    end
 
     # The kill oracles' guard against judging a mutant by a run that never happened.
     #
@@ -27,34 +44,96 @@ module Rigor
     # let {MutationScanner} put the mutant in the `harness_errors` bucket (#264), which is already excluded
     # from `killed + survived` and already surfaced by the CLI. A crash then READS as a crash.
     #
-    # Only {Analysis::Result#crashed?} is armed — the check-rule rescue, the one shape that REPLACES a
-    # file's whole diagnostic list. Refusing more than that is the same error pointed the other way, and it
+    # Two shapes are armed, and only two.
+    #
+    # {Analysis::Result#crashed?} — the check-rule rescue, the one shape that REPLACES a file's whole
+    # diagnostic list. Refusing more than the shapes below is the same error pointed the other way, and it
     # was measured: on a project whose plugin `prepare` raises, refusing the `:plugin` row took a file from
     # `killed=1 survived=6` to `killed=0 survived=0 harness_errors=7` — the builtin rules had run, their
     # diagnostics were all present, and a real measurement was thrown away. `invoke_plugin_prepare` appends
     # its row to every sequential run, so arming it would have refused every run for the life of the
-    # process. `:rbs_build` is excluded for the same reason plus one more: the site filter that admits
-    # mutations already drops receivers whose type did not resolve, so a class whose definition failed to
-    # build contributes no measured sites to begin with.
+    # process. The user-caused `:rbs_build` rungs are excluded for the same reason plus one more: the site
+    # filter that admits mutations already drops receivers whose type did not resolve, so a class whose
+    # definition failed to build contributes no measured sites to begin with.
+    #
+    # {Analysis::CrashSignature.analyzer_defect?} (issue #790) — the one `:rbs_build` rung whose cause is
+    # Rigor rather than the user's `sig/`: post-#788 a mutant that makes the implicit HKT scan raise no
+    # longer produces a per-file `internal analyzer error` but ONE readable `rbs.coverage.hkt-scan-failed`
+    # row, so `Result#crashed?` stays false and the mutant was scored as a measurement over a silently
+    # degraded universe — issue #776 was exactly such a mutant. The run is readable (every rule fired), so
+    # it stays out of `#crashed?`, which answers the user-facing "may I read these diagnostics?"; what this
+    # guard asks is the narrower "is this a valid measurement OF RIGOR?", and it is not.
+    #
+    # The refusal is asked off {Analysis::CrashSignature} rather than off a second string match here, so a
+    # reworded row or a fourth rung added to `ANALYZER_DEFECT_RULES` cannot disarm one copy and leave the
+    # others armed (#696).
+    #
+    # The defect half is asked TWICE, of two surfaces, because each covers the other's blind spot. The row
+    # is severity-stamped like every other diagnostic, so `severity_overrides:` resolving `rbs` (or the
+    # exact rule id) to `off` drops it from the run entirely — and a harness that exists to find analyzer
+    # defects must not be the one thing a project's config can hide one from. {Rigor::Environment} records
+    # the failure BEFORE any severity resolution, so `#hkt_scan_failure` still answers. Conversely that slot
+    # only ever describes THIS process's Environment: under the fork pool the defect happens in a worker's
+    # own Environment and reaches the parent as the row alone.
     module AnalysisGuard
       module_function
 
-      # Takes the whole {Analysis::Result} rather than its diagnostics so the question is asked through
-      # {Analysis::Result#crashed?} — the same predicate the spec-side guard reads, off the same
+      # Takes the whole {Analysis::Result} rather than its diagnostics so the crash question is asked
+      # through {Analysis::Result#crashed?} — the same predicate the spec-side guard reads, off the same
       # {Analysis::CrashSignature} table. Hands back the diagnostics, which is all a kill comparison wants.
       #
-      # @param result [Rigor::Analysis::Result] one analysis run.
-      # @param context [String] which oracle call produced it, so the raise points at the right seam.
-      # @return [Array<Rigor::Analysis::Diagnostic>] the run's diagnostics, when the run was healthy.
-      # @raise [AnalyzerCrashed]
-      def checked(result, context:)
-        return result.diagnostics unless result.crashed?
+      # @param result — one analysis run.
+      # @param context — which oracle call produced it, so the raise points at the right seam.
+      # @param environment — the Environment the run was made over, read for the pre-severity record of a
+      #   shared-build failure. Optional: a caller that has none loses only the severity-override case.
+      # @return the run's diagnostics, when the run was healthy.
+      # @raise AnalyzerCrashed
+      def checked(result, context:, environment: nil)
+        refuse_crash(result, context) if result.crashed?
+        defect = result.diagnostics.find { |diagnostic| Analysis::CrashSignature.analyzer_defect?(diagnostic) }
+        refuse_defect(context, Analysis::CrashSignature.describe(defect)) if defect
 
+        failure = shared_build_failure(environment)
+        refuse_defect(context, failure) if failure
+
+        result.diagnostics
+      end
+
+      # The pre-severity record, described the way {Analysis::CrashSignature.describe} describes a row, so
+      # the two refusals read alike whichever surface saw the defect.
+      def shared_build_failure(environment)
+        return nil unless environment.respond_to?(:hkt_scan_failure)
+
+        failure = environment.hkt_scan_failure
+        return nil if failure.nil?
+
+        error_class, message, frame, stage = failure
+        "#{stage} HKT registry build raised #{error_class}: #{message}#{" at #{frame}" if frame}"
+      end
+      private_class_method :shared_build_failure
+
+      def refuse_crash(result, context)
         raise AnalyzerCrashed,
               "#{context}: the analyzer crashed, so this run's diagnostics say nothing about the code " \
               "(#{Analysis::CrashSignature.describe(result.crash_diagnostics.first)}). A kill comparison " \
               "against it would score the mutant a survivor it was never measured against. See issue #686."
       end
+      private_class_method :refuse_crash
+
+      # The run is readable, so the message says what is wrong with it instead: the universe it was produced
+      # over is missing the type constructors the RBS `type` aliases and the loaded plugins would have
+      # contributed, and the BASELINE this mutant is compared against carries the identical degradation — so
+      # the set difference is empty for a reason that has nothing to do with the mutation.
+      def refuse_defect(context, description)
+        refusal = AnalyzerCrashed.new(
+          "#{context}: the analyzer degraded its own type universe, so this run is readable but is not a " \
+          "measurement of Rigor (#{description}). Scoring a mutant against it reports the analyzer's own " \
+          "defect as the mutant's survival. See issue #790.",
+          analyzer_defect: true
+        )
+        raise refusal
+      end
+      private_class_method :refuse_defect
     end
   end
 end