rigortype 0.3.6 → 0.3.8

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

@@ -115,17 +115,79 @@ 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)
           snapshot_project_signature_state(environment)
           snapshot_effect_annotation_carrier(environment&.rbs_loader)
           result = files.flat_map { |path| @analyze_file.call(path, environment) }
+          # Issue #696 — AFTER the loop, deliberately. Definition builds are lazy (ADR-54 WD1: per class, on
+          # 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
@@ -152,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
@@ -216,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
@@ -295,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
@@ -310,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
@@ -321,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
@@ -393,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:}`
@@ -414,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(
@@ -425,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
 
@@ -484,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
@@ -541,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,
@@ -556,17 +673,30 @@ 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
+          # Issue #696 — this path analyses on the coordinator, so its loader IS the one that reached the
+          # failing build, and it must snapshot the same slot the two real paths do. Reached whenever
+          # `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 =
@@ -582,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,
@@ -608,10 +728,109 @@ module Rigor
               plugin_id: entry.plugin_id, path: entry.path, message: entry.message
             )
           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.
+        #
+        # Accumulating rather than assigning is what makes a pooled run say what a sequential one says: each
+        # worker holds its OWN loader and its own memo (the `@state` that also gates the stderr banner, which
+        # is why the banner repeats per worker — #295), so a class that fails in two workers arrives twice
+        # and a class only one worker touched arrives once. The union over the workers is the set the RUN
+        # hit; neither worker alone is.
+        #
+        # NOT gated on `project_signature_paths?`, unlike {#snapshot_project_signature_state}. That gate
+        # exists because each condition there forces the otherwise-lazy env build, which would warm the cache
+        # on a project with no sig set of its own. Nothing is forced here — this reads what the analysis
+        # already demanded — and the failure is not a project-sig-only condition anyway: two BUNDLED sources
+        # declaring the same method collapse a class with no `signature_paths:` in sight (the
+        # `bigdecimal` / `BigMath` shape, #299). Gating it would suppress exactly the variant the user cannot
+        # fix by editing their own `sig/`.
+        def record_definition_build_failures(failures)
+          return if failures.nil? || failures.empty?
+
+          @snapshots.definition_build_failures =
+            (@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/project_pre_passes.rb

@@ -53,17 +53,11 @@ module Rigor
         # consumes them and so never pays the double parse (see {#discover} + `Runner#ensure_project_discovery`).
         # The slot names mirror the discovery half of {Result} exactly.
         Discovery = Data.define(
-          :discovered_classes,
-          :discovered_def_nodes,
-          :discovered_singleton_def_nodes,
-          :discovered_def_sources,
-          :discovered_singleton_def_sources,
-          :discovered_superclasses,
-          :discovered_includes,
-          :discovered_class_sources,
-          :discovered_method_visibilities,
-          :discovered_methods,
-          :data_member_layouts,
+          :discovered_classes, :discovered_def_nodes, :discovered_def_nestings,
+          :discovered_singleton_def_nodes, :discovered_def_sources, :discovered_singleton_def_sources,
+          :discovered_superclasses, :discovered_header_nestings, :discovered_includes,
+          :discovered_class_sources, :constant_values, :constant_sources, :constant_writes,
+          :discovered_method_visibilities, :discovered_methods, :data_member_layouts,
           :struct_member_layouts
         )
 
@@ -156,12 +150,22 @@ module Rigor
           Discovery.new(
             discovered_classes: index.fetch(:classes),
             discovered_def_nodes: def_index.fetch(:def_nodes),
+            # Issue #681 — the recorded `Module.nesting` per declared `def`, so a callee's body re-walk
+            # resolves its constants the way the declaration that owns it does.
+            discovered_def_nestings: def_index.fetch(:def_nestings),
             discovered_singleton_def_nodes: def_index.fetch(:singleton_def_nodes),
             discovered_def_sources: def_index.fetch(:def_sources),
             discovered_singleton_def_sources: def_index.fetch(:singleton_def_sources),
             discovered_superclasses: def_index.fetch(:superclasses),
+            # Issue #682 — the nesting each declaration header is written in, so an ancestor name resolves in
+            # the cref Ruby resolves it in rather than by peeling the subclass's own qualified name.
+            discovered_header_nestings: def_index.fetch(:header_nestings),
             discovered_includes: def_index.fetch(:includes),
             discovered_class_sources: def_index.fetch(:class_sources),
+            # Issue #644 — the cross-file value-constant publication table and its write attribution.
+            constant_values: def_index.fetch(:constant_values),
+            constant_sources: def_index.fetch(:constant_sources),
+            constant_writes: def_index.fetch(:constant_writes),
             discovered_method_visibilities: def_index.fetch(:method_visibilities),
             discovered_methods: def_index.fetch(:methods),
             data_member_layouts: def_index.fetch(:data_member_layouts),

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

@@ -17,12 +17,18 @@ module Rigor
       class RunSnapshots
         attr_accessor :class_decl_paths, :signature_paths,
                       :synthesized_namespaces, :quarantined_signatures, :conformance_results,
-                      :env_build_failure, :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
         # `env_build_failure` slot is nil (no failure) rather than an empty collection — it holds a single
-        # `[error_class, first_line, buffer_names]` tuple or nothing.
+        # `[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}. `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
@@ -30,6 +36,8 @@ module Rigor
           @quarantined_signatures = [].freeze
           @conformance_results = [].freeze
           @env_build_failure = nil
+          @definition_build_failures = [].freeze
+          @hkt_scan_failure = nil
           @effect_annotation_carrier = [].freeze
         end
 
@@ -42,6 +50,8 @@ module Rigor
           @quarantined_signatures = []
           @conformance_results = []
           @env_build_failure = nil
+          @definition_build_failures = []
+          @hkt_scan_failure = nil
           @effect_annotation_carrier = [].freeze
         end
       end