rigortype 0.3.7 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e6c542d01ee79f9cb65e22a91aa5a87cd9dd43a842ffc815b94ded244fe9cc0
-  data.tar.gz: 2a4cf5b015559a12d1ede16f414d9884df09aab01ce0bc61da0b1d683b1e11a0
+  metadata.gz: 30b66e3d183999cbd85557c5af6b770ac78bf82507a2e587e5878c1a411b4326
+  data.tar.gz: 2c3cee80d75ea9769d7b965dd84ac60eb4af89c27fc63d3ec35a1cdce3b45338
 SHA512:
-  metadata.gz: '032268117a2430a52a7f8505196c8f5e6760cd29551aa95af5c3fe55185450d569d21f97a6379281951b6ef01b34a30522178f25701dfbed8ff680c6a6c80eaa'
-  data.tar.gz: d39c177c2c8d9a9b255a1e60ffcbc3c101a8d9e63fb6213bb846d47ae13dcdd0e37acd366055b6ede65836939ac12b026b43c9b03b0774de60f52a2e09de2890
+  metadata.gz: 9986a78b908e05fd017f772b0c26d6bc3d654e665cbf59d85cdf0176b76735403d644238ca7072268f9e47ba3937073002de47a308deda6cab77311459f6f008
+  data.tar.gz: 66df68005471dc8df33c9a1881659644fca80c4e406830b7ab9c1fe5b641e3872d13a70ab39cccdf66fba3d256e46026ab13963a70a76be1362ac86b8e823f1d

data/README.md

@@ -231,7 +231,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.3.7`** (2026-09-05) — on the
+Current release: **`v0.3.8`** (2026-09-08) — on the
 `0.3.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a

data/docs/handbook/11-sig-gen.md

@@ -95,10 +95,13 @@ states:
 
 The `sig.skipped.*` reasons are:
 
-- `sig.skipped.complex-shape` — the method has optional, rest,
-  keyword, block, or forwarding parameters. The MVP's
-  body-typing path only handles required positional
-  parameters; complex shapes need a future slice.
+- `sig.skipped.complex-shape` — reserved for a parameter
+  shape the renderer cannot spell. Every shape a `def` can
+  declare renders today (optional, rest, trailing, keyword,
+  keyword-rest, `...` forwarding, `&block`), so the
+  generator does not produce this reason; it stayed
+  reserved when the gate that used to fire it for every
+  such method was retired (#778).
 - `sig.skipped.untyped-return` — the method body's last
   expression types as `Dynamic[top]`. Emitting `untyped` as
   a tightening would be noise rather than help.
@@ -119,16 +122,25 @@ The `sig.skipped.*` reasons are:
 The three `sig.generated.*` identifiers
 (`sig.generated.new-file` / `new-method` / `tighter-return`)
 are emitted as JSON fields under `--format=json` so CI
-gating consumers can route them.
+gating consumers can route them. Every `skipped` row is part
+of the same payload, carrying its `sig.skipped.*` identifier
+as `skip_reason`, so a method missing from your `sig/` has
+its reason next to the rows that did emit. In text mode a
+one-line stderr summary counts the skipped methods per
+reason instead; stdout stays paste-clean.
 
 ## What method shapes the generator covers
 
 Slice-by-slice (each shipped via a CHANGELOG entry — this
 list is the current state):
 
-- **Plain instance `def foo`** with required positional
-  parameters. Both new-method and tighter-return paths
-  apply.
+- **Plain instance `def foo`** of any parameter shape:
+  required, optional, rest, trailing, keyword, keyword-rest,
+  `...` forwarding and `&block`. The parameter list mirrors
+  the runtime shape with `untyped` in every position (the
+  observed union under `--params=observed`), and a block
+  renders as `?{ (*untyped) -> untyped }`. Both new-method
+  and tighter-return paths apply.
 - **Singleton-side `def self.foo`** and
   `class << self; def foo; end`. Rendered as
   `def self.foo: ...`; matched against
@@ -143,10 +155,8 @@ list is the current state):
   are recognised as user-authored and never produce a
   duplicate `def` insertion.
 
-Method shapes the generator does **not** cover yet (and
-silently skips):
+Method shapes the generator does **not** cover yet:
 
-- Optional / rest / keyword / block / forwarding parameters.
 - `define_method(:name) { ... }`.
 - Methods whose body types as `Dynamic[top]` (the body
   inference cannot prove a useful return type).
@@ -303,9 +313,9 @@ inference, not a separate analysis.
 
 ## Limits today
 
-- Methods with optional / rest / keyword / block /
-  forwarding parameters silently skip
-  (`sig.skipped.complex-shape`).
+- A block parameter always renders as the lenient
+  `?{ (*untyped) -> untyped }`; a typed block signature
+  waits on the engine tracking yield shapes end-to-end.
 - `define_method` and `Data.define`-specific emission are
   deferred follow-ups (`Data.define`-derived readers come
   through if a method body exists).

data/docs/manual/02-cli-reference.md

@@ -475,6 +475,13 @@ exits `1`: you asked for a write and did not get one. Such a skip
 is a bug in Rigor's RBS rendering, not in your code — please
 report it.
 
+A method the generator declined for any other reason (a body
+that proves only `untyped`, a user-authored declaration it will
+not overwrite) is never a silent absence: under `--format=json`
+it is a `skipped` row of the `candidates` array with its
+`sig.skipped.*` identifier in `skip_reason`, and in text mode a
+one-line stderr summary counts the skipped methods per reason.
+
 ## `rigor lsp`
 
 Run the Language Server over stdio. See

data/docs/manual/04-diagnostics.md

@@ -74,7 +74,7 @@ carries no `documentation_url`.
 | <a id="rule-effect-envelope-exceeded"></a>`effect.envelope-exceeded` | A method performs an effect its declared envelope does not admit — its proven effect labels (its own body plus everything it calls) are not covered by the `%a{pure}` or `%a{rigor:v1:effect …}` bound written on it or on its class. Opt-in twice over: it needs an `effects:` block in `.rigor.yml` and an envelope you wrote. Positioned at the Ruby `def`. Unproven ("and possibly more") effects never fire, and `mutate.local` is tolerated by every envelope. | high |
 | <a id="rule-effect-liskov-widened"></a>`effect.liskov-widened` | An override escapes the envelope written on the method it overrides. A `PgRepo` is usable wherever a `Repo` is, so a `%a{rigor:v1:effect io.db}` on `Repo#find` binds `PgRepo#find` too: an implementation may be purer than the bound it inherits, never less pure. Either what the override *does* exceeds the inherited bound, or the envelope the override *declares for itself* is wider than it. Both sides must be authored — nothing fires unless someone wrote an envelope on the ancestor — and only subclassing counts, not `include`. Positioned at the override's `def`. Needs an `effects:` block. | high |
 | <a id="rule-effect-unknown-label"></a>`effect.unknown-label` | An effect declaration names a label the registry does not know — a typo in an envelope (`%a{rigor:v1:effect io.bd}`), or a member of `effects.tolerated:`. The whole tag then reads as unbounded, so the declaration quietly stops doing anything; this says so. Positioned at the declaration: the `.rbs` line, the `.rb` line for an rbs-inline annotation, or `.rigor.yml` for a config value. `# rigor:disable` comments are not read out of `.rbs` or `.rigor.yml`, so use `disable:` or the baseline there. Only fires where the spelling is evidently meant to be a label (close to a known one, next to a known one, dotted, or retired) — a word nothing resembles stays silent, because you may be opening your own vocabulary. Needs an `effects:` block. | high |
-| <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — except on a run that analyses no file at all (a warm `--incremental` with nothing changed), where only the `.rbs` lane is visible. | — |
+| <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — on every run, a warm `--incremental` with nothing changed included. | — |
 | <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
 | <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
 | <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |

data/lib/rigor/analysis/crash_signature.rb

@@ -42,9 +42,16 @@ module Rigor
     #   prepare row is appended to every sequential run, it would refuse every run for the life of the
     #   process.
     # - `:rbs_build` — the analysis ran to completion and every rule fired, over a type universe missing one
-    #   class (`rbs.coverage.definition-build-failed`) or all of them
-    #   (`rbs.coverage.environment-build-failed`). A degradation the user causes and the diagnostic itself
-    #   reports; a project can sit on it for a release while it fixes its `sig/`.
+    #   class (`rbs.coverage.definition-build-failed`), all of them
+    #   (`rbs.coverage.environment-build-failed`), or only the HKT registrations the `type` aliases and the
+    #   loaded plugins' manifests would have contributed (`rbs.coverage.hkt-scan-failed`, issues #784 and
+    #   #791). The first two are degradations
+    #   the user causes and the diagnostic itself reports; a project can sit on one for a release while it
+    #   fixes its `sig/`. The third is NOT the user's: post-#783 the scan raising is an analyzer defect, and
+    #   the overlay stage is a defect in Rigor or in a plugin the user installed, never in their `sig/`. It
+    #   still belongs here rather than under `:check_rule`, because the question this classification
+    #   answers is "may a consumer still read the run's diagnostics?" — and it may: every rule fired. What
+    #   differs is whether the run is a valid measurement OF RIGOR, which is {.analyzer_defect?}'s question.
     #
     # The two consumer tiers therefore differ on purpose. The ADR-69 kill oracles arm `:check_rule` only:
     # refusing a run they could still have measured is the same "manufactures work" error as scoring an
@@ -63,10 +70,11 @@ module Rigor
       PLUGIN_SOURCE_FAMILY = :plugin_loader
       PLUGIN_RULE = "runtime-error"
 
-      # The `rbs.coverage.*` rules that mean declared types went missing from this run — an env-wide
-      # collapse and its per-class sibling (#696). Ordered widest consequence last, the way the two rows sit
-      # in `docs/type-specification/diagnostic-policy.md`.
+      # The `rbs.coverage.*` rules that mean declared types went missing from this run — the implicit-HKT
+      # scan over `type` aliases (#784), a per-class definition build (#696), and the env-wide collapse.
+      # Ordered widest consequence last, the way the rows sit in `docs/type-specification/diagnostic-policy.md`.
       RBS_BUILD_FAILURE_RULES = %w[
+        rbs.coverage.hkt-scan-failed
         rbs.coverage.definition-build-failed
         rbs.coverage.environment-build-failed
       ].freeze
@@ -75,8 +83,62 @@ module Rigor
       # `:rbs_build` both leave a readable run behind — see the class doc.
       DISCARDS_FILE_ANALYSIS_REASON = :check_rule
 
+      # The `:rbs_build` rules whose cause is Rigor, not the user's `sig/` (issue #784). Readable for the
+      # user — every rule fired — but NOT a valid measurement of Rigor itself, so a harness that scores
+      # Rigor's behaviour should treat one of these as a crash finding the way it treats `:check_rule`, or
+      # a mutant that re-breaks the HKT scan (#776 was one) scores as a measurement over a silently degraded
+      # universe. What consults it today: `tool/mutation`'s fuzz crash detector — on the severity-resolved
+      # stream, so a `severity_overrides: rbs: off` hides the row from it. What does NOT yet: the ADR-69
+      # kill oracle (`Protection::AnalysisGuard` reads `Result#crashed?`, which excludes every
+      # `:rbs_build` row), and both harnesses still reuse one Environment across mutants, which memoises
+      # the degraded registry after the first defect. Arming the oracle, inspecting the pre-severity row,
+      # and resetting the Environment are issue #790.
+      ANALYZER_DEFECT_RULES = %w[
+        rbs.coverage.hkt-scan-failed
+      ].freeze
+
       module_function
 
+      # The message `Runner#analyze_file_body` / `WorkerSession#analyze_body` fold a raised `StandardError`
+      # into. Built here, not at either rescue site, so the two twins cannot drift (issue #665) — and so
+      # the appended crash frame is derived identically on the sequential and pooled paths. Keeps the
+      # {CHECK_RULE_MESSAGE_PREFIX} prefix every consumer matches on; the frame is a trailing hint.
+      #
+      # @param error [StandardError]
+      # @return [String]
+      def check_rule_message(error)
+        base = "#{CHECK_RULE_MESSAGE_PREFIX}: #{error.class}: #{error.message}"
+        frame = crash_frame(error)
+        frame ? "#{base} (#{frame})" : base
+      end
+
+      # The first `lib/rigor/` backtrace frame — the raise site, path made repo-relative so it reads the
+      # same whether Rigor runs from a checkout or an installed gem. A LOCATION, not an attribution: a
+      # bundled or third-party plugin also lives under `lib/rigor/<plugin>/`, so a frame here says where
+      # the raise was, never whose defect it is. Falls back to the raw top frame when the crash is entirely
+      # inside a dependency, and to nil when there is no backtrace at all.
+      #
+      # @param error [Exception]
+      # @return [String, nil]
+      def crash_frame(error)
+        frames = error.backtrace
+        return nil if frames.nil? || frames.empty?
+
+        relativize_frame(frames.find { |f| f.include?("/lib/rigor/") } || frames.first)
+      end
+
+      # The repo-relative half of {.crash_frame}, pulled out on its own so a second caller — the #784
+      # `rbs.coverage.hkt-scan-failed` diagnostic, which stores its raw frame across a `Marshal` boundary
+      # (the fork pool) rather than deriving it fresh from a live `Exception` — can relativize the frame it
+      # already has without re-deriving `.crash_frame`'s "which frame" choice. Nil-safe, and a no-op (`sub`
+      # never matches) on a frame with no `lib/rigor/` segment at all.
+      #
+      # @param frame [String, nil]
+      # @return [String, nil]
+      def relativize_frame(frame)
+        frame&.sub(%r{\A.*/(lib/rigor/)}, '\1')
+      end
+
       # @param diagnostic [Rigor::Analysis::Diagnostic]
       # @return [Symbol, nil] `:check_rule`, `:plugin`, `:rbs_build`, or nil for an ordinary diagnostic.
       def reason(diagnostic)
@@ -96,6 +158,16 @@ module Rigor
         reason(diagnostic) == DISCARDS_FILE_ANALYSIS_REASON
       end
 
+      # True when `diagnostic` reports a failure inside Rigor that left the run readable but invalid as a
+      # measurement of Rigor — see {ANALYZER_DEFECT_RULES}. Orthogonal to {.discards_file_analysis?}: the
+      # user-facing tier reads the run; the Rigor-measuring tier should refuse it (the mutation fuzz does,
+      # the ADR-69 kill oracle does not yet — #790).
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      def analyzer_defect?(diagnostic)
+        ANALYZER_DEFECT_RULES.include?(diagnostic.rule)
+      end
+
       # A one-line "<reason> at <path>:<line>: <message>" for a failure message, so whoever reads the raise
       # sees which shape fired and where without re-deriving it.
       #

data/lib/rigor/analysis/incremental_session.rb

@@ -172,7 +172,7 @@ module Rigor
         # ADR-103 WD13 / #382 — a baseline collects every file, so its collections are the whole world.
         @effect_collections = runner.effect_collections_by_path
         @effects_identity = current_effects_identity
-        @cache = per_file(diagnostics)
+        @cache = per_file(runner.per_file_diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
         diagnostics
       end
@@ -202,7 +202,7 @@ module Rigor
         @last_runner = runner # ADR-88 WD1 — the post-hoc fact-surface fingerprint reads this prepared registry.
         reused = (current & previous) - affected.to_a
         merged = fresh + reused.flat_map { |path| @cache[path] || [] }
-        absorb(runner, fresh, current, analyze_set, removed)
+        absorb(runner, current, analyze_set, removed)
         @param_table = fresh_params
         Recheck.new(diagnostics: merged, changed: changed.to_set, added: added.to_set,
                     removed: removed.to_set, affected: affected, reused: reused.to_set)
@@ -684,13 +684,13 @@ module Rigor
       # Fold a #recheck's fresh results back into the cache + graph so the session is correct across
       # multiple edits: the analyzed set gets fresh diagnostics + digests + dependency edges, removed files
       # are evicted from every map, and the analyzed-file list advances to `current`.
-      def absorb(runner, fresh, current, analyze_set, removed)
+      def absorb(runner, current, analyze_set, removed)
         removed.each { |path| forget(path) }
         @analyzed = current
         # ADR-85 WD2 — the recheck's discovery folded the restored bundles and refreshed them (changed files
         # re-walked, removed files dropped, added files built), so adopt the runner's current set wholesale.
         @seed_bundles = runner.seed_bundles
-        fresh_by_file = per_file(fresh)
+        fresh_by_file = per_file(runner.per_file_diagnostics)
         analyze_set.each do |path|
           @cache[path] = fresh_by_file[path] || []
           @digests[path] = pack_digest(path)
@@ -984,9 +984,21 @@ module Rigor
         @paths ? runner.run(@paths) : runner.run
       end
 
-      # Group diagnostics by their file path, keeping only those whose path is an analyzed project file —
-      # run-level streams (the gem-RBS info diagnostic, keyed on `.rigor.yml`) are recomputed fresh every
-      # run and must not be served from the per-file cache.
+      # Group the runner's PER-FILE diagnostics by path, keeping only analyzed project files.
+      #
+      # The argument is `Runner#per_file_diagnostics` — what `PoolCoordinator#analyze_files` returned, already
+      # severity-resolved as the run's stream is (this cache serves reused files without re-stamping, so a
+      # raw row would resurrect an `:off` rule and lose every override) — never the run's full stream. Every
+      # run-level row is regenerated by every run and must not be served
+      # from this cache, and "run-level" is a property of where a row was PRODUCED, not of where it is
+      # positioned: the `.rigor.yml` rows the slice below drops are the common case, but
+      # `effect.annotations-unchecked` sits at the first annotated file and the two `source-rbs-*` rows sit
+      # at the source file that carried the annotation, and all three are produced once per run off the
+      # environment and its reporters. Slicing the full stream cached them, and once a narrowed run's
+      # environment carried the whole project's synthesized RBS (#793) each was regenerated for a file the
+      # recheck did not analyse and met its cached twin in the merge — two rows, `--verify-incremental` red,
+      # on the default configuration with the bundled rbs-inline plugin (#788 rounds 5 and 6; a rule-id
+      # denylist missed the second pair). Feeding only the per-file stream makes the split structural.
       def per_file(diagnostics)
         diagnostics.group_by(&:path).slice(*@analyzed)
       end

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"
 
@@ -39,13 +40,18 @@ module Rigor
         # @param definition_build_failures_snapshot [#call] 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 hkt_scan_failure_snapshot [#call] 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 [#call] 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:)
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -59,6 +65,7 @@ module Rigor
           @quarantined_signatures_snapshot_reader = quarantined_signatures_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 +322,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 +390,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?
@@ -458,11 +486,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
@@ -550,6 +579,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}"
@@ -603,16 +692,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 +713,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 +722,22 @@ module Rigor
             )
           end
 
-          unresolved + lossy
+          unresolved + lossy + hkt_directive_diagnostics
+        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
@@ -712,6 +819,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?
 
@@ -776,6 +897,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