rigortype 0.3.7 → 0.3.8

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

@@ -115,11 +115,62 @@ module Rigor
         # sources. The env stays a LOCAL variable (not an ivar) so it goes GC-eligible when the method
         # returns — holding it as long-lived state added memory pressure that surfaced as a Bus Error
         # during the spec suite under Ruby 4.0 + rbs 4.0.2.
-        def analyze_files(files, environment: nil)
-          return [] if files.empty?
-          return dispatch_pool(files) if pool_mode?
-
-          analyze_files_sequentially(files, environment || resolve_sequential_environment(source_files: files))
+        # @param project_files [Array<String>, nil] issue #784 — the WHOLE project's analyzed file set
+        #   (`expansion.fetch(:files)`), independent of any `analyze_only` narrowing of `files`. Read only
+        #   when `files` is empty, to decide whether anyone could have demanded the HKT registry at all.
+        def analyze_files(files, environment: nil, project_files: nil)
+          if files.empty?
+            # Issue #784 — an EMPTY analyze set still owes the run its HKT-scan row: the per-file cache never
+            # holds it (`IncrementalSession` caches only `Runner#per_file_diagnostics`, so every run-level row
+            # is regenerated every run), so returning here without recording flips a red project green — and
+            # the shipping `--incremental` path reaches this branch with NO environment in hand on every
+            # warm recheck that changed nothing (`CheckCommand#run_incremental_check` builds its session
+            # without one). So: an environment already in hand is consulted; otherwise one is resolved over
+            # the project's OWN file list — not `[]`, which would drop every plugin-synthesized virtual RBS
+            # (`Environment.collect_virtual_rbs` short-circuits on an empty list) and scan a different type
+            # universe from the one a full run analyses — and only when the project HAS files: with none,
+            # nobody could have demanded a registry, and an empty project keeps paying no env build. Keyed
+            # on the project's files rather than on `analyze_only`, because a recheck over an EMPTY project
+            # narrows to `Set[]`, which is non-nil.
+            env = environment || @environment_override
+            if project_files && !project_files.empty?
+              env ||= resolve_sequential_environment(source_files: project_files)
+            end
+            # #788 rounds 6 and 9 — everything the run owes from its environment that no per-file analysis
+            # produces is taken here, the way `analyze_files_sequentially` takes it: the project-signature
+            # state (`synthesized-namespace`, `quarantined-signature`, `environment-build-failed`, the
+            # conformance results), the effect-annotation carrier the residual pass reads, and the HKT-scan
+            # outcome. Now that run-level rows are never served from the per-file cache, this branch is the
+            # only producer on a warm recheck that changed nothing — leaving any of them out turned a red
+            # project green on its second `--incremental` run (the inline-only `effect.annotations-unchecked`
+            # went 1 → 0; a quarantined `signature_paths:` file went 1 → 0; a `conforms-to` class whose
+            # definition build fails went 1 → 0). Same ORDER as the sequential path, because the order is
+            # the contract: the conformance scan inside the signature-state snapshot demands the definition
+            # of every `rigor:v1:conforms-to` class — a user-authored, invocation-independent demand that
+            # #696 counts — so the definition-build failures are read AFTER it and BEFORE the HKT demand,
+            # exactly where `analyze_files_sequentially` reads them relative to its own. What this branch
+            # cannot regenerate is the part of that set the per-file ANALYSIS demanded (#796). This also
+            # retires the #441 "`.rbs` lane only when the run analyses nothing" boundary: its cost premise
+            # (no environment on this path) stopped holding the moment the branch above resolved one.
+            snapshot_project_signature_state(env)
+            snapshot_effect_annotation_carrier(env&.rbs_loader)
+            record_definition_build_failures(env&.rbs_loader&.definition_build_failures)
+            record_hkt_scan_failure(hkt_scan_outcome(env))
+            return []
+          end
+          # Issue #784 / #793 — `files` is what this run ANALYSES; `source_files` is what its environment
+          # is BUILT over, and the two are the same only on a full run. A narrowed run (`analyze_only`: an
+          # incremental closure, a `--verify-incremental` partition) used to build its environment over the
+          # subset, so plugin-synthesized virtual RBS from every excluded file was missing and the run
+          # scanned a different type universe than the full run it is compared against — a scan failure
+          # whose trigger lived in an excluded file's synthesized RBS fired on the full run and vanished on
+          # the subset. Every environment and worker this run builds now takes the whole project.
+          source_files = project_files || files
+          return dispatch_pool(files, source_files: source_files) if pool_mode?
+
+          analyze_files_sequentially(
+            files, environment || resolve_sequential_environment(source_files: source_files)
+          )
         end
 
         def analyze_files_sequentially(files, environment)
@@ -130,6 +181,13 @@ module Rigor
           # first demand), so a snapshot taken beside the ones above — which run BEFORE `files.flat_map` —
           # would read an empty list on every run, including the ones this diagnostic exists for.
           record_definition_build_failures(environment&.rbs_loader&.definition_build_failures)
+          # Issue #784 — same timing contract, same reason: the HKT scan is first demanded from inside a
+          # file's analysis (the dispatcher's Singleton-receiver tier), so a snapshot taken any earlier
+          # would read nil on every run. And demanded HERE once more by the run itself, because a subset
+          # run (`--verify-incremental`'s partition, an incremental recheck's closure) may contain no file
+          # that demands it — the row must not depend on which files were analysed. See {#hkt_scan_outcome}
+          # for why a Rigor-owned demand is sound here where #696 forbids it.
+          record_hkt_scan_failure(hkt_scan_outcome(environment))
           if @collect_stats
             loader = environment.rbs_loader
             @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
@@ -156,7 +214,8 @@ module Rigor
             return
           end
 
-          loader = environment.rbs_loader
+          # nil-safe: the empty-closure path reaches here with no environment when the project has no files.
+          loader = environment&.rbs_loader
           @snapshots.synthesized_namespaces = loader&.synthesized_namespaces || []
           @snapshots.quarantined_signatures = loader&.quarantined_signatures || []
           @snapshots.env_build_failure = loader&.env_build_failure
@@ -220,20 +279,24 @@ module Rigor
         # An effects run (ADR-103 WD13) is pinned for exactly the same reason — the Ractor messages carry
         # no side-table channel — and degrades the same way. The degrade is sound rather than merely safe:
         # the sequential fallback still collects, so the effect graph is complete either way.
-        def dispatch_pool(files)
+        # @param source_files [Array<String>] the file list every worker's / the fallback's environment is
+        #   built over — the whole project (issue #793), defaulting to `files` for direct callers.
+        def dispatch_pool(files, source_files: files)
           if @record_dependencies || @record_effects
-            return analyze_files_in_fork_pool(files) if Process.respond_to?(:fork)
+            return analyze_files_in_fork_pool(files, source_files: source_files) if Process.respond_to?(:fork)
 
             return analyze_files_sequentially_fallback(
-              files, reason: "incremental parallelism requires fork; recording sequentially"
+              files, reason: "incremental parallelism requires fork; recording sequentially",
+                     source_files: source_files
             )
           end
           case pool_backend
-          when :ractor then analyze_files_in_pool(files)
-          when :fork   then analyze_files_in_fork_pool(files)
+          when :ractor then analyze_files_in_pool(files, source_files: source_files)
+          when :fork   then analyze_files_in_fork_pool(files, source_files: source_files)
           else
             analyze_files_sequentially_fallback(
-              files, reason: "fork-based parallelism is unavailable on this platform"
+              files, reason: "fork-based parallelism is unavailable on this platform",
+                     source_files: source_files
             )
           end
         end
@@ -299,7 +362,7 @@ module Rigor
         # worker touches comes back as an internal analyzer error. What the code below fixes is the
         # failure MODE, not the backend: the run used to hang forever instead of saying anything. Reviving
         # the backend needs an upstream change, which is why `pool_backend` keeps `fork` as the default.
-        def analyze_files_in_pool(files) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        def analyze_files_in_pool(files, source_files: files) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
           # Pre-warm class-level lazy memos on the MAIN Ractor. `Environment::ClassRegistry.default` is the
           # default kwarg threaded through `Environment.new` inside each worker session; lazy-initialising
           # it from a non-main Ractor would trip `Ractor::IsolationError`. Touching it here forces the
@@ -314,10 +377,28 @@ module Rigor
           # constants.
           if @cache_store.nil?
             return analyze_files_sequentially_fallback(
-              files, reason: "pool mode requires a cache_store (--no-cache disables pool)"
+              files, reason: "pool mode requires a cache_store (--no-cache disables pool)",
+                     source_files: source_files
             )
           end
-          prewarm_rbs_cache_for_pool
+          # Issue #798 — the SAME gap the fork pool had: this coordinator never analyses a file itself, so
+          # without an explicit read the project-signature state (`synthesized-namespace`,
+          # `quarantined-signature`, `environment-build-failed`, the conformance results) has no producer.
+          # Unlike the fork pool's copy-on-write children, a Ractor worker builds its OWN Environment
+          # inside its own isolated Ractor, so nothing here inherits what the coordinator's environment
+          # finds. `#prewarm_rbs_cache_for_pool` already builds and fully loads exactly this
+          # coordinator-side environment (to warm the cache before any worker spawns); it now hands it
+          # back so its RBS state can be read the same way the fork pool reads its pre-fork session
+          # environment. The conformance scan inside the snapshot demands the definition of every
+          # `rigor:v1:conforms-to` class — a demand no Ractor worker shares memory with — so a resulting
+          # definition-build failure is recorded explicitly right after, exactly as the empty-closure
+          # branch reads its own environment's demand (#788). No matching explicit call for the HKT-scan
+          # outcome: every worker already demands it from its OWN environment in `#drain_reporters`, and
+          # the scan has one outcome whoever demands it, so a worker's report already says what the
+          # coordinator's own demand would.
+          warm_env = prewarm_rbs_cache_for_pool
+          snapshot_project_signature_state(warm_env)
+          record_definition_build_failures(warm_env&.rbs_loader&.definition_build_failures)
 
           configuration = @configuration
           cache_root = @cache_store&.root
@@ -325,8 +406,9 @@ module Rigor
           explain = @explain
           # ADR-32 WD4 — the full project file list travels into every Ractor worker so each worker's
           # WorkerSession can invoke loaded plugins' source_rbs_synthesizers at env-build time. The list is
-          # a frozen Array<String>; cheaply shareable.
-          shareable_source_files = files.map { |path| path.to_s.dup.freeze }.freeze
+          # a frozen Array<String>; cheaply shareable. Issue #793 — it IS the full project now
+          # (`source_files`), not the analyzed subset this comment always described.
+          shareable_source_files = source_files.map { |path| path.to_s.dup.freeze }.freeze
 
           pool = Array.new(@workers) do
             Ractor.new(configuration, cache_root, blueprints, explain, shareable_source_files) do |configuration, cache_root, blueprints, explain, shareable_source_files| # rubocop:disable Layout/LineLength
@@ -397,15 +479,28 @@ module Rigor
           # The files no worker reported — every file of a worker that died, and any file in flight when
           # it did. Re-analysed in process, exactly as the fork backend re-analyses a dead child's slice.
           degraded = files.reject { |path| results_by_path.key?(path) }
-          unless degraded.empty?
-            environment = build_runner_environment(source_files: files)
-            degraded.each { |path| results_by_path[path] = @analyze_file.call(path, environment) }
-          end
+          reanalyze_degraded_in_process(degraded, results_by_path, source_files: source_files)
 
           diagnostics = Array(prepare_diagnostics) + files.flat_map { |path| results_by_path.fetch(path, []) }
           degraded.empty? ? diagnostics : diagnostics.unshift(pool_degraded_diagnostic(degraded.size, "ractor"))
         end
 
+        # The Ractor backend's degrade: the files of a worker that died are re-analysed on a LOCAL
+        # environment built over the whole project. That worker never sent `:done`, so nothing drains its
+        # reporters — and the local environment has no session to drain either — so the run-level state
+        # this analysis produced is taken here, exactly as the sequential fallback takes it: the
+        # definition-build failures the re-analysis demanded (#696) and the HKT-scan outcome, demanded
+        # once more by the run itself (#784 — a rescued scan failure otherwise vanished with the worker).
+        # The fork backend needs none of this: it re-analyses on the parent {WorkerSession} and drains it.
+        def reanalyze_degraded_in_process(degraded, results_by_path, source_files:)
+          return if degraded.empty?
+
+          environment = build_runner_environment(source_files: source_files)
+          degraded.each { |path| results_by_path[path] = @analyze_file.call(path, environment) }
+          record_definition_build_failures(environment.rbs_loader&.definition_build_failures)
+          record_hkt_scan_failure(hkt_scan_outcome(environment))
+        end
+
         # ADR-15 Amendment (2026-05-20) — fork-based worker pool, the active backend for `workers > 0`.
         # Builds ONE {WorkerSession} on the parent, then `fork`s N children that copy-on-write inherit it.
         # Each child analyses a contiguous slice of `files` and writes a Marshal'd `{results:, reporters:}`
@@ -418,7 +513,11 @@ module Rigor
         #
         # A child that exits non-zero (crash / unmarshalable payload) is degraded: the parent re-analyses
         # that slice in-process and prepends a `pool-degraded` warning.
-        def analyze_files_in_fork_pool(files) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        #
+        # Also snapshots the project-signature state and the effect-annotation carrier off the pre-fork
+        # `session.environment` before any child spawns (#798) — the only environment this backend's
+        # coordinator ever holds, and so the only place those diagnostic rows can be read from.
+        def analyze_files_in_fork_pool(files, source_files: files) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
           Environment::ClassRegistry.default
 
           session = WorkerSession.new(
@@ -429,12 +528,27 @@ module Rigor
             synthetic_method_index: synthetic_method_index,
             project_patched_methods: project_patched_methods,
             project_scope_seed: project_scope_seed,
-            source_files: files,
+            source_files: source_files,
             record_dependencies: @record_dependencies
           )
           # Force the full RBS load on the parent so children copy-on-write inherit a warm Environment
           # rather than each rebuilding it after the fork.
           session.environment.rbs_loader&.prewarm
+          # Issue #798 — same set, same ORDER as the sequential path (docs/type-specification/
+          # diagnostic-policy.md § `rbs.coverage.*`): the project-signature state
+          # (`synthesized-namespace`, `quarantined-signature`, `environment-build-failed`, the
+          # conformance results) has no per-file producer, so this coordinator-side environment is the
+          # only place a pooled run can take it from — exactly as the empty-closure branch above is the
+          # only place an empty run can (#788). Taken BEFORE the fork below: the conformance scan this
+          # runs demands the definition of every `rigor:v1:conforms-to` class, and doing that HERE means
+          # a resulting definition-build failure is already sitting in the parent's loader at the moment
+          # each child copy-on-write-inherits it — every child's own `#drain_reporters` then reports it
+          # right alongside whatever its own slice demanded, with no separate plumbing needed. Left
+          # unconditional, unlike `#snapshot_fork_pool_stats` below: these are diagnostic rows, not
+          # `RunStats` telemetry, and the stats gate must not decide which diagnostics a run reports (a
+          # `--workers N --no-stats` run used to say strictly LESS than the sequential path over the
+          # same project).
+          snapshot_project_signature_state(session.environment)
           snapshot_effect_annotation_carrier(session.environment.rbs_loader)
           snapshot_fork_pool_stats(session) if @collect_stats
 
@@ -488,18 +602,16 @@ module Rigor
           exit!(1)
         end
 
-        # Snapshots `class_decl_paths` from the parent session's loader so end-of-run {RunStats} can
-        # attribute the RBS class universe.
+        # Issue #798 — `RunStats` telemetry ONLY, now that `#snapshot_project_signature_state` (called
+        # unconditionally above) owns every diagnostic-bearing slot this method used to ALSO write
+        # (`quarantined_signatures`, `env_build_failure`): those must not be gated on `@collect_stats`, and
+        # this method's own name says what is left — `class_decl_paths` / `signature_paths`, read off the
+        # parent session's loader so end-of-run {RunStats} can attribute the RBS class universe, which a
+        # `--no-stats` run legitimately skips.
         def snapshot_fork_pool_stats(session)
           loader = session.environment.rbs_loader
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
           @snapshots.signature_paths = loader&.signature_paths || [].freeze
-          # The workers each quarantine the same broken file, but they report no diagnostics for it — the row is
-          # a whole-run one. Read it off the parent session's loader so a pooled run says exactly what a
-          # sequential one says. The same reasoning holds for a total env-build failure.
-          @snapshots.quarantined_signatures =
-            project_signature_paths? ? (loader&.quarantined_signatures || []) : []
-          @snapshots.env_build_failure = project_signature_paths? ? loader&.env_build_failure : nil
         end
 
         # Waits for every forked child, merges each successful payload into `results_by_path`, and returns
@@ -545,9 +657,10 @@ module Rigor
 
         # ADR-15 Phase 4b.x — drives every cached RBS producer on the main Ractor so each worker can serve
         # all reflection queries from disk (Marshal-load only). Builds a single coordinator-side
-        # {Environment} for this purpose; the env object is discarded immediately after the cache is warm
-        # — workers build their own `Environment.for_project` inside the Ractor body, which then routes
-        # through `cached_env` instead of `RBS::EnvironmentLoader.new`.
+        # {Environment} for this purpose and returns it fully loaded — issue #798: the caller also reads
+        # the project-signature state off it, since it is the only environment this backend's coordinator
+        # ever holds. Workers still build their OWN `Environment.for_project` inside the Ractor body, which
+        # then routes through `cached_env` instead of `RBS::EnvironmentLoader.new`.
         def prewarm_rbs_cache_for_pool
           warm_env = Environment.for_project(
             libraries: @configuration.libraries,
@@ -560,14 +673,18 @@ module Rigor
             rbs_collection_auto_detect: @configuration.rbs_collection_auto_detect
           )
           warm_env.rbs_loader&.prewarm
+          warm_env
         end
 
         # ADR-15 Phase 4b.x — pool-mode safety net. When pool mode is configured but a precondition fails
         # (currently: `--no-cache` would force workers through `EnvironmentLoader.new`), degrade to
         # sequential analysis with a `:warning` `pool-degraded` diagnostic at run start. The actual
         # per-file analysis runs on the coordinator, identical to the default sequential path.
-        def analyze_files_sequentially_fallback(files, reason:)
-          environment = build_runner_environment
+        # @param source_files [Array<String>] issue #793 — the whole project, so this path's environment
+        #   carries the same plugin-synthesized RBS the pool workers' would. It used to build over `[]`,
+        #   i.e. with no synthesized RBS at all, even on a full run.
+        def analyze_files_sequentially_fallback(files, reason:, source_files: files)
+          environment = build_runner_environment(source_files: source_files)
           snapshot_effect_annotation_carrier(environment.rbs_loader)
           diagnostics = files.flat_map { |path| @analyze_file.call(path, environment) }
           loader = environment.rbs_loader
@@ -576,6 +693,10 @@ module Rigor
           # `fork` is unavailable (Windows) and on `--incremental` / effects runs without it: a run that
           # degraded to sequential must not also report less than a sequential run would.
           record_definition_build_failures(loader&.definition_build_failures)
+          # Issue #784 — same reasoning: this path's Environment IS the one that reached the scan, so it
+          # must snapshot the slot too, or a run that degraded to sequential would report less than a
+          # sequential run would. Demanded once by the run as well, for the reason at the sequential site.
+          record_hkt_scan_failure(hkt_scan_outcome(environment))
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze
           @snapshots.signature_paths = loader&.signature_paths || [].freeze
           @snapshots.quarantined_signatures =
@@ -591,17 +712,7 @@ module Rigor
         end
 
         def merge_worker_reporters(drained)
-          rbs = drained.fetch(:rbs_extended)
-          rbs.fetch(:unresolved_payloads).each do |entry|
-            @rbs_extended_reporter.record_unresolved(
-              payload: entry.payload, source_location: entry.source_location
-            )
-          end
-          rbs.fetch(:lossy_projections).each do |entry|
-            @rbs_extended_reporter.record_lossy_projection(
-              head: entry.head, source_location: entry.source_location
-            )
-          end
+          merge_rbs_extended_reporter(drained.fetch(:rbs_extended))
           drained.fetch(:boundary_cross).each do |entry|
             @boundary_cross_reporter.record(
               class_name: entry.class_name,
@@ -619,10 +730,42 @@ module Rigor
           end
           # Issue #696. Fetched with a default so an older drain stays compatible, exactly as the line above.
           record_definition_build_failures(drained[:definition_build_failures])
+          # Issue #784. `Hash#[]` is already a nil default, exactly as `env_build_failure` is snapshotted
+          # elsewhere — an older drain shape simply has no key and records nothing.
+          record_hkt_scan_failure(drained[:hkt_scan_failure])
         end
 
         private
 
+        # Replays one worker's three {RbsExtended::Reporter} streams into the run's own reporter.
+        #
+        # `hkt_directive_errors` (issue #785) is read with `Hash#[]`'s nil default rather than `fetch`,
+        # exactly as `source_rbs_synthesis` is, so an older drain shape simply records nothing.
+        #
+        # All three streams replay by their `(path, line, column)` primitives (#785 for the hkt stream, #805
+        # for its two elders). Every worker reads the same `.rbs`, so each hands over the same entries, and
+        # only a primitive-keyed dedup collapses them back to the single row a `--workers=0` run prints — an
+        # `RBS::Location` compares equal only against a location over the same `RBS::Buffer` object, so a
+        # location-keyed one would print N copies at `--workers=N`. The entries could not reach here carrying
+        # a location anyway: the drain Marshals its payload and an `RBS::Location` has no `_dump`.
+        def merge_rbs_extended_reporter(rbs)
+          rbs.fetch(:unresolved_payloads).each do |entry|
+            @rbs_extended_reporter.record_unresolved(
+              payload: entry.payload, path: entry.path, line: entry.line, column: entry.column
+            )
+          end
+          rbs.fetch(:lossy_projections).each do |entry|
+            @rbs_extended_reporter.record_lossy_projection(
+              head: entry.head, path: entry.path, line: entry.line, column: entry.column
+            )
+          end
+          Array(rbs[:hkt_directive_errors]).each do |entry|
+            @rbs_extended_reporter.record_hkt_error(
+              message: entry.message, path: entry.path, line: entry.line, column: entry.column
+            )
+          end
+        end
+
         # Issue #696 — accumulate the per-class `RBS::DefinitionBuilder` failures this run observed, deduped
         # by class name and kept in first-seen order.
         #
@@ -646,6 +789,48 @@ module Rigor
             (@snapshots.definition_build_failures + failures).uniq(&:first).freeze
         end
 
+        # Issue #784 — first-wins, unlike {#record_definition_build_failures}'s accumulate-and-dedup. That
+        # method accumulates because each pool WORKER owns its own loader and its own per-class memo, so a
+        # collapsed class can genuinely be observed by only some workers and the run's set is the union.
+        # The HKT scan has no such per-worker variation: `Environment#hkt_registry` builds from the SAME
+        # `signature_paths:` overlay every worker was handed, so every worker that demands it either all
+        # raise identically or all succeed — there is only ever one tuple to record, and `||=` is correct
+        # (and cheap) rather than an accumulate-and-dedup this slot never needs.
+        def record_hkt_scan_failure(tuple)
+          @snapshots.hkt_scan_failure ||= tuple
+        end
+
+        # Issue #784 — demand the registry once on behalf of the run, then read the slot. The seam in
+        # {Environment#hkt_registry} is demand-driven, and nothing guarantees any analysed file demands it:
+        # a `--verify-incremental` partition or an incremental closure can miss every `Klass.method` call,
+        # and then the slot is nil after the loop and the run says nothing — while `--incremental` has also
+        # dropped the row from its per-file cache. Demanding here makes the outcome a property of the RUN,
+        # not of which files happened to be in it.
+        #
+        # This is sound where #696's "a demand that is Rigor's own MUST NOT contribute" is not, and the
+        # difference is the shape of what is recorded. #696 reports a per-class LIST whose membership is
+        # "the classes the analysis demanded"; a Rigor-internal demand adds classes the user never asked
+        # about and makes that list vary with configuration. The HKT scan is ONE build with ONE outcome —
+        # the same tuple whoever demands it — so an extra demand cannot change what is reported, only
+        # guarantee it is observed.
+        #
+        # What it costs, stated plainly because {#record_definition_build_failures}'s comment promises
+        # "nothing is forced here": the demand DOES force the RBS env build when the environment has not
+        # built it yet (the scan reads the loader). On every path that reaches this method that build is
+        # either already done (the loop demanded it) or the same load one analysed file would have paid:
+        # a Marshal load when a cache store exists, the parse a full run pays under `--no-cache`. Never a
+        # build on a project with no files (see {#analyze_files}). Memoised, so on a reused Environment
+        # this is a hash read.
+        #
+        # @param environment [Rigor::Environment, nil]
+        # @return [Array, nil] the recorded tuple, or nil (no environment, or the scan built)
+        def hkt_scan_outcome(environment)
+          return nil if environment.nil?
+
+          environment.hkt_registry
+          environment.hkt_scan_failure
+        end
+
         # True when the project declares its own `signature_paths:` (the only place the
         # qualified-name-without-namespace mistake lives).
         def project_signature_paths?

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

@@ -17,7 +17,8 @@ module Rigor
       class RunSnapshots
         attr_accessor :class_decl_paths, :signature_paths,
                       :synthesized_namespaces, :quarantined_signatures, :conformance_results,
-                      :env_build_failure, :definition_build_failures, :effect_annotation_carrier
+                      :env_build_failure, :definition_build_failures, :hkt_scan_failure,
+                      :effect_annotation_carrier
 
         # Constructor defaults match the {Runner} constructor: the pre-seed values `build_run_stats` /
         # `pre_file_diagnostics` read before the first analysis path runs are frozen empties. The
@@ -25,7 +26,9 @@ module Rigor
         # `[error_class, first_line, buffer_names]` tuple or nothing. Its per-class sibling
         # `definition_build_failures` (#696) holds a LIST, because a collapsed universe fails many classes,
         # and is accumulated ACROSS pool workers rather than assigned once — see
-        # {PoolCoordinator#merge_worker_reporters}.
+        # {PoolCoordinator#merge_worker_reporters}. `hkt_scan_failure` (#784) is nil-or-tuple like
+        # `env_build_failure`, not a list like `definition_build_failures`: the scan is ONE build over the
+        # whole `signature_paths:` overlay, not a per-class one, so it has exactly one outcome per run.
         def initialize
           @class_decl_paths = {}.freeze
           @signature_paths = [].freeze
@@ -34,6 +37,7 @@ module Rigor
           @conformance_results = [].freeze
           @env_build_failure = nil
           @definition_build_failures = [].freeze
+          @hkt_scan_failure = nil
           @effect_annotation_carrier = [].freeze
         end
 
@@ -47,6 +51,7 @@ module Rigor
           @conformance_results = []
           @env_build_failure = nil
           @definition_build_failures = []
+          @hkt_scan_failure = nil
           @effect_annotation_carrier = [].freeze
         end
       end

data/lib/rigor/analysis/runner.rb

@@ -29,6 +29,7 @@ require_relative "../inference/scope_indexer"
 require_relative "../inference/synthetic_method_scanner"
 require_relative "../inference/project_patched_scanner"
 require_relative "../inference/method_dispatcher/file_folding"
+require_relative "crash_signature"
 require_relative "buffer_binding"
 require_relative "check_rules"
 require_relative "dependency_recorder"
@@ -64,7 +65,14 @@ module Rigor
 
       attr_reader :cache_store, :plugin_registry, :dependency_source_index,
                   :rbs_extended_reporter, :boundary_cross_reporter,
-                  :analyzed_files, :unresolved_self_calls, :seed_bundles
+                  :analyzed_files, :unresolved_self_calls, :seed_bundles,
+                  # #788 rounds 6–7 — the rows per-file analysis produced this run, severity-resolved exactly
+                  # as the run's stream is and sliced to this run's targets (a pool backend folds `.rigor.yml`
+                  # prepare / degraded rows into `analyze_files`'s return). `IncrementalSession` caches ONLY
+                  # this and serves reused files from it without re-stamping: a run-level row is regenerated
+                  # every run wherever it is positioned, and slicing the run's full stream by path cached the
+                  # file-positioned ones (`effect.annotations-unchecked`, `source-rbs-*`).
+                  :per_file_diagnostics
 
       # ADR-46 — the per-file cross-file read records this run captured (empty unless
       # `record_dependencies: true`). Sequential analysis records into `@file_dependencies` via
@@ -302,6 +310,7 @@ module Rigor
         # See `self_undefined_rule_active?`.
         @self_undefined_rule_active = nil
         @analyzed_files = [].freeze
+        @per_file_diagnostics = [].freeze
         # In-memory source map for `#run_source` — `{ logical_path => source String }`. When set,
         # `parse_source` reads bytes from here instead of disk and `expand_paths` accepts the (possibly
         # non-existent) logical path. nil on a normal disk-backed run.
@@ -426,6 +435,9 @@ module Rigor
         # Per-run reset of the environment the cacheable path resolves, reused by the envelope pass so a
         # run never builds two.
         @run_environment = nil
+        # #788 — the per-file reader is assigned only on the analysis (miss) path; reset it here so a run the
+        # ADR-45 result cache serves does not answer with the previous run's rows.
+        @per_file_diagnostics = [].freeze
         # ADR-84 WD2 — roll the return-memo bucket: a fresh frozen token per run makes every per-file scope
         # of THIS run share one memo bucket while entries from any earlier run in this process (stale after
         # an edit) become unreachable.
@@ -674,7 +686,14 @@ module Rigor
         @run_generation = Object.new.freeze
         run_project_pre_passes(expansion: expansion)
         ensure_project_discovery(expansion)
-        environment = @pool_coordinator.resolve_sequential_environment(source_files: target_files(expansion))
+        # Issue #795 — `source_files:` is the WHOLE project's file list, never `target_files(expansion)`.
+        # `IncrementalSession#build_runner` threads its own `@buffer` into this Runner, so in editor-buffer
+        # mode `target_files` narrows to the buffer's single logical path; an environment built over just
+        # that path drops every OTHER file's plugin-synthesized virtual RBS, which can flip a re-evaluated
+        # return descriptor and wrongly declare a caller's return type unstable (or stable) relative to the
+        # full-project answer. This probe never analyzes a file, so it carries none of #788's per-file-cache
+        # duplication concern either.
+        environment = @pool_coordinator.resolve_sequential_environment(source_files: expansion.fetch(:files))
         specs.to_h do |spec|
           [[spec[:class_name], spec[:method_name], spec[:singleton]], evaluate_spec_returns(spec, environment)]
         end
@@ -927,9 +946,19 @@ module Rigor
         ).diagnostics
       end
 
+      # Issue #795 — `source_files:` is the WHOLE project's file list (`expansion.fetch(:files)`), never
+      # `target_files(expansion)`. A subset or editor-buffer run's `target_files` narrows to the
+      # `analyze_only` closure or the buffer's single logical path; building the envelope walk's
+      # environment over that subset drops every plugin-synthesized virtual RBS from an excluded file, so
+      # an envelope declared only in that file's inline annotation is invisible to the walk — the same #793
+      # gap #788 closed for per-file analysis, left open here because #788's binding sentences scoped
+      # themselves to "the environments the per-file analysis builds". This path is exempt from #788's
+      # per-file-cache duplication concern: `effect.unknown-label` (and its envelope-pass siblings) are
+      # produced by this pass, never by `Runner#per_file_diagnostics`, so `IncrementalSession` never caches
+      # them and widening this source list cannot duplicate a row on recheck.
       def envelope_rbs_loader(expansion)
         environment = @run_environment ||
-                      @pool_coordinator.resolve_sequential_environment(source_files: target_files(expansion))
+                      @pool_coordinator.resolve_sequential_environment(source_files: expansion.fetch(:files))
         environment&.rbs_loader
       rescue StandardError
         nil
@@ -985,7 +1014,17 @@ module Rigor
         # per-file cache, so it needs the full analyzed set to subtract the affected closure from.
         targets = target_files(expansion)
         @analyzed_files = targets
-        diagnostics += @pool_coordinator.analyze_files(targets, environment: environment)
+        # Issue #784 — the whole project's file list rides along so an EMPTY `targets` (a narrowed run whose
+        # closure is empty) can still resolve the environment a full run would — same files, same
+        # synthesized RBS — to demand the HKT registry once, while a project with no files resolves nothing.
+        # #788 rounds 6–7 — the per-file stream is kept apart from the run-level streams appended below,
+        # because `IncrementalSession` must cache ONLY what per-file analysis produced (#per_file_diagnostics),
+        # and the reader is exposed SEVERITY-RESOLVED and sliced to this run's targets. The cache serves a
+        # reused file without re-stamping, so a raw row would resurrect a rule the profile resolves to `:off`
+        # (`static.value-use.void` ships off on the default profile) and serve the authored severity where an
+        # override re-stamps it; and a pool backend folds `.rigor.yml`-positioned prepare / pool-degraded rows
+        # into the same return, which the slice drops. The run's own stream is stamped once, at the end.
+        diagnostics += analyze_targets(targets, environment: environment, project_files: expansion.fetch(:files))
         # ADR-103 WD12 — the effect fixpoint, in the post-pool aggregation slot beside the conformance
         # results. Graph-only over a finite lattice, so it is a plain worklist to a true fixpoint; it
         # contributes NO diagnostics and its result leaves through `#effect_table`, never through the
@@ -993,10 +1032,14 @@ module Rigor
         close_effect_graph
         diagnostics += @diagnostic_aggregator.rbs_quarantined_signature_diagnostics
         diagnostics += @diagnostic_aggregator.rbs_environment_build_failed_diagnostics
-        # Issue #696 — after its env-wide twin and before the synthesized-namespace notice: the three
+        # Issue #696 — after its env-wide twin and before the synthesized-namespace notice: the four
         # `rbs.coverage.*` build conditions surface widest-consequence first, and their relative order is
         # the diagnostic output contract.
         diagnostics += @diagnostic_aggregator.rbs_definition_build_failed_diagnostics
+        # Issue #784 — last of the four, deliberately: it loses only the IMPLICIT HKT registrations a
+        # `type` alias would have contributed, never a class's own declared method surface, so it is the
+        # narrowest-consequence rung on the same ladder.
+        diagnostics += @diagnostic_aggregator.rbs_hkt_scan_failed_diagnostics
         diagnostics += @diagnostic_aggregator.rbs_synthesized_namespace_diagnostics
         diagnostics += @diagnostic_aggregator.conforms_to_diagnostics
         diagnostics += @diagnostic_aggregator.rbs_extended_reporter_diagnostics
@@ -1004,6 +1047,21 @@ module Rigor
         diagnostics + @diagnostic_aggregator.source_rbs_synthesis_diagnostics
       end
 
+      # #788 round 7 — runs per-file analysis over `targets` and exposes what it produced as
+      # `#per_file_diagnostics`: the `analyze_files` return, stamped with the same severity profile the run's
+      # own stream gets (`SeverityStamp` drops `:off` rows and re-stamps overrides, and the per-file cache never
+      # re-stamps), sliced to the rows positioned at the targets. Returns the RAW return for the run's stream,
+      # which is stamped once, at the end of `#run_analysis`.
+      def analyze_targets(targets, environment:, project_files:)
+        raw = @pool_coordinator.analyze_files(targets, environment: environment, project_files: project_files)
+        analysed = targets.to_set
+        @per_file_diagnostics = @diagnostic_aggregator.apply_severity_profile(raw)
+                                                      .select { |diagnostic| analysed.include?(diagnostic.path) }
+                                                      .freeze
+        raw
+      end
+      private :analyze_targets
+
       # ADR-67 WD6a — the check-walk parameter-inference pre-pass. Populates `@project_param_inferred_types`
       # (read by `project_scope_seed_tables`) with the call-site union of every undeclared parameter, running
       # ONE round (a single hop of call-site → param typing; the protection scan's three-round fixpoint stays a
@@ -1427,7 +1485,7 @@ module Rigor
       # indexes, prepare-diagnostic snapshot, and the four end-of-pass snapshots) is reached through reader
       # procs so each collaborator observes the live ivar value at call time without a back-reference
       # cycle. The reporter accumulators and the {RunSnapshots} sink are shared mutable instances.
-      def build_collaborators # rubocop:disable Metrics/MethodLength
+      def build_collaborators # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         @pre_passes = ProjectPrePasses.new(
           configuration: @configuration, cache_store: @cache_store, buffer: @buffer,
           plugin_requirer: @plugin_requirer, pool_mode: -> { pool_mode? }
@@ -1462,6 +1520,7 @@ module Rigor
           quarantined_signatures_snapshot: -> { @snapshots.quarantined_signatures },
           env_build_failure_snapshot: -> { @snapshots.env_build_failure },
           definition_build_failures_snapshot: -> { @snapshots.definition_build_failures },
+          hkt_scan_failure_snapshot: -> { @snapshots.hkt_scan_failure },
           conformance_results_snapshot: -> { @snapshots.conformance_results }
         )
       end
@@ -1876,7 +1935,7 @@ module Rigor
             path: path,
             line: 1,
             column: 1,
-            message: "internal analyzer error: #{e.class}: #{e.message}",
+            message: CrashSignature.check_rule_message(e),
             severity: :error
           )
         ]