rigortype 0.3.8 → 0.4.0

data/lib/rigor/plugin/template_unit.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Rigor
+  module Plugin
+    # One **template unit** — a non-Ruby source file a plugin compiled into Ruby, handed to the engine to
+    # be parsed and typed like a file (ADR-16 Tier D, revived by #392 as this seam; design note
+    # `docs/design/20260816-effect-labels.md` § 11.3).
+    #
+    # ADR-16's Tier D declared `external_files:` — "files evaluated as if their body were pasted at a
+    # declared call site, with `self` typed as a declared class" — and ADR-60 WD1 removed it for want of a
+    # consumer. What Tier D lacked, and what this carries, is a **source transform with a line map** ahead
+    # of parsing: the file on disk is not Ruby, so the engine analyses `ruby_source` and reports at the
+    # template's own lines.
+    #
+    # A unit is pure data. The plugin's transform runs ONCE, on the parent, before any analysis; nothing
+    # here is a callable, so the unit survives `Marshal` into a fork-pool worker exactly as the macro
+    # substrate's value objects do.
+    #
+    # - `logical_name` — the name the unit is keyed by, independent of the handler: `users/show.html`, not
+    #   `users/show.html.erb`. Becomes the `view:<logical_name>` effect-unit key, so an ERB → Haml rewrite
+    #   is not a rename.
+    # - `path` — the template file as the user wrote it. Every diagnostic and every source trace names it.
+    # - `ruby_source` — the compiled Ruby the engine parses.
+    # - `line_map` — `{ ruby_source line => template line }`, 1-based. A line the map does not mention
+    #   anchors at the nearest mapped line before it, and at line 1 when there is none. **An EMPTY map is
+    #   the identity, not "no positions"**: every compiled line reports at its own number and the columns
+    #   pass through untouched. That is correct only for a transform that emits nothing the template did
+    #   not contain — a transform that prepends so much as one preamble line and omits the map reports
+    #   every finding off by that many lines. Omit it only for a byte-preserving transform.
+    # - `self_type` — the fully-qualified class the body's `self` is typed as, or nil for a bare body.
+    # - `locals` — `{ name => type name }`, the parameters the render site passes.
+    # - `ivar_seeds` — `{ "@name" => type name }`, the assigns the rendering action set.
+    # - `transform_id` — the compiler's identity (`"erubi-1.13"`). Joins the unit digest, so re-compiling
+    #   with a different compiler re-analyses. Defaults to the declaring plugin's `id@version`.
+    #
+    # - `suppressed_rules` — rule-id PREFIXES the engine drops for this unit's diagnostics (#393). The
+    #   per-unit rule posture: a compiled template is not code the user wrote, and a plugin that knows its
+    #   compiler's idioms is the only party that can say which families of finding are meaningful there.
+    #   `["call."]` is what an ERB plugin declares while the synthesised receivers are still coarse — the
+    #   unit still contributes its EFFECTS, which is what the view layer is analysed for first, without
+    #   the typing half costing the project a diagnostic per line. Empty means "report everything", which
+    #   is what a plugin whose synthesis it trusts should declare.
+    #
+    # A type name that resolves to nothing is not an error here: the engine falls back to `Dynamic`, which
+    # taints honestly rather than fabricating a type the plugin could not justify (ADR-5).
+    class TemplateUnit
+      # Bumped whenever the engine changes what it synthesises from a unit — the seeding rules, the
+      # scope binding, the effect-unit key spelling. It rides the unit digest, so a change here
+      # invalidates every cached run that analysed a unit, exactly as a changed transform does.
+      SYNTHESIS_VERSION = 2
+
+      # The prefix an effect-unit key carries for a template unit. Deliberately not a {Effects::MethodKey}
+      # shape: a view has no owner class and no selector, and spelling one would put a method in the
+      # snapshot that no call site can name.
+      KEY_PREFIX = "view:"
+
+      IVAR_NAME = /\A@[A-Za-z_][A-Za-z0-9_]*\z/
+      private_constant :IVAR_NAME
+
+      LOCAL_NAME = /\A[a-z_][A-Za-z0-9_]*\z/
+      private_constant :LOCAL_NAME
+
+      # A rule prefix is a dotted family (`call.`) or a whole rule id (`call.undefined-method`); the match
+      # is `String#start_with?`, so the former covers the latter. A bare `""` would suppress the unit
+      # entirely and is refused.
+      RULE_PREFIX = /\A[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*\.?\z/
+      private_constant :RULE_PREFIX
+
+      attr_reader :logical_name, :path, :ruby_source, :line_map, :self_type, :locals, :ivar_seeds,
+                  :transform_id, :suppressed_rules
+
+      # Every field is one declared property of the unit; grouping them behind a context object would only
+      # move the same list into a second value class.
+      def initialize(logical_name:, path:, ruby_source:, line_map: {}, self_type: nil, locals: {}, # rubocop:disable Metrics/ParameterLists
+                     ivar_seeds: {}, transform_id: nil, suppressed_rules: [])
+        @logical_name = validate_string!("logical_name", logical_name)
+        @path = validate_string!("path", path)
+        @ruby_source = validate_source!(ruby_source)
+        @line_map = validate_line_map!(line_map)
+        @self_type = self_type.nil? ? nil : validate_string!("self_type", self_type)
+        @locals = validate_bindings!("locals", locals, LOCAL_NAME)
+        @ivar_seeds = validate_bindings!("ivar_seeds", ivar_seeds, IVAR_NAME)
+        @transform_id = transform_id.nil? ? nil : validate_string!("transform_id", transform_id)
+        @suppressed_rules = validate_rule_prefixes!(suppressed_rules)
+        freeze
+      end
+
+      # The effect-unit key and the snapshot key: `view:users/show.html`.
+      def unit_key
+        "#{KEY_PREFIX}#{@logical_name}"
+      end
+
+      # The unit's cache identity — **source bytes + transform id + synthesis version**, the triple
+      # `docs/internal-spec/cache.md` § computed-value keys asks a synthesised input to carry. The
+      # template's own bytes are deliberately NOT in it: the engine analyses `ruby_source`, and two
+      # templates that compile to the same Ruby have the same answer.
+      #
+      # @param fallback_transform_id — the declaring plugin's `id@version`, used when the unit
+      #   named no transform of its own.
+      def digest(fallback_transform_id = nil)
+        Digest::SHA256.hexdigest(
+          [
+            "source:#{@ruby_source}",
+            "transform:#{@transform_id || fallback_transform_id || 'unknown'}",
+            "suppressed:#{@suppressed_rules.join(',')}",
+            "synthesis:#{SYNTHESIS_VERSION}"
+          ].join("\x00")
+        )
+      end
+
+      # The template line a `ruby_source` line reports at. Falls back to the nearest mapped line before it
+      # — a synthesised prologue or a buffer-append the compiler emitted between two template lines still
+      # points into the template rather than past its end — and to line 1 when the map says nothing at all.
+      def template_line(ruby_line)
+        return ruby_line if @line_map.empty?
+        return @line_map[ruby_line] if @line_map.key?(ruby_line)
+
+        before = @line_map.keys.select { |line| line < ruby_line }
+        before.empty? ? 1 : @line_map[before.max]
+      end
+
+      def to_h
+        {
+          "logical_name" => @logical_name, "path" => @path, "ruby_source" => @ruby_source,
+          "line_map" => @line_map, "self_type" => @self_type, "locals" => @locals,
+          "ivar_seeds" => @ivar_seeds, "transform_id" => @transform_id,
+          "suppressed_rules" => @suppressed_rules
+        }
+      end
+
+      def ==(other)
+        other.is_a?(TemplateUnit) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      private
+
+      def validate_string!(field, value)
+        text = value.to_s
+        raise ArgumentError, "TemplateUnit #{field} must be a non-empty String" if text.empty?
+
+        text.dup.freeze
+      end
+
+      def validate_source!(value)
+        raise ArgumentError, "TemplateUnit ruby_source must be a String" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      # 1-based on both sides. A zero or negative line is a compiler bug the engine would turn into a
+      # diagnostic positioned off the top of the file, so it is refused at construction.
+      def validate_line_map!(value)
+        raise ArgumentError, "TemplateUnit line_map must be a Hash" unless value.is_a?(Hash)
+
+        value.to_h do |from, to|
+          unless from.is_a?(Integer) && to.is_a?(Integer) && from.positive? && to.positive?
+            raise ArgumentError, "TemplateUnit line_map must map positive Integer to positive Integer"
+          end
+
+          [from, to]
+        end.freeze
+      end
+
+      def validate_rule_prefixes!(value)
+        raise ArgumentError, "TemplateUnit suppressed_rules must be an Array" unless value.is_a?(Array)
+
+        value.map do |prefix|
+          text = prefix.to_s
+          unless text.match?(RULE_PREFIX)
+            raise ArgumentError, "TemplateUnit suppressed_rules entry #{text.inspect} is malformed"
+          end
+
+          text.dup.freeze
+        end.uniq.freeze
+      end
+
+      def validate_bindings!(field, value, pattern)
+        raise ArgumentError, "TemplateUnit #{field} must be a Hash" unless value.is_a?(Hash)
+
+        value.to_h do |name, type_name|
+          key = name.to_s
+          raise ArgumentError, "TemplateUnit #{field} key #{key.inspect} is malformed" unless key.match?(pattern)
+
+          [key.dup.freeze, validate_string!("#{field} value", type_name)]
+        end.freeze
+      end
+    end
+  end
+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.rb

@@ -2,6 +2,7 @@
 
 require_relative "plugin/type_node_resolver"
 require_relative "plugin/macro"
+require_relative "plugin/template_unit"
 require_relative "plugin/manifest"
 require_relative "plugin/access_denied_error"
 require_relative "plugin/trust_policy"

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