rigortype 0.3.7 → 0.3.9

data/lib/rigor/protection/closure_kill_oracle.rb

@@ -55,35 +55,36 @@ module Rigor
       # knowledge the single-file run does not have) must not mask a kill the shipped oracle would report.
       Baseline = Data.define(:own, :dependents)
 
-      # @param configuration [Rigor::Configuration]
-      # @param environment [Rigor::Environment] built once by the caller.
-      # @param project_scan [Rigor::Analysis::ProjectScan] built once by the caller; adopted per analysis
+      # @param environment — built once by the caller.
+      # @param project_scan — built once by the caller; adopted per analysis
       #   through `prebuilt:`, exactly as {DiagnosticOracle} does.
-      # @param paths [Array<String>] the measured file set, in canonical order (the seed's span: a class
+      # @param paths — the measured file set, in canonical order (the seed's span: a class
       #   declared outside it stays unknown, as it does for Tier 1's seed and for {DiscoverySeed}).
-      # @param dependents [Hash{String => Array<String>}] {DependencyClosure} map, restricted to `paths`.
-      # @param seed_bundles [Hash{String => Hash}] {DiscoverySeed.bundles} over the same `paths`.
-      # @param discovery_seed [Hash, nil] the `discovery-seeded-mutation-sites` seed when that feature is also
+      # @param dependents — {DependencyClosure} map, restricted to `paths`.
+      # @param seed_bundles — {DiscoverySeed.bundles} over the same `paths`.
+      # @param discovery_seed — the `discovery-seeded-mutation-sites` seed when that feature is also
       #   adopted, nil otherwise. It goes to the delegated {DiagnosticOracle} verbatim, so the mutated file's
       #   verdict is byte-for-byte the verdict that feature combination produces without this one; its
       #   `param_inferred_types` slot additionally rides the per-mutant closure seed, so an admitted site is
       #   judged with the knowledge that admitted it (issue #260's amended decision). The table is not
       #   refreshed per mutant — the collector is a whole-project pre-pass, and one mutated method body does
       #   not justify re-running it thousands of times.
+      # @param rebuild_session — issue #790 — a callable returning a FRESH `[environment, project_scan]`
+      #   pair, invoked after a run this oracle refused for an analyzer defect. nil means the caller has no
+      #   way to rebuild; see {#recovering} for what the oracle then does instead.
+      # rubocop:disable Metrics/ParameterLists -- the eight are independent collaborators the caller builds
+      # once each; an options object would only put a name in front of the same list.
       def initialize(configuration:, environment:, project_scan:, paths:, dependents:, seed_bundles:,
-                     discovery_seed: nil)
+                     discovery_seed: nil, rebuild_session: nil)
+        # rubocop:enable Metrics/ParameterLists
         @configuration = configuration
-        @environment = environment
-        @project_scan = project_scan
         @paths = paths
         @dependents = dependents
         @seed_bundles = seed_bundles
         @discovery_seed = discovery_seed
+        @rebuild_session = rebuild_session
         @param_inferred_types = discovery_seed && discovery_seed[:param_inferred_types]
-        @single = DiagnosticOracle.new(
-          configuration: configuration, environment: environment, project_scan: project_scan,
-          discovery_seed: discovery_seed
-        )
+        adopt_session(environment, project_scan)
       end
 
       # The clean baselines a mutant must add a diagnostic to: the mutated file's (the shipped oracle's own,
@@ -91,21 +92,25 @@ module Rigor
       # never per mutant. The dependents' half is bound through the same buffer machinery a mutant is, so the
       # clean and mutant runs of the closure differ in exactly one input — the bytes.
       def baseline(source:, path:)
-        Baseline.new(
-          own: @single.baseline(source: source, path: path),
-          dependents: dependents_signatures(source, path)
-        )
+        recovering do
+          Baseline.new(
+            own: @single.baseline(source: source, path: path),
+            dependents: dependents_signatures(source, path)
+          )
+        end
       end
 
       # Killed iff the mutant introduces a diagnostic the baseline did not carry — in the mutated file (the
       # shipped verdict), or, failing that, in any dependent of it (what this feature adds).
       def killed?(mutant_source:, path:, baseline:)
-        return true if @single.killed?(mutant_source: mutant_source, path: path, baseline: baseline.own)
+        recovering do
+          next true if @single.killed?(mutant_source: mutant_source, path: path, baseline: baseline.own)
 
-        dependents = @dependents[path] || []
-        return false if dependents.empty?
+          dependents = @dependents[path] || []
+          next false if dependents.empty?
 
-        dependents_signatures(mutant_source, path).any? { |sig| !baseline.dependents.include?(sig) }
+          dependents_signatures(mutant_source, path).any? { |sig| !baseline.dependents.include?(sig) }
+        end
       end
 
       # The file set a kill is looked for in: the mutated file plus its measured dependents.
@@ -115,6 +120,45 @@ module Rigor
 
       private
 
+      # Issue #790 — a refused mutant is one mutant; a POISONED Environment is every mutant after it.
+      #
+      # The #784 seam records its failure on the Environment and {Environment::HktRegistryHolder} memoises
+      # the degraded registry, while {Environment::FailureSlot} is first-write-wins. So the one mutant that
+      # made the scan raise leaves an Environment that reports `rbs.coverage.hkt-scan-failed` on every later
+      # run and never re-attempts the scan — the row lands on BOTH sides of the next mutant's set
+      # difference, and every later mutant is measured over the degraded universe. Pre-#788 the raise
+      # propagated instead of being memoised, so the next demand retried the build and the poisoning did not
+      # exist; recovering it is this method.
+      #
+      # REBUILD rather than reset the slots. A reset would be cheaper, but it has to enumerate every holder
+      # the degraded registry fed — the memo itself, the failure slot, and the constant-type cache whose
+      # entries were folded under it — and a holder added to {Rigor::Environment} later would silently not
+      # be reset, with nothing to go red. The cost objection a reset answers is a rebuild PER MUTANT; this
+      # one is paid only after a defect is actually observed, which on a healthy sweep is never.
+      #
+      # With no `rebuild_session:` the oracle keeps the poisoned Environment and every later mutant is
+      # refused by the same guard. That is the deliberate fallback: a sweep that reports `harness_errors`
+      # says it could not measure, where the pre-#790 behaviour said "survived" about a universe it had
+      # silently degraded.
+      def recovering
+        yield
+      rescue AnalyzerCrashed => e
+        adopt_session(*@rebuild_session.call) if e.analyzer_defect? && @rebuild_session
+        raise
+      end
+
+      # The delegated single-file oracle is rebuilt with the pair, not handed the new Environment after the
+      # fact: it holds its own reference, and an oracle whose two halves disagree about which Environment
+      # they measure over is the same split-universe bug one layer down.
+      def adopt_session(environment, project_scan)
+        @environment = environment
+        @project_scan = project_scan
+        @single = DiagnosticOracle.new(
+          configuration: @configuration, environment: environment, project_scan: project_scan,
+          discovery_seed: @discovery_seed
+        )
+      end
+
       # The diagnostic signatures the dependents of `path` report while `source` stands in for it. Empty (and
       # analysis-free) when nothing depends on the file — 120 of Rigor's own 349 `lib` files.
       def dependents_signatures(source, path)
@@ -187,7 +231,7 @@ module Rigor
             configuration: @configuration, environment: @environment, prebuilt: @project_scan,
             cache_store: nil, collect_stats: false, buffer: buffer, discovery_seed: seed, analyze_only: paths
           ).run(paths),
-          context: "ClosureKillOracle closure analysis of #{paths.join(', ')}"
+          context: "ClosureKillOracle closure analysis of #{paths.join(', ')}", environment: @environment
         )
       end
     end

data/lib/rigor/protection/dependency_closure.rb

@@ -24,14 +24,13 @@ module Rigor
     module DependencyClosure
       module_function
 
-      # @param paths [Array<String>] the measured file set, in caller order.
-      # @param configuration [Rigor::Configuration]
-      # @param environment [Rigor::Environment] built once by the caller.
-      # @param cache_store [Rigor::Cache::Store, nil] threaded to the recording run only (its RBS-env and
+      # @param paths — the measured file set, in caller order.
+      # @param environment — built once by the caller.
+      # @param cache_store — threaded to the recording run only (its RBS-env and
       #   plugin-producer tiers); the per-mutant analyses stay `cache_store: nil` regardless.
-      # @param workers [Integer] fork-pool workers for the recording pass (the pool records per worker and
+      # @param workers — fork-pool workers for the recording pass (the pool records per worker and
       #   marshals the records back, so a pooled graph equals the sequential one).
-      # @return [Hash{String => Array<String>}] frozen `path => sorted dependents`, restricted to `paths`.
+      # @return frozen `path => sorted dependents`, restricted to `paths`.
       def build(paths:, configuration:, environment:, cache_store: nil, workers: 0)
         runner = Analysis::Runner.new(
           configuration: configuration, environment: environment, cache_store: cache_store,
@@ -45,8 +44,6 @@ module Rigor
       # not being measured, so re-analysing it would report a diagnostic against a file the run never
       # baselined. Self-edges are dropped (the mutated file is the closure's own head), and each list is
       # sorted so a `--threshold` gate reads the same number whatever order the recording pass finished in.
-      #
-      # @return [Hash{String => Array<String>}]
       def index(dependents, paths)
         measured = Set.new(paths)
         paths.to_h do |path|

data/lib/rigor/protection/diagnostic_oracle.rb

@@ -17,7 +17,7 @@ module Rigor
     # disk write). Passing `prebuilt:` disables the run-result cache (whose key digests the *disk* file), so a
     # mutant is never served a stale clean hit.
     class DiagnosticOracle
-      # @param discovery_seed [Hash, nil] issue #260 — the cross-file discovery tables (see {DiscoverySeed})
+      # @param discovery_seed — issue #260 — the cross-file discovery tables (see {DiscoverySeed})
       #   the per-mutant analysis is seeded with, threaded through to `Runner.new(discovery_seed:)`. Without
       #   it the runner's `prebuilt:` path carries frozen-empty discovery tables, so a receiver whose class is
       #   declared in a *sibling* file reads `Dynamic` and NO mutation at that site can produce a diagnostic —
@@ -53,7 +53,7 @@ module Rigor
             configuration: @configuration, environment: @environment, prebuilt: @project_scan,
             cache_store: nil, collect_stats: false, discovery_seed: @discovery_seed
           ).run_source(source: source, path: path),
-          context: "DiagnosticOracle re-analysis of #{path}"
+          context: "DiagnosticOracle re-analysis of #{path}", environment: @environment
         )
       end
     end

data/lib/rigor/protection/discovery_seed.rb

@@ -30,12 +30,12 @@ module Rigor
     module DiscoverySeed
       module_function
 
-      # @param paths [Array<String>] the measured file set; the seed spans these files only, exactly as Tier 1's
+      # @param paths — the measured file set; the seed spans these files only, exactly as Tier 1's
       #   seed does. A class declared outside them stays unknown.
-      # @param environment [Rigor::Environment] the plugin-aware environment, built once by the caller.
-      # @param target_ruby [String] Prism parse version for the parameter-inference pre-pass.
-      # @param workers [Integer] worker count for that pre-pass (0 keeps it sequential).
-      # @return [Hash{Symbol => Object}] frozen seed tables; empty when the paths yield nothing.
+      # @param environment — the plugin-aware environment, built once by the caller.
+      # @param target_ruby — Prism parse version for the parameter-inference pre-pass.
+      # @param workers — worker count for that pre-pass (0 keeps it sequential).
+      # @return frozen seed tables; empty when the paths yield nothing.
       def build(paths:, environment:, target_ruby:, workers: 0)
         tables = discovery_tables(paths)
         params = Inference::ParameterInferenceCollector.collect(
@@ -51,8 +51,8 @@ module Rigor
       # builds. Built ONCE on the parent (before {CLI::MutationForkScan} forks, so children copy-on-write
       # inherit it), and cheap: ≈0.36s over Rigor's own 349-file `lib`.
       #
-      # @param paths [Array<String>] the measured file set, in canonical (caller) order.
-      # @return [Hash{String => Hash}] per-path bundles, the input {#tables_for_buffer} re-folds.
+      # @param paths — the measured file set, in canonical (caller) order.
+      # @return per-path bundles, the input {#tables_for_buffer} re-folds.
       def bundles(paths:)
         Inference::ScopeIndexer.discovered_project_index_incremental(paths, seed_bundles: {}).fetch(:bundles)
       end
@@ -69,10 +69,10 @@ module Rigor
       #
       # ≈15ms over 349 files (one re-walk plus a whole-set fold), against ≈210ms for one mutant's analysis.
       #
-      # @param paths [Array<String>] the measured file set, in the same order {#bundles} was built from.
-      # @param bundles [Hash{String => Hash}] that bundle set.
-      # @param buffer [Rigor::Analysis::BufferBinding] the mutant binding (logical path → mutant bytes).
-      # @return [Hash{Symbol => Object}] frozen seed tables.
+      # @param paths — the measured file set, in the same order {#bundles} was built from.
+      # @param bundles — that bundle set.
+      # @param buffer — the mutant binding (logical path → mutant bytes).
+      # @return frozen seed tables.
       def tables_for_buffer(paths:, bundles:, buffer:)
         index = Inference::ScopeIndexer.discovered_project_index_incremental(
           paths, seed_bundles: bundles, buffer: buffer

data/lib/rigor/protection/kill_signature.rb

@@ -15,14 +15,12 @@ module Rigor
     module KillSignature
       module_function
 
-      # @param diagnostic [Rigor::Analysis::Diagnostic]
-      # @return [Array] the comparison key.
+      # @return the comparison key.
       def of(diagnostic)
         [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
       end
 
-      # @param diagnostics [Enumerable<Rigor::Analysis::Diagnostic>]
-      # @return [Set<Array>] the signature set of `diagnostics`.
+      # @return the signature set of `diagnostics`.
       def signatures_of(diagnostics)
         diagnostics.to_set { |diagnostic| of(diagnostic) }
       end

data/lib/rigor/protection/measurement_integrity.rb

@@ -19,15 +19,13 @@ module Rigor
     module MeasurementIntegrity
       module_function
 
-      # @return [Boolean] false only when nothing could be measured AND something failed trying.
+      # @return false only when nothing could be measured AND something failed trying.
       def measured?(total:, harness_errors:)
         !(total.zero? && harness_errors.positive?)
       end
 
       # The report-level companion: a project ratio computed over nothing, where something went wrong.
       # Distinct from an empty project, which is legitimately vacuous.
-      #
-      # @return [Boolean]
       def ratio_unmeasurable?(grand_total:, unmeasured_files:)
         grand_total.zero? && unmeasured_files.positive?
       end

data/lib/rigor/protection/mutation_cache.rb

@@ -89,17 +89,15 @@ module Rigor
       UNIDENTIFIED_ENGINE = "the engine's own source tree could not be digested"
 
       class << self
-        # @param configuration [Rigor::Configuration]
-        # @param roots [Array<String>] the analysis roots to look for a snapshot under, most-specific first
+        # @param roots — the analysis roots to look for a snapshot under, most-specific first
         #   (the command's own path arguments, then the configured `paths:`).
-        # @param project_scan [Rigor::Analysis::ProjectScan] the prepared whole-project scan.
-        # @param sampling [Sampling]
-        # @param feature_ids [Array<String>] the ADOPTED bleeding-edge ids that change this measurement.
-        # @param seed_inputs [Array<String>, nil] the files the {DiscoverySeed} was built over when it is
+        # @param project_scan — the prepared whole-project scan.
+        # @param feature_ids — the ADOPTED bleeding-edge ids that change this measurement.
+        # @param seed_inputs — the files the {DiscoverySeed} was built over when it is
         #   active, nil when it is not. The CLI stays the only place that knows a feature id exists.
-        # @param bypass_reason [String, nil] a caller-side reason to run uncached (`--no-cache`, the closure
+        # @param bypass_reason — a caller-side reason to run uncached (`--no-cache`, the closure
         #   oracle). Reported verbatim.
-        # @return [MutationCache] enabled, or a disabled instance carrying `#reason`.
+        # @return enabled, or a disabled instance carrying `#reason`.
         def build(configuration:, roots:, project_scan:, sampling:, feature_ids:, seed_inputs: nil,
                   bypass_reason: nil)
           return disabled(bypass_reason) if bypass_reason
@@ -263,7 +261,6 @@ module Rigor
       end
 
       # The cached result for `path`, or nil on any miss (including "this cache is disabled").
-      # @return [MutationScanner::FileResult, nil]
       def fetch(path)
         return nil unless enabled?
         # A path the snapshot never analysed has no recorded `deps[A]`, which means "depends on every project

data/lib/rigor/protection/mutation_scanner.rb

@@ -87,25 +87,25 @@ module Rigor
         end
       end
 
-      # @param configuration [Rigor::Configuration]
-      # @param environment [Rigor::Environment] pre-built once by the caller
-      # @param project_scan [Rigor::Analysis::ProjectScan] pre-built once
-      # @param limit [Integer, nil] optional per-file mutation cap (sampled with
+      # @param environment — pre-built once by the caller
+      # @param project_scan — pre-built once
+      # @param limit — optional per-file mutation cap (sampled with
       #   `seed`); nil analyses every type-relevant mutation (deterministic).
-      # @param seed [Integer] RNG seed for the optional sample.
-      # @param oracle [#baseline, #killed?, nil] the kill oracle (ADR-69 Seam 1);
-      #   defaults to the {DiagnosticOracle} (the ADR-62/63 behaviour).
-      # @param site_selector [:biteable, :all] which sites to mutate (ADR-69
+      # @param seed — RNG seed for the optional sample.
+      # @param oracle — the kill oracle (ADR-69 Seam 1) — anything answering
+      #   `baseline` and `killed?`; defaults to the {DiagnosticOracle} (the
+      #   ADR-62/63 behaviour).
+      # @param site_selector — which sites to mutate (ADR-69
       #   Seam 2). `:biteable` (default) keeps only concrete-type sites Rigor can
       #   bite; `:all` also mutates Dynamic-receiver dispatch sites — use only
       #   with a {TestSuiteOracle} (the fused overlay), never the diagnostic path.
-      # @param base_scope [Rigor::Scope, nil] the scope site selection judges
+      # @param base_scope — the scope site selection judges
       #   anchor types against, built once by the caller (see
       #   {Mutator#anchor_base_scope}). `nil` — the default — keeps the bare
       #   single-file empty scope. A caller that seeds cross-file discovery
       #   passes it here; this class stays free of {Rigor::Configuration} and of
       #   bleeding-edge feature ids, which live one layer up in the CLI.
-      # @param discovery_seed [Hash, nil] issue #260 — the SAME cross-file table
+      # @param discovery_seed — issue #260 — the SAME cross-file table
       #   set `base_scope` was built from, threaded to the default
       #   {DiagnosticOracle} so an admitted cross-file site is one the oracle can
       #   also kill at. Pass both or neither: a `base_scope` without it measures
@@ -127,9 +127,8 @@ module Rigor
         )
       end
 
-      # @param path [String] the file to measure (used as the in-memory bind path)
-      # @param source [String, nil] the file's source; read from disk when nil
-      # @return [FileResult]
+      # @param path — the file to measure (used as the in-memory bind path)
+      # @param source — the file's source; read from disk when nil
       def scan_file(path, source: nil)
         source ||= File.read(path, encoding: Encoding::UTF_8)
         kept = kept_mutations(source, path)
@@ -156,8 +155,6 @@ module Rigor
       # mutant the type checker did **not** kill, asks `test_oracle` whether the project's test suite catches it.
       # The expensive suite run is paid only for type-survivors (the gradual short-circuit), so the cost is
       # proportional to the protection hole.
-      # @param test_oracle [TestSuiteOracle]
-      # @return [FusedFileResult]
       def scan_file_fused(path, test_oracle:, source: nil)
         source ||= File.read(path, encoding: Encoding::UTF_8)
         kept = kept_mutations(source, path)

data/lib/rigor/protection/mutator.rb

@@ -127,6 +127,7 @@ module Rigor
         when Type::Constant then CONSTANT_CLASSES[type.value.class] || type.value.class.name
         when Type::Refined, Type::Difference then concrete_class_name(type.base)
         when Type::IntegerRange then "Integer"
+        when Type::FloatRange then "Float"
         when Type::App then concrete_class_name(type.bound)
         end
       end
@@ -171,7 +172,7 @@ module Rigor
       # only removes provably-Dynamic sites. Returns [kept, dropped_count]. Builds the scope index from THIS
       # mutator's parse so anchor node identity matches the keys.
       #
-      # @param base_scope [Rigor::Scope, nil] a pre-seeded scope to judge anchors against (see
+      # @param base_scope — a pre-seeded scope to judge anchors against (see
       #   {#anchor_base_scope}); nil builds the bare empty scope, which is the shipped default.
       def filter_by_type(mutations, environment:, path:, base_scope: nil)
         base = anchor_base_scope(environment, path, base_scope)

data/lib/rigor/protection/test_suite_oracle.rb

@@ -16,8 +16,8 @@ module Rigor
     # standard mutation-testing hazard the `ensure` cannot cover; callers running this in CI accept that, as
     # `mutant` / Stryker do.)
     class TestSuiteOracle
-      # @param command [Array<String>] the test command (the runner hook)
-      # @param runner [#call, nil] `runner.call(command) -> true iff the suite
+      # @param command — the test command (the runner hook)
+      # @param runner — `runner.call(command) -> true iff the suite
       #   passed`. Defaults to shelling out via `system`.
       def initialize(command:, runner: nil)
         @command = command
@@ -31,9 +31,9 @@ module Rigor
       end
 
       # Killed iff the mutant turns the suite red. Restores `original` afterward.
-      # @param path [String] the file to (temporarily) overwrite with the mutant
-      # @param original [String] the clean bytes to restore
-      # @param mutant_source [String] the mutated bytes to test against
+      # @param path — the file to (temporarily) overwrite with the mutant
+      # @param original — the clean bytes to restore
+      # @param mutant_source — the mutated bytes to test against
       def killed?(path:, original:, mutant_source:)
         File.write(path, mutant_source)
         !@runner.call(@command)

data/lib/rigor/rbs_extended/conformance_checker.rb

@@ -31,8 +31,9 @@ module Rigor
     # - `IncompatibleSignature` — a provided method's signature violates the interface contract (return widened,
     #   or a parameter narrowed). Same rule, signature-specific message.
     # - `UnresolvedInterface` — the named interface is not loaded (a typo, or the defining library / `sig` set is
-    #   not on the RBS load path). Surfaces as `dynamic.rbs-extended.unresolved` `:info`, the fail-soft channel
-    #   the other directive parsers use, so a bad name never silently disables the author's assertion.
+    #   not on the RBS load path). Surfaces as `dynamic.rbs-extended.unresolved` at `:warning` (#928): the
+    #   other directive parsers fail soft to `:info`, but a name the author asserted against must not pass
+    #   silently — the catalog ships, so an unresolved role is a typo or a missing `sig` set.
     #
     # Fail-soft throughout: a class whose own definition cannot be built (RBS error) is skipped rather than
     # reported.
@@ -60,7 +61,7 @@ module Rigor
         results
       end
 
-      # @return [Array] zero or more records for one (class, interface) pair.
+      # @return zero or more records for one (class, interface) pair.
       def check_one(rbs_loader, class_name, interface_name, location)
         interface_def = resolve_interface(rbs_loader, class_name, interface_name)
         if interface_def.nil?

data/lib/rigor/rbs_extended/envelope_scanner.rb

@@ -22,14 +22,15 @@ module Rigor
     #
     # ## Why it parses rather than reading the built environment
     #
-    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope cannot: the
+    # {ConformanceChecker}, the obvious model, walks `RbsLoader`'s built env. An envelope did not: the
     # diagnostic has to name **where the bound was written** (`sig/foo.rbs:12`), and the ADR-54 env
-    # cache dumps every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run would lose
-    # both the position and the only evidence of which file a declaration came from. Parsing the
-    # project's own signature sources is a few milliseconds over a tree Rigor already globs, it is
-    # identical warm and cold, and it enforces ADR-103 WD6's trust rule structurally: a `%a{pure}` in
-    # rbs core or in a gem's shipped RBS is never read, so it cannot bound a project method that
-    # happens to share its key.
+    # cache reduced every `RBS::Location` to a zero-range `<cached>` sentinel, so a warm run lost both
+    # the position and the only evidence of which file a declaration came from. That particular loss is
+    # closed now — #696 restored the buffer name, #799 an annotation's position — so what still decides
+    # it is the rest: parsing the project's own signature sources is a few milliseconds over a tree
+    # Rigor already globs, it is identical warm and cold, and it enforces ADR-103 WD6's trust rule
+    # structurally: a `%a{pure}` in rbs core or in a gem's shipped RBS is never read, so it cannot bound
+    # a project method that happens to share its key.
     #
     # Malformed payloads and `pure`-versus-`effect` contradictions are recorded on a {Reporter} the
     # scanner owns and ride out on {Result#unresolved}. They surface no diagnostic in this slice:
@@ -47,10 +48,9 @@ module Rigor
 
       module_function
 
-      # @param sources [Array<Array(String, String)>] `[buffer name, RBS source]` pairs — the project's
+      # @param sources — `[buffer name, RBS source]` pairs — the project's
       #   `.rbs` files, plus the virtual entries rbs-inline and plugin `source_rbs` synthesis contribute.
-      # @param registry [Rigor::Effects::Registry] the vocabulary an unknown label is judged against.
-      # @return [Result]
+      # @param registry — the vocabulary an unknown label is judged against.
       #
       # The `ANNOTATION_HINT` routing test runs here, before any parse: a source with no honoured
       # payload can contribute neither an envelope nor an unresolved report, so a signature tree with
@@ -93,11 +93,10 @@ module Rigor
       # class discovery knows", which is a project fact; a gem's class-level tag would have to
       # distribute over a definition set this reader does not have.
       #
-      # @param loader [Rigor::Environment::RbsLoader] the run's loader; it owns the env walk
+      # @param loader — the run's loader; it owns the env walk
       #   ({Rigor::Environment::RbsLoader#each_annotated_method_member}), so the environment itself never
       #   leaves it.
-      # @param registry [Rigor::Effects::Registry]
-      # @return [Hash{String => Rigor::Effects::Envelope}] keyed `Class#m` / `Class.m`
+      # @return keyed `Class#m` / `Class.m`
       def from_loader(loader:, registry:)
         out = {}
         loader.each_annotated_method_member do |class_name, member|

data/lib/rigor/rbs_extended/hkt_directives.rb

@@ -2,6 +2,7 @@
 
 require_relative "../inference/hkt_registry"
 require_relative "../inference/hkt_body_parser"
+require_relative "reporter"
 
 module Rigor
   module RbsExtended
@@ -286,10 +287,24 @@ module Rigor
         source_location.respond_to?(:start_line) ? source_location.start_line : nil
       end
 
+      # Issue #785 — routes a declined directive to the per-run reporter. The FIRST arm is the one that
+      # matters: the production reporter is {RbsExtended::Reporter}, whose surface is `record_unresolved` /
+      # `record_lossy_projection` / `record_hkt_error` — it has neither `#record` nor `#<<`, so before this
+      # arm existed every call here fell off the end of the `if` and every malformed HKT directive was
+      # dropped in every real run, while the doc comments claimed an `:info` entry was recorded. The
+      # position is flattened at record time through {RbsExtended::Reporter.position_of}, the one place
+      # every stream flattens through since #805, because the entry has to reach the pool drain channel as
+      # primitives (see {RbsExtended::Reporter}).
+      #
+      # The `#record` / `#<<` arms stay for the collecting doubles the directive specs and plugin authors
+      # use, which is the contract `scan_rbs_loader`'s `@param reporter [#record, nil]` documents.
       def record_hkt_error(reporter, message, source_location)
         return if reporter.nil?
 
-        if reporter.respond_to?(:record)
+        if reporter.respond_to?(:record_hkt_error)
+          path, line, column = Reporter.position_of(source_location)
+          reporter.record_hkt_error(message: message, path: path, line: line, column: column)
+        elsif reporter.respond_to?(:record)
           reporter.record(directive: "hkt", message: message, source_location: source_location)
         elsif reporter.respond_to?(:<<)
           reporter << { directive: "hkt", message: message, source_location: source_location }