rigortype 0.3.7 → 0.3.9

data/lib/rigor/analysis/reachability/scan_cache.rb

@@ -43,9 +43,9 @@ module Rigor
         RACY_WINDOW_NS = 2_000_000_000
         private_constant :RACY_WINDOW_NS
 
-        # @param cache_path [String, nil] the configuration's cache root; nil or empty is an inert
+        # @param cache_path — the configuration's cache root; nil or empty is an inert
         #   cache (every fetch computes, nothing persists).
-        # @param target_ruby [String, nil] parse-affecting configuration, part of the identity.
+        # @param target_ruby — parse-affecting configuration, part of the identity.
         def self.open(cache_path, target_ruby: nil)
           return new(path: nil, header: nil) if cache_path.nil? || cache_path.to_s.empty?
 

data/lib/rigor/analysis/reachability/signature_scan.rb

@@ -26,8 +26,8 @@ module Rigor
       module SignatureScan
         module_function
 
-        # @param file [String] path to a `.rbs` file.
-        # @return [Array<Scan::Reference>] one file-level reference per distinct referenced name. Empty when the
+        # @param file — path to a `.rbs` file.
+        # @return one file-level reference per distinct referenced name. Empty when the
         #   file cannot be read or parsed — a broken signature is the analyzer's business, not this scan's.
         def call(file)
           _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: file, content: File.read(file)))

data/lib/rigor/analysis/result.rb

@@ -7,7 +7,7 @@ module Rigor
     class Result
       attr_reader :diagnostics, :stats
 
-      # @param stats [Rigor::Analysis::RunStats, nil] end-of-run telemetry (target file count, RBS class
+      # @param stats — end-of-run telemetry (target file count, RBS class
       #   breakdown, wall + RSS) collected by the Runner. Nil when stats collection wasn't requested or wasn't
       #   applicable (early-exit paths like `validate_target_ruby` failure).
       def initialize(diagnostics: [], stats: nil)
@@ -43,8 +43,6 @@ module Rigor
 
       # The diagnostics {#crashed?} answers true for, so a caller can name what it saw rather than only that
       # it saw something.
-      #
-      # @return [Array<Rigor::Analysis::Diagnostic>]
       def crash_diagnostics
         diagnostics.select { |diagnostic| CrashSignature.discards_file_analysis?(diagnostic) }
       end

data/lib/rigor/analysis/rule_catalog.rb

@@ -642,7 +642,10 @@ module Rigor
             "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
             "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
             "Writes live in different classes that happen to share an ivar name.",
-            "Writes are in `def self.foo` (singleton) bodies — those track separately."
+            "Writes are in a singleton body — `def self.foo` or a `class << self` def — those track " \
+            "separately.",
+            "Writes are in a `def` inside an anonymous-class factory block (`Class.new do … end`, " \
+            "`Module.new`, `Struct.new`, `Data.define`): that body defines another class."
           ],
           suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
           severity_authored: :error,

data/lib/rigor/analysis/run_cache_key.rb

@@ -80,7 +80,7 @@ module Rigor
       # collecting project's path-set churn is the same churn, and over-evicting costs one recompute.
       EFFECTS_GENERATION_CAP = GENERATION_CAP
 
-      # @param rbs_config_entries [Array<Cache::Descriptor::ConfigEntry>] the RBS-derived config slots
+      # @param rbs_config_entries — the RBS-derived config slots
       #   (`rbs.libraries` [+ `rbs.virtual_rbs`]). nil on any failure so a malformed key disables the cache.
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)
         Cache::Descriptor.new(

data/lib/rigor/analysis/run_cache_probe.rb

@@ -51,17 +51,15 @@ module Rigor
     #   serves it instead. The decline is measured against the declarations alone, never against what they
     #   would judge to, so it costs one glob and never a wrong answer.
     class RunCacheProbe
-      # @param configuration [Rigor::Configuration]
-      # @param cache_root [String]
-      # @param explain [Boolean] the `--explain` flag (folded into the key, as the runner does).
+      # @param explain — the `--explain` flag (folded into the key, as the runner does).
       def initialize(configuration:, cache_root:, explain:)
         @configuration = configuration
         @cache_root = cache_root
         @explain = explain
       end
 
-      # @param paths [Array<String>] the analysis roots (`@argv` or `configuration.paths`).
-      # @return [Analysis::Result, nil] the cached run result with the severity profile applied and no stats
+      # @param paths — the analysis roots (`@argv` or `configuration.paths`).
+      # @return the cached run result with the severity profile applied and no stats
       #   (matching a cache-served `Runner#run`), or nil to DECLINE — a miss / stale / unavailable cache — so
       #   the caller loads the engine and runs the full path. Any failure declines rather than raising: the
       #   probe must never turn a servable run into a crash.

data/lib/rigor/analysis/runner/buffer_pool_dispatcher.rb

@@ -66,7 +66,7 @@ module Rigor
         # via `RIGOR_LSP_POOL_MIN_BATCH` (mirrors `RIGOR_RACTOR_WORKERS`'s override shape).
         DEFAULT_MIN_BATCH_SIZE = 16
 
-        # @return [Integer] `RIGOR_LSP_POOL_MIN_BATCH` when set to a non-empty value, else
+        # @return `RIGOR_LSP_POOL_MIN_BATCH` when set to a non-empty value, else
         #   {DEFAULT_MIN_BATCH_SIZE}.
         def self.resolve_min_batch_size
           env_value = ENV.fetch("RIGOR_LSP_POOL_MIN_BATCH", nil)
@@ -75,19 +75,17 @@ module Rigor
           Integer(env_value)
         end
 
-        # @param configuration [Rigor::Configuration]
-        # @param cache_store [Rigor::Cache::Store, nil]
-        # @param environment [Rigor::Environment] the warm, shared per-session Environment
+        # @param environment — the warm, shared per-session Environment
         #   (`ProjectContext#environment`) every job's Runner reuses instead of rebuilding.
-        # @param prebuilt [Rigor::Analysis::ProjectScan] the warm, shared pre-pass snapshot
+        # @param prebuilt — the warm, shared pre-pass snapshot
         #   (`ProjectContext#project_scan`) every job's Runner adopts instead of re-scanning.
-        # @param workers [Integer] pool size. `#analyze` degrades to sequential in-process execution — one
+        # @param workers — pool size. `#analyze` degrades to sequential in-process execution — one
         #   job at a time, no `fork` — when fewer than 2 bindings are submitted, fewer than `min_batch_size`
         #   bindings are submitted, `workers` is not positive, `fork` is unavailable on this platform, or
         #   `cache_store` is nil. The middle two are the fork-pool-is-not-worth-it-yet gate documented on
         #   {DEFAULT_MIN_BATCH_SIZE}; the last two mirror
         #   {PoolCoordinator#analyze_files_in_pool}'s own fork-pool preconditions.
-        # @param min_batch_size [Integer] see {DEFAULT_MIN_BATCH_SIZE}. Exposed as a constructor param
+        # @param min_batch_size — see {DEFAULT_MIN_BATCH_SIZE}. Exposed as a constructor param
         #   (rather than read from the env internally) purely for spec control; production callers get the
         #   resolved default.
         def initialize(configuration:, cache_store:, environment:, prebuilt:, workers:,
@@ -185,7 +183,7 @@ module Rigor
           degraded
         end
 
-        # @return [Hash, nil] the child's `{index => diagnostics}` payload, or nil when the child exited
+        # @return the child's `{index => diagnostics}` payload, or nil when the child exited
         #   abnormally or wrote no readable payload. `Marshal.load` is safe here: the blob was written by our
         #   own forked child to a temp file we created.
         def fork_worker_payload(status, out_path)

data/lib/rigor/analysis/runner/declaration_position.rb

@@ -20,8 +20,7 @@ module Rigor
 
         module_function
 
-        # @param finding [#location]
-        # @return [Array(String, Integer)] `[path, line]`
+        # @return `[path, line]`
         def of(finding)
           location = finding.location
           return [CONFIG_PATH, 1] if location.nil?

data/lib/rigor/analysis/runner/diagnostic_aggregator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../crash_signature"
 require_relative "../diagnostic"
 require_relative "../severity_stamp"
 
@@ -21,31 +22,36 @@ module Rigor
       # end-of-pass snapshots) is read through injected reader procs so this collaborator never calls back
       # into the {Runner} and the read happens at the exact point in the run the original inline read did.
       class DiagnosticAggregator # rubocop:disable Metrics/ClassLength
-        # @param configuration [Rigor::Configuration]
-        # @param rbs_extended_reporter [RbsExtended::Reporter]
-        # @param boundary_cross_reporter [DependencySourceInference::BoundaryCrossReporter]
-        # @param source_rbs_synthesis_reporter [Plugin::SourceRbsSynthesisReporter]
-        # @param plugin_registry [#call] reader returning the current {Plugin::Registry} (varies per run).
-        # @param dependency_source_index [#call] reader returning the current
+        # @param plugin_registry — reader returning the current {Plugin::Registry} (varies per run).
+        # @param dependency_source_index — reader returning the current
         #   {DependencySourceInference::Index}.
-        # @param pool_mode [#call] reader returning the pool-mode flag.
-        # @param cached_plugin_prepare_diagnostics [#call] reader returning the prepare-diagnostic snapshot.
-        # @param pre_eval_diagnostics_from_scanner [#call] reader returning the pre-eval scanner diagnostics.
-        # @param synthesized_namespaces_snapshot [#call] reader.
-        # @param quarantined_signatures_snapshot [#call] reader returning the `signature_paths:` files skipped
+        # @param pool_mode — reader returning the pool-mode flag.
+        # @param cached_plugin_prepare_diagnostics — reader returning the prepare-diagnostic snapshot.
+        # @param pre_eval_diagnostics_from_scanner — reader returning the pre-eval scanner diagnostics.
+        # @param synthesized_namespaces_snapshot — reader.
+        # @param quarantined_signatures_snapshot — reader returning the `signature_paths:` files skipped
         #   because they do not parse (`[path, first_error_line]` pairs).
-        # @param env_build_failure_snapshot [#call] reader returning the total RBS env-build failure tuple
+        # @param signature_standdowns_snapshot — reader returning the plugin-contributed signature files
+        #   that stood down against a colliding generic arity (#610), as
+        #   `[path, class_name, existing_arity, incoming_arity, existing_file]` tuples. Defaults to none so
+        #   a caller that snapshots nothing of the kind need not say so.
+        # @param env_build_failure_snapshot — reader returning the total RBS env-build failure tuple
         #   (`[error_class, first_error_line, conflicting_buffer_names]`) or nil when the env built.
-        # @param definition_build_failures_snapshot [#call] issue #696 — reader returning the per-class
+        # @param definition_build_failures_snapshot — issue #696 — reader returning the per-class
         #   `RBS::DefinitionBuilder` failures the run observed, as `[class_name, error_class, member,
         #   conflicting_buffer_names]` tuples. Empty for a healthy sig set.
-        # @param conformance_results_snapshot [#call] reader.
+        # @param hkt_scan_failure_snapshot — issue #784 — reader returning the `[error_class_name,
+        #   first_message_line, raw_frame_or_nil, stage]` tuple whichever stage of the HKT-registry build
+        #   raised, or nil when both built (or were never demanded). `stage` is `:scan` (the RBS `type`-alias
+        #   scan) or `:overlay` (the plugin-manifest aggregation, #791), and picks the row's wording.
+        # @param conformance_results_snapshot — reader.
         def initialize(configuration:, rbs_extended_reporter:, boundary_cross_reporter:, # rubocop:disable Metrics/ParameterLists
                        source_rbs_synthesis_reporter:, plugin_registry:, dependency_source_index:,
                        pool_mode:, cached_plugin_prepare_diagnostics:,
                        pre_eval_diagnostics_from_scanner:, synthesized_namespaces_snapshot:,
                        quarantined_signatures_snapshot:, env_build_failure_snapshot:,
-                       definition_build_failures_snapshot:, conformance_results_snapshot:)
+                       definition_build_failures_snapshot:, hkt_scan_failure_snapshot:,
+                       conformance_results_snapshot:, signature_standdowns_snapshot: -> { [] })
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -57,8 +63,10 @@ module Rigor
           @pre_eval_diagnostics_from_scanner_reader = pre_eval_diagnostics_from_scanner
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
+          @signature_standdowns_snapshot_reader = signature_standdowns_snapshot
           @env_build_failure_snapshot_reader = env_build_failure_snapshot
           @definition_build_failures_snapshot_reader = definition_build_failures_snapshot
+          @hkt_scan_failure_snapshot_reader = hkt_scan_failure_snapshot
           @conformance_results_snapshot_reader = conformance_results_snapshot
         end
 
@@ -315,9 +323,11 @@ module Rigor
         # user knows their sig set is malformed (`rbs validate` rejects it) and can fix it at the source.
         # Authored `:info`: the analysis already succeeded; this is advisory, never a gate. Empty for a
         # well-formed sig set.
-        # An unparseable `.rbs` under `signature_paths:` is QUARANTINED so the rest of the env survives
-        # (PR #50), which means the types it declares are silently absent — calls into them read
-        # `Dynamic[top]`, and the run gets *quieter*, not louder. The stderr banner alone never reached CI:
+        # An unparseable or declaration-colliding `.rbs` under `signature_paths:` is QUARANTINED so the
+        # rest of the env survives (PR #50; issue #777 extends this to class-vs-module / constant
+        # collisions against bundled RBS), which means the types it declares are silently absent — calls
+        # into them read `Dynamic[top]`, and the run gets *quieter*, not louder. The stderr banner alone
+        # never reached CI:
         # it is not a diagnostic, so it is absent from `--format json` / SARIF / GitHub annotations / the LSP
         # and cannot move the exit code. This puts it in the diagnostic stream where every channel sees it.
         #
@@ -381,6 +391,25 @@ module Rigor
           [build_rbs_definition_build_failed_diagnostic(failures)]
         end
 
+        # Issue #784 — the fourth rung, narrowest consequence: one of the two builds behind
+        # `Environment#hkt_registry` raised instead of building. The `:scan` stage is the implicit HKT scan
+        # over RBS `type` aliases (ADR-20 WD2's `%a{rigor:v1:hkt_register / hkt_define}` overlay AND any
+        # recursive `type` alias in the project's own `.rbs` or an installed `rbs collection`); analysis
+        # proceeds over the PRE-scan registry — bundled builtins (`json::value`, …) plus the plugin overlay
+        # — so a `type` alias that would have registered as a type constructor reads its bound
+        # (`Dynamic[top]`) instead. The `:overlay` stage (#791) is the plugin-manifest aggregation, which
+        # sat ABOVE the seam until the run-owned demands made a raise there abort the run; it degrades one
+        # step further in and one step narrower — the plugin entries are dropped, the `.rbs` scan still
+        # runs. Either way everything else this run reports is unaffected: no class loses its method
+        # surface, no signature file is skipped, the environment builds. That is why this sits LAST on the
+        # ladder, after its two `rbs.coverage.*` siblings above.
+        def rbs_hkt_scan_failed_diagnostics
+          failure = hkt_scan_failure_snapshot
+          return [] if failure.nil?
+
+          [build_rbs_hkt_scan_failed_diagnostic(failure)]
+        end
+
         def rbs_synthesized_namespace_diagnostics
           synthesized = synthesized_namespaces_snapshot
           return [] if synthesized.nil? || synthesized.empty?
@@ -388,6 +417,26 @@ module Rigor
           [build_rbs_synthesized_namespace_diagnostic(synthesized)]
         end
 
+        # Issue #610 — the outcome that AVOIDED `rbs.coverage.definition-build-failed`'s rung: a signature
+        # file a loaded plugin contributes re-declared a class another loaded source (typically an `rbs
+        # collection install`) already declares at a DIFFERENT generic arity, so the plugin's file stood
+        # down rather than fail the class's definition build. One `:info` per file: the user is told what
+        # typing they are not getting and why, and — unlike the quarantine row this file used to be
+        # misreported as — is not sent to remove a declaration the plugin owns.
+        def rbs_plugin_signature_stood_down_diagnostics
+          standdowns = signature_standdowns_snapshot
+          return [] if standdowns.nil? || standdowns.empty?
+
+          standdowns.map { |entry| build_rbs_plugin_signature_stood_down_diagnostic(entry) }
+        end
+
+        # The two `:info` notices that close the `rbs.coverage.*` ladder, in this order: the namespace
+        # synthesis first, then the stand-down (#610) — the outcome that AVOIDED a definition-build failure
+        # and so the quietest row on it. One method so the runner's assembly reads them as one slot.
+        def rbs_coverage_notice_diagnostics
+          rbs_synthesized_namespace_diagnostics + rbs_plugin_signature_stood_down_diagnostics
+        end
+
         # Maps the per-run `rigor:v1:conforms-to` scan results into diagnostics (spec: `rbs-extended.md` §
         # "Explicit conformance directive"). A class that declares `conforms-to _Interface` but is missing
         # a required interface method surfaces as `rbs_extended.unsatisfied-conformance`; an unresolvable
@@ -408,16 +457,28 @@ module Rigor
           when RbsExtended::ConformanceChecker::IncompatibleSignature
             build_incompatible_signature_diagnostic(record)
           else # UnresolvedInterface
-            build_reporter_diagnostic(
-              record.location,
-              rule: "dynamic.rbs-extended.unresolved",
-              message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
-                       "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
-                       "the `sig`/library that declares it to the RBS load path."
-            )
+            build_unresolved_conformance_diagnostic(record)
           end
         end
 
+        # Issue #928 — `:warning`, not the `:info` the other `dynamic.rbs-extended.unresolved` producers
+        # stamp. Those report that an inference fell back; this one reports that an assertion the author
+        # deliberately wrote is checking NOTHING, and the whole point of `conforms-to` is to be checked. It
+        # is not unsolicited either: only a project that wrote the directive can see it. Now that the
+        # capability-role catalog ships, the remaining way to reach this row is a name that does not exist.
+        def build_unresolved_conformance_diagnostic(record)
+          path, line, column = location_fields(record.location)
+          Diagnostic.new(
+            path: path, line: line, column: column,
+            message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
+                     "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
+                     "the `sig`/library that declares it to the RBS load path.",
+            severity: :warning,
+            rule: "dynamic.rbs-extended.unresolved",
+            source_family: :builtin
+          )
+        end
+
         def build_unsatisfied_conformance_diagnostic(record)
           path, line, column = location_fields(record.location)
           Diagnostic.new(
@@ -458,11 +519,12 @@ module Rigor
             path: ".rigor.yml",
             line: 1,
             column: 1,
-            message: "#{quarantined.size} RBS file(s) under `signature_paths:` do not parse and were " \
-                     "SKIPPED: #{sample.join(', ')}#{suffix}. The rest of your RBS environment still " \
-                     "loaded, but the types those files declare are absent — calls into them read " \
-                     "`Dynamic[top]`, so this run is quieter than it should be, not cleaner. Fix the " \
-                     "parse error(s) (`rbs validate`) to restore that coverage.",
+            message: "#{quarantined.size} RBS file(s) under `signature_paths:` were SKIPPED " \
+                     "(unparseable, or duplicated against bundled RBS): #{sample.join(', ')}#{suffix}. " \
+                     "The rest of your RBS environment still loaded, but the types those files declare " \
+                     "are absent — calls into them read `Dynamic[top]`, so this run is quieter than it " \
+                     "should be, not cleaner. Fix the parse error(s) or remove the conflicting " \
+                     "declaration(s) (`rbs validate`) to restore that coverage.",
             severity: :warning,
             rule: "rbs.coverage.quarantined-signature",
             source_family: :builtin
@@ -515,14 +577,27 @@ module Rigor
                      "#{first_failure_clause(failures.first)}#{conflicting_files_clause(files, sample_size)} " \
                      "Rigor still treats each class as KNOWN, so calls into it — real methods and typos " \
                      "alike — silently read `Dynamic[top]` instead of resolving, and this run is quieter " \
-                     "than it should be rather than cleaner. Two signature sources declare the same " \
-                     "member; remove the duplicate declaration (`rbs validate`) to restore type coverage.",
+                     "than it should be rather than cleaner. #{definition_build_advice(failures.first)}",
             severity: :warning,
             rule: "rbs.coverage.definition-build-failed",
             source_family: :builtin
           )
         end
 
+        # The closing advice follows the FIRST failure's error class: `GenericParameterMismatchError` is two
+        # declarations of one CLASS at different generic arity (#610), and "remove the duplicate member"
+        # sends its reader after a member that does not exist.
+        def definition_build_advice(failure)
+          _, error_class, = failure
+          if error_class.to_s.end_with?("GenericParameterMismatchError")
+            "Two signature sources declare the class with a different number of type parameters; make " \
+              "the declarations agree (`rbs validate`) to restore type coverage."
+          else
+            "Two signature sources declare the same member; remove the duplicate declaration " \
+              "(`rbs validate`) to restore type coverage."
+          end
+        end
+
         # `[class_name, error_class, member, buffers]`. The member is nil for the error classes that carry no
         # name at all (`RecursiveAncestorError`), and the clause then names the error class alone rather than
         # inventing a member.
@@ -550,6 +625,66 @@ module Rigor
           "#{sample.join(', ')}#{suffix}"
         end
 
+        # Issue #784 — one `:error` row per run, unlike its two `:warning` `rbs.coverage.*` siblings above.
+        # Those two are typically a collision between the user's OWN `sig/` and Rigor's bundled RBS, so an
+        # `:error` default would let a Rigor release turn a green project red with zero user change (ADR-5
+        # / AGENTS.md § FP discipline) — the reason both stay `:warning` by default. This row has no such
+        # neighbour: post-#783 the scan itself raising is an ANALYZER defect, never something a user's
+        # `sig/` could trigger on its own, so there is no green project this could newly redden. And the
+        # run was already non-zero before this row existed — issue #784's seam is what stopped the raise
+        # from reaching every file as N identical `internal analyzer error` rows in the first place, and
+        # THAT per-file rescue is what `Result#success?` was already reading as a failure; this row only
+        # makes the reason legible.
+        #
+        # One row per RUN, not per file: the scan is one build over the whole `signature_paths:` overlay
+        # (memoised — see {Environment#hkt_registry}), so every file that would have demanded it hit the
+        # exact same failure, and a row per file would say the same thing N times.
+        #
+        # `:rbs_build` (via {CrashSignature::RBS_BUILD_FAILURE_RULES}), not `:check_rule`: the analysis ran
+        # to completion over a DEGRADED type universe — every rule still fired, unlike `:check_rule`'s
+        # whole-file replacement — so a consumer gating on {CrashSignature.discards_file_analysis?} must
+        # keep reading this run's diagnostics rather than refuse it as a crash.
+        def build_rbs_hkt_scan_failed_diagnostic(failure)
+          error_class, first_line, frame, stage = failure
+          relative_frame = CrashSignature.relativize_frame(frame)
+          frame_clause = relative_frame ? " at #{relative_frame}" : ""
+          raised = "(#{error_class}): #{first_line}#{frame_clause}."
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: stage == :overlay ? hkt_overlay_failed_message(raised) : hkt_scan_failed_message(raised),
+            severity: :error,
+            rule: "rbs.coverage.hkt-scan-failed",
+            source_family: :builtin
+          )
+        end
+
+        def hkt_scan_failed_message(raised)
+          "The implicit HKT scan over RBS `type` aliases raised #{raised} Rigor fell back to the bundled " \
+            "and plugin HKT registrations, so a recursive `type` alias in your `.rbs` or an installed " \
+            "`rbs collection` no longer registers as a type constructor and reads its bound " \
+            "(`Dynamic[top]`) instead — this run is quieter than it should be, not cleaner. " \
+            "This is an analyzer defect, not a problem with your signatures; please report it " \
+            "with the message above."
+        end
+
+        # Issue #791 — the overlay stage of the same build, worded for the plugin it came from. The scan
+        # wording would send a user to their `.rbs` for a defect that is not there: what failed is the
+        # aggregation of the loaded plugins' manifest-declared HKT entries, and the message names the
+        # plugin whenever the raise was attributable to one (`Plugin::Registry#hkt_overlay_registry` puts
+        # the id in the message it re-raises). The degradation is narrower than the scan's, so the fallback
+        # sentence differs too: only the plugin entries are missing, and the user's own `.rbs` scan still
+        # ran on top of the bundled registrations.
+        def hkt_overlay_failed_message(raised)
+          "Building the plugin HKT overlay raised #{raised} Rigor skipped every plugin-declared HKT " \
+            "registration and analysed with the bundled ones plus your own `.rbs` overlay, so a type " \
+            "constructor a plugin declares reads its bound (`Dynamic[top]`) instead — this run is " \
+            "quieter than it should be, not cleaner. This is a defect in the named plugin or in Rigor, " \
+            "not a problem with your signatures; report it with the message above, or remove the plugin " \
+            "from `plugins:` to analyse without it."
+        end
+
         # The absolute path is what the loader records; the user thinks in project-relative terms.
         def relative_signature_path(path)
           root = "#{Dir.pwd}#{File::SEPARATOR}"
@@ -576,6 +711,42 @@ module Rigor
           )
         end
 
+        def build_rbs_plugin_signature_stood_down_diagnostic(entry)
+          path, class_name, existing_arity, incoming_arity, existing_file = entry
+          displaced_by = displacing_source_phrase(existing_file)
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "`#{relative_signature_path(path.to_s)}` (a signature file a plugin contributes) declares " \
+                     "`#{class_name.to_s.delete_prefix('::')}` with #{type_parameter_phrase(incoming_arity)}, " \
+                     "but #{displaced_by} already declares it with #{type_parameter_phrase(existing_arity)}. " \
+                     "Two declarations of one class at different generic arity fail its definition build, so " \
+                     "the plugin's file stood down: calls into the class resolve against the other " \
+                     "declaration, and the plugin's element typing for it is unavailable while both are " \
+                     "loaded. Expected when a bundled plugin and an `rbs collection install` both declare " \
+                     "the class; nothing to fix unless you want the plugin's typing back, which needs the " \
+                     "other source to stop declaring the class.",
+            severity: :info,
+            rule: "rbs.coverage.plugin-signature-stood-down",
+            source_family: :builtin
+          )
+        end
+
+        def displacing_source_phrase(existing_file)
+          return "another loaded signature source" if existing_file.nil?
+
+          "`#{relative_signature_path(existing_file.to_s)}`"
+        end
+
+        def type_parameter_phrase(arity)
+          case arity
+          when nil, 0 then "no type parameters"
+          when 1 then "1 type parameter"
+          else "#{arity} type parameters"
+          end
+        end
+
         def build_rbs_coverage_missing_diagnostic(missing)
           sample_size = 5
           sample = missing.first(sample_size).map(&:gem_name)
@@ -603,16 +774,19 @@ module Rigor
         #   enable.
         # - `dynamic.shape.lossy-projection` for every shape-projection type function (`pick_of`, …) applied
         #   to a carrier that loses precision (anything other than `HashShape` / `Tuple`).
+        # - `dynamic.rbs-extended.hkt-directive-invalid` for every malformed ADR-20 `rigor:v1:hkt_register` /
+        #   `rigor:v1:hkt_define` the directive parser declined (issue #785).
         #
-        # Both are authored `:info`; the severity profile re-stamps them per project taste. Path / line /
-        # column come from the annotation's `RBS::Location` when available, falling back to
-        # `.rigor.yml`-style file-level attribution otherwise.
+        # All three are authored `:info`; the severity profile re-stamps them per project taste. Every stream
+        # carries its `(path, line, column)` already flattened off the annotation's `RBS::Location`, because
+        # all three cross the pool drain channel (see {RbsExtended::Reporter}); an entry with no position
+        # falls back to `.rigor.yml`-style file-level attribution.
         def rbs_extended_reporter_diagnostics
           return [] if @rbs_extended_reporter.empty?
 
           unresolved = @rbs_extended_reporter.unresolved_payloads.map do |entry|
-            build_reporter_diagnostic(
-              entry.source_location,
+            build_positioned_reporter_diagnostic(
+              entry,
               rule: "dynamic.rbs-extended.unresolved",
               message: "`RBS::Extended` directive payload could not be resolved: " \
                        "#{entry.payload.inspect}. Check for typos or enable a plugin " \
@@ -621,8 +795,8 @@ module Rigor
           end
 
           lossy = @rbs_extended_reporter.lossy_projections.map do |entry|
-            build_reporter_diagnostic(
-              entry.source_location,
+            build_positioned_reporter_diagnostic(
+              entry,
               rule: "dynamic.shape.lossy-projection",
               message: "Shape projection `#{entry.head}` applied to a carrier without a " \
                        "literal shape; the projection degrades to the input type. Author " \
@@ -630,7 +804,37 @@ module Rigor
             )
           end
 
-          unresolved + lossy
+          unresolved + lossy + hkt_directive_diagnostics + deprecated_form_diagnostics
+        end
+
+        # ADR-109 WD3 — one row per annotation still written in a spelling the grammar accepts but no
+        # longer displays. The row names the replacement because the deprecation window exists for exactly
+        # this edit, and it stays `:info`: the annotation resolved, the run is as green as it was.
+        def deprecated_form_diagnostics
+          @rbs_extended_reporter.deprecated_forms.map do |entry|
+            build_positioned_reporter_diagnostic(
+              entry,
+              rule: "dynamic.rbs-extended.deprecated-form",
+              message: "`#{entry.payload}` is a deprecated spelling; write `#{entry.replacement}`. The " \
+                       "angle-bracket integer range is accepted for one deprecation window and removed " \
+                       "at the next compatibility break (ADR-109)."
+            )
+          end
+        end
+
+        # Issue #785 — one row per declined HKT directive. The consequence sentence is the point: the parser
+        # is fail-soft, so nothing else in the run tells the author that the constructor they registered is
+        # not there and that every `App[…]` naming it silently reads its bound.
+        def hkt_directive_diagnostics
+          @rbs_extended_reporter.hkt_directive_errors.map do |entry|
+            build_positioned_reporter_diagnostic(
+              entry,
+              rule: "dynamic.rbs-extended.hkt-directive-invalid",
+              message: "`RBS::Extended` HKT directive was declined: #{entry.message}. The type " \
+                       "constructor stays unregistered, so an `App[...]` carrier naming it reads " \
+                       "its bound (`Dynamic[top]`) instead of the type function."
+            )
+          end
         end
 
         # ADR-32 WD6 — drains the per-run {Plugin::SourceRbsSynthesisReporter} into
@@ -704,6 +908,56 @@ module Rigor
           end
         end
 
+        # Issue #959 — surfaces the {Plugin::IoBoundary} refusal history each loaded plugin accumulated over
+        # the whole run (prepare AND every per-file call: `#io_boundary` is memoised per plugin instance, so
+        # one boundary sees both). `TrustPolicy#allow_read?` stays `File.expand_path`-only per ADR-2 — a
+        # project rooted under a symlink (macOS' `/tmp` → `/private/tmp` is the common case) can have every
+        # plugin read fall outside its own read roots with nothing said about it. One `:info` row per plugin
+        # that hit this, never one per path, naming the count and the first path so the row stays legible on
+        # a plugin that walked a whole out-of-scope subtree.
+        #
+        # Positioned here, in `#pre_file_diagnostics`'s post-analysis sibling list (called from
+        # `Runner#assemble_run_diagnostics`, which only runs on an ADR-45 cache MISS): the refusal history is
+        # a function of the plugin code and the resolved paths for THIS configuration, so it is deterministic
+        # across runs of the same inputs and the row that lands in a miss's cached diagnostics blob is the
+        # row a later warm HIT correctly re-serves — the same regeneration contract every other stream
+        # aggregated in `#pre_file_diagnostics` / `#assemble_run_diagnostics` already relies on (see
+        # `docs/type-specification/diagnostic-policy.md` § "Run-level rows and the record-and-validate
+        # cache"). It is also never routed through `IncrementalSession`'s per-file cache (`#788`): that cache
+        # holds only `Runner#per_file_diagnostics`, and this row is not part of that stream.
+        #
+        # Scope: `plugin_registry` here is the coordinator-side registry, which only actually RUNS `#prepare`
+        # / per-file analysis in sequential mode (`--workers` unset, the default) — a pooled run (`--workers
+        # N`) prepares and analyses on per-worker `WorkerSession` registries this reader never sees, so a
+        # refusal confined to a pooled worker's slice is not reported. Left out deliberately: draining it
+        # needs a fourth marshalled channel beside `drain_reporters` / `drain_dependencies` / `drain_effects`
+        # in `Runner::PoolCoordinator`, and the default (unpooled) path already covers the reported bug.
+        def plugin_trust_refusal_diagnostics
+          return [] if plugin_registry.empty?
+
+          plugin_registry.plugins.filter_map { |plugin| plugin_trust_refusal_diagnostic(plugin) }
+        end
+
+        def plugin_trust_refusal_diagnostic(plugin)
+          summary = plugin.io_boundary.refusal_summary
+          return nil if summary.nil?
+
+          plugin_id = plugin.manifest.id
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "plugin #{plugin_id.inspect} had #{summary[:count]} read(s) refused by the trust " \
+                     "policy; first refused path: #{summary[:first_path].inspect}, outside read root " \
+                     "#{summary[:nearest_root].inspect}. Spell the path the way that read root spells it " \
+                     "(a symlink alias such as macOS' /tmp does not match its real path), or add a " \
+                     "`plugins_io.allowed_paths:` entry in .rigor.yml covering the path.",
+            severity: :info,
+            rule: "plugin_trust.read-refused",
+            source_family: :builtin
+          )
+        rescue StandardError
+          nil
+        end
+
         def build_reporter_diagnostic(source_location, rule:, message:)
           path, line, column = location_fields(source_location)
           Diagnostic.new(
@@ -712,6 +966,20 @@ module Rigor
           )
         end
 
+        # The {RbsExtended::Reporter} form of the builder above: its three streams carry the position as
+        # `(path, line, column)` primitives rather than as the `RBS::Location` a conformance record holds,
+        # because they cross the pool drain channel (#785, #805). A missing component falls back exactly as
+        # {#location_fields} does for a missing location.
+        def build_positioned_reporter_diagnostic(entry, rule:, message:)
+          path = entry.path.to_s
+          Diagnostic.new(
+            path: path.empty? ? ".rigor.yml" : path,
+            line: entry.line || 1,
+            column: entry.column || 1,
+            message: message, severity: :info, rule: rule, source_family: :builtin
+          )
+        end
+
         def location_fields(source_location)
           return [".rigor.yml", 1, 1] if source_location.nil?
 
@@ -768,6 +1036,10 @@ module Rigor
           @quarantined_signatures_snapshot_reader.call
         end
 
+        def signature_standdowns_snapshot
+          @signature_standdowns_snapshot_reader.call
+        end
+
         def env_build_failure_snapshot
           @env_build_failure_snapshot_reader.call
         end
@@ -776,6 +1048,10 @@ module Rigor
           @definition_build_failures_snapshot_reader.call
         end
 
+        def hkt_scan_failure_snapshot
+          @hkt_scan_failure_snapshot_reader.call
+        end
+
         def conformance_results_snapshot
           @conformance_results_snapshot_reader.call
         end