rigortype 0.4.2 → 0.4.4

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

@@ -8,6 +8,7 @@ require_relative "../../inference/synthetic_method_scanner"
 require_relative "../../inference/project_patched_scanner"
 require_relative "../dependency_source_inference"
 require_relative "../project_scan"
+require_relative "../worker_session"
 require_relative "../template_units"
 require_relative "../template_unit_collector"
 
@@ -59,7 +60,7 @@ module Rigor
           :unpositioned_mixins, :discovered_class_sources, :constant_values, :constant_sources, :constant_writes,
           :discovered_method_visibilities, :discovered_methods, :discovered_parameter_envelopes, :data_member_layouts,
           :struct_member_layouts, :discovered_deferred_ranges, :discovered_refinements, :siblings,
-          :discovered_global_write_census
+          :discovered_global_write_census, :singleton_class_sources
         )
 
         # Internal: drives every EAGER project-wide pre-pass — the ones whose products feed the RBS
@@ -175,6 +176,8 @@ module Rigor
             # object's `extend`s reach `Narrowing` from a sibling file the way its `include`s already do.
             discovered_extends: def_index.fetch(:extends), unpositioned_mixins: def_index.fetch(:unpositioned_mixins),
             discovered_class_sources: def_index.fetch(:class_sources),
+            # Issue #1752 — the files opening `class << Const`, for the class-declaration diff alone.
+            singleton_class_sources: def_index.fetch(:singleton_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),
@@ -251,6 +254,35 @@ module Rigor
           registry
         end
 
+        # Issue #1541 — what a pooled run's workers would have produced from `#prepare`, for the coordinator's
+        # empty-closure branch, which dispatches none: the `#prepare` error rows and the run-scoped
+        # registrations (`#disclose_once` / `#emit_once`) made there. It runs on a THROWAWAY registry, so
+        # nothing `#prepare` records on a plugin instance reaches the coordinator-side instances
+        # {DiagnosticAggregator} reads; issue #1900 — the trust refusals are therefore handed back too, in
+        # the shape {Analysis::WorkerSession#drain_trust_refusals} gives a pooled cold run's.
+        # Returns the rows first, then the disclosure records, then the refusals.
+        def prepare_throwaway_registry
+          registry = load_plugins
+          # Issue #1900 — `#init` already ran (in `load_plugins`) and its refusals are the coordinator-side
+          # registry's to report, so only what `#prepare` refuses from here on is handed back.
+          baseline = WorkerSession.refusal_counts(registry)
+          rows = plugin_prepare_diagnostics(registry)
+          records = registry.plugins.flat_map do |plugin|
+            plugin_id = safe_plugin_id(plugin)
+            Array(plugin.run_disclosure_records).map { |record| record.merge(plugin_id: plugin_id) }
+          rescue StandardError
+            []
+          end
+          [rows, records, trust_refusals(registry, baseline)]
+        end
+
+        # Issue #1900 — `#prepare` on `plugin_registry` itself, returning its error rows. For the pool
+        # coordinator's sequential fallback, which analyses on the coordinator-side registry that {#run}
+        # left unprepared because the run is in pool mode.
+        def prepare_registry(plugin_registry)
+          plugin_prepare_diagnostics(plugin_registry)
+        end
+
         # Returns the per-run shared `Plugin::FactStore` instance. All loaded plugins share this store
         # through their respective `Plugin::Services` (the same instance is threaded by
         # `Plugin::Loader.load`). Returns `nil` when no plugins are loaded.
@@ -262,6 +294,19 @@ module Rigor
 
         private
 
+        def trust_refusals(registry, baseline)
+          registry.plugins.filter_map do |plugin|
+            summary = plugin.io_boundary.refusal_summary
+            next nil if summary.nil?
+
+            plugin_id = safe_plugin_id(plugin)
+            delta = summary[:count] - baseline.fetch(plugin_id, 0)
+            summary.merge(count: delta, plugin_id: plugin_id) if delta.positive?
+          rescue StandardError
+            nil
+          end
+        end
+
         def pool_mode?
           @pool_mode_reader.call
         end

data/lib/rigor/analysis/runner.rb

@@ -297,8 +297,14 @@ module Rigor
                      record_dependencies: false, record_self_calls: false, analyze_only: nil,
                      seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
                      discovery_seed: nil, no_tolerated_effects: false,
-                     restored_run_level_rows: nil, served_per_file_diagnostics: nil)
+                     restored_run_level_rows: nil, served_per_file_diagnostics: nil, served_effect_collections: nil,
+                     on_file_indexed: nil)
         @configuration = configuration
+        # ADR-113 WD2 — `rigor lens` reads a target's seeded index here: called with `(path, parse_result, scope,
+        # index)` for every file this process indexes, after its rules ran and inside the run window, so the reader
+        # sees what `check` saw. A pooled file is indexed in a worker and never reaches it; the incremental session
+        # analyses forced targets with `workers: 0` for that reason.
+        @on_file_indexed = on_file_indexed
         # Issues #796 / #794 — the previous full run's run-level rows, supplied only by
         # {IncrementalSession} on a narrowed run; see {PoolCoordinator#replay_restored_run_level_rows}.
         @restored_run_level_rows = restored_run_level_rows
@@ -306,6 +312,10 @@ module Rigor
         # narrowed run does not analyse, spliced into this run's per-file stream by
         # {#interleave_served_diagnostics}. Empty on every other run.
         @served_per_file_diagnostics = served_per_file_diagnostics || {}
+        # Issue #1898 — `{path => FileCollection}` the {IncrementalSession} serves for the same unanalysed files, so the
+        # effect graph this run closes (and the envelope pass judges) spans the whole project, not just the closure.
+        # Never part of {#effect_collections_by_path}, which stays what THIS run collected. Empty on every other run.
+        @served_effect_collections = served_effect_collections || {}
         @explain = explain
         @cache_store = enforce_read_only_cache(cache_store, buffer)
         @plugin_requirer = plugin_requirer
@@ -431,6 +441,7 @@ module Rigor
         # Issue #1367 — the project's `Inference::GlobalWriteCensus`, which the `global.*` write rules read.
         @project_discovered_global_write_census = Set.new.freeze
         @project_discovered_class_sources = {}.freeze
+        @project_singleton_class_sources = {}.freeze
         # Issue #644 — the cross-file VALUE-constant publication table (`{qualified name => Type::Constant}`,
         # literal writes only) and its per-name write attribution. The first seeds `in_source_constants` on
         # every per-file scope so `FOO = :sym` in one file reads as `:sym` in another; the second seeds
@@ -648,8 +659,8 @@ module Rigor
       # subclasses (`subclass_of:<last segment>`).
       def class_declarations
         result = Hash.new { |hash, key| hash[key] = Set.new }
-        @project_discovered_class_sources.each do |class_name, files|
-          files.each { |file| result[file] << class_name }
+        [@project_discovered_class_sources, @project_singleton_class_sources].each do |sources|
+          sources.each { |class_name, files| files.each { |file| result[file] << class_name } }
         end
         Incremental.add_superclass_edges(result, @project_discovered_class_sources, @project_discovered_superclasses)
         result.transform_values(&:freeze).freeze
@@ -845,7 +856,8 @@ module Rigor
         analysis = serve_effect_collections(expansion, environment, key_descriptor, rbs_descriptor)
         computed = false
         diagnostics = @cache_store.fetch_or_validate(
-          producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID, key_descriptor: key_descriptor,
+          producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID,
+          key_descriptor: RunCacheKey.with_roots(key_descriptor, expansion.fetch(:roots)),
           generation_cap: RunCacheKey::GENERATION_CAP
         ) do
           computed = true
@@ -1374,7 +1386,8 @@ module Rigor
 
       def build_run_dependency_descriptor(expansion, rbs_descriptor)
         entries = analyzed_file_entries(expansion) + discovery_file_entries(expansion) +
-                  pre_eval_file_entries + template_unit_file_entries + rbs_descriptor.files
+                  pre_eval_file_entries + template_unit_file_entries + rbs_descriptor.files +
+                  root_presence_entries(expansion)
         # #979 — the signature ROOTS' listings, one glob row each. `rbs_descriptor.files` covers only the
         # `.rbs` files that existed while the run read them, so without these a signature file written after
         # the run left the slot validating fresh and the warm run answered without it.
@@ -1385,6 +1398,20 @@ module Rigor
         Cache::Descriptor.new(files: entries, globs: globs.uniq)
       end
 
+      # #1962 / #1555 — a kind row per path the run's answer depends on the presence and kind of, not only its
+      # bytes. An analysis root: its path errors (`no such file or directory`, `not a Ruby file`) answer to whether
+      # it exists and whether it is a directory or a file, while what a directory root holds is the analysed-file
+      # set the key carries. A `pre_eval:` entry: `pre-eval.file-not-found` answers to whether it is a file (one
+      # that is has its `:stat` row from {#pre_eval_file_entries}). A project signature root, configured or the
+      # auto-detected `sig`: the loader reads a directory and a file differently, and #979's listing rows cover a
+      # file appearing under a root that existed, not the root appearing. A kind row rather than an existence row,
+      # because a directory replaced by a file of the same name leaves an existence row fresh. The `--incremental`
+      # slot records existence rows for the same paths ({#incremental_slot_rows}, {#baseline_dependency_rows}).
+      def root_presence_entries(expansion)
+        (expansion.fetch(:roots) + @configuration.pre_eval + signature_root_candidates)
+          .uniq.map { |path| Cache::Descriptor::FileEntry.kind(path: path) }
+      end
+
       # Every file a plugin read or probed through its `IoBoundary` (#577 / #613), and every directory it listed
       # (#954), as the boundaries stand when asked.
       def plugin_boundary_rows
@@ -1574,7 +1601,7 @@ module Rigor
           end
         end
       end
-      private :plugin_boundary_rows, :producer_watch_glob_entries, :existence_entries,
+      private :plugin_boundary_rows, :producer_watch_glob_entries, :existence_entries, :root_presence_entries,
               :analysis_reads_attributed?, :signature_root_candidates, :discovery_glob_entries,
               :unanalysed_pre_eval_entries, :signature_rows, :within?
 
@@ -1748,6 +1775,8 @@ module Rigor
         @project_discovered_prepends = discovery.discovered_prepends
         @project_discovered_extends = discovery.discovered_extends
         @project_unpositioned_mixins = discovery.unpositioned_mixins
+        # Issue #1752 — the files that open `class << Const`, read only by {#class_declarations}.
+        @project_singleton_class_sources = discovery.singleton_class_sources
       end
 
       # Internal: builds the deferred cross-file discovery tables at most once per run and adopts them.
@@ -1804,10 +1833,8 @@ module Rigor
       # the pre-pass then saw two writers for every constant a file declares and withheld its publication (#644),
       # and every file was a discovered-not-analysed dependency of the run's cache entry.
       #
-      # The widening decision itself still compares the paths as spelled. `exclude:` patterns match a path as it
-      # is spelled, so until #1576 is fixed the configured absolute `lib` can discover files the argument `lib`
-      # excludes (a relative `lib/gen/**` pattern never matches `/abs/lib/gen/x.rb`), and treating the two as the
-      # same root would drop those files from discovery.
+      # The widening decision itself compares the paths as spelled. `exclude:` patterns apply to both spellings
+      # alike (#1576), so the configured absolute `lib` and the argument `lib` exclude the same files.
       def project_discovery_expansion(paths, expansion)
         return nil unless widen_discovery_to_project?(paths)
 
@@ -1901,8 +1928,10 @@ module Rigor
       # The run's per-file effect collections in sorted path order — the sequential half merged with the
       # pool's, exactly as {#file_dependencies} reconciles its two halves. Sorted, because the fold below
       # it must not depend on pool-completion order.
+      # Issue #1898 — a narrowed incremental run adds the collections its session served for the files it did not
+      # analyse, under this run's own for any path both name.
       def effect_collections
-        effect_collections_by_path.sort_by { |path, _| path.to_s }.map(&:last)
+        @served_effect_collections.merge(effect_collections_by_path).sort_by { |path, _| path.to_s }.map(&:last)
       end
 
       # Editor mode § "Scope choice — option A". Under `buffer:` non-nil the per-file analysis emits
@@ -2017,7 +2046,9 @@ module Rigor
           template_units: -> { template_units },
           analyze_file: ->(path, environment) { analyze_file(path, environment) },
           restored_run_level_rows: @restored_run_level_rows,
-          feature_sources: -> { required_feature_sources }
+          feature_sources: -> { required_feature_sources },
+          plugin_prepare: -> { @pre_passes.prepare_throwaway_registry },
+          prepare_coordinator_plugins: -> { @pre_passes.prepare_registry(@plugin_registry) }
         )
         @diagnostic_aggregator = DiagnosticAggregator.new(
           configuration: @configuration,
@@ -2037,7 +2068,8 @@ module Rigor
           definition_build_failures_snapshot: -> { @snapshots.definition_build_failures },
           hkt_scan_failure_snapshot: -> { @snapshots.hkt_scan_failure },
           conformance_results_snapshot: -> { @snapshots.conformance_results },
-          pooled_run_disclosures: -> { @pool_coordinator.collected_run_disclosures }
+          pooled_run_disclosures: -> { @pool_coordinator.collected_run_disclosures },
+          pooled_trust_refusals: -> { @pool_coordinator.collected_trust_refusals }
         )
       end
 
@@ -2063,7 +2095,8 @@ module Rigor
         )
         RunStats.new(
           wall_seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at,
-          peak_rss_bytes: RunStats.peak_rss_bytes,
+          # Issue #1529 — read lazily on the summary's first use, so a run that prints none never forks for it.
+          peak_rss_probe: RunStats::CURRENT_PROCESS_PEAK_RSS,
           # #392 — the template units count too: they are files this run parsed and typed, and a stats line
           # that omitted them would under-report exactly the work a views-heavy project added.
           target_files: expansion.fetch(:files).size + template_units.paths.size,
@@ -2176,7 +2209,8 @@ module Rigor
         bad = []
         Array(paths).each do |path|
           if File.directory?(path)
-            files.concat(PathExpansion.directory_files(path, @configuration.exclude_patterns))
+            files.concat(PathExpansion.directory_files(path, @configuration.exclude_patterns,
+                                                       base: @configuration.exclude_base))
           # Editor-mode bypass: the buffer's logical path is treated as a real `.rb` file regardless of
           # on-disk presence — `parse_source` reads bytes from the buffer's physical path. Common case: LSP
           # client editing a brand-new file.
@@ -2188,7 +2222,7 @@ module Rigor
             bad << [path, "no such file or directory"]
           end
         end
-        { files: files, errors: path_expansion_errors(bad, any_files: files.any?) }
+        { files: files, roots: Array(paths).map(&:to_s), errors: path_expansion_errors(bad, any_files: files.any?) }
       end
 
       # A bad path *among valid ones* is a warn-and-skip — the run still does useful work, so `rigor check
@@ -2591,10 +2625,11 @@ module Rigor
         # the rule is active or `record_self_calls:` opted in.
         index = nil
         self_call_record = with_self_call_recording(path) do
-          index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+          index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope, widen_clauses: true)
         end
         self_call_misses = self_call_record ? self_call_record.calls : []
         diagnostics = rule_and_plugin_diagnostics(path, parse_result, scope, index, self_call_misses)
+        notify_file_indexed(path, parse_result, scope, index)
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [
@@ -2618,6 +2653,14 @@ module Rigor
         ]
       end
 
+      # ADR-113 WD2 — the `on_file_indexed` observer. It reads; an error inside it never changes this file's
+      # diagnostics, so it is contained here rather than reaching {#analyze_file_body}'s crash row.
+      def notify_file_indexed(path, parse_result, scope, index)
+        @on_file_indexed&.call(path, parse_result, scope, index)
+      rescue StandardError
+        nil
+      end
+
       # ADR-53 B4 — the built-in node collectors and the plugin node rules share ONE traversal of the file.
       # The collectors are built here (they need the completed `index`) and populated by the converged
       # plugin walk; `node_results` carries the per-plugin node-rule output. Both the built-in `diagnose`
@@ -2636,7 +2679,8 @@ module Rigor
           node_collectors: node_collectors,
           stated_runtime_ruby: @configuration.stated_runtime_ruby
         )
-        diagnostics + plugin_emitted_diagnostics(path, root, scope, node_results)
+        plugin_rows = plugin_emitted_diagnostics(path, root, scope, node_results)
+        diagnostics + CheckRules.filter_plugin_suppressed(plugin_rows, path: path, comments: parse_result.comments)
       end
 
       # ADR-24 slice 4a — runs `block` (the typing pass) with the self-call recorder active when either

data/lib/rigor/analysis/severity_stamp.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "check_rules/rule_ids"
 require_relative "diagnostic"
 require_relative "../configuration/severity_profile"
 
@@ -9,14 +10,46 @@ module Rigor
     # overrides and drops any diagnostic resolving to `:off`. Rules emit with their authored severity; the
     # profile is the final filter.
     #
+    # Issue #1895 — the `.rigor.yml` `disable:` list is applied here too, ahead of the profile, with the same
+    # token expansion and match per-file analysis uses ({CheckRules.config_disabled?}), but only to a built-in
+    # check-rule row (see {.check_rule_row?}): the rows the diagnostic policy already says `disable:` reaches. Most
+    # are filtered where they were produced; this catches the ones that are not (the `effect.annotations-unchecked`
+    # residual under `disable: [all]`) on every run shape (sequential, pool, `--incremental`, a warm cache hit).
+    # Issue #1953 — a plugin's `plugin.<id>.*` row answers here to its qualified id (`plugin.<id>.<rule>`) or to
+    # `plugin.<id>`, never to a bare id or `all`. The run-level rows outside the check-rule catalogue
+    # (`rbs.coverage.*`, `dynamic.dependency-source.*`, the plugin loader, `plugin_trust.*`, `pool-degraded`) keep
+    # answering to `severity_overrides:` only, by any spelling.
+    #
     # Extracted (ADR-87 WD4) so the miss path ({Runner::DiagnosticAggregator}) and the boot-slimming hit path
     # ({RunCacheProbe}, which never loads the aggregator) apply the IDENTICAL final filter — a warm HIT's
     # served diagnostics are byte-identical to what a full run would print.
     module SeverityStamp
       module_function
 
+      CHECK_RULES = CheckRules::ALL_RULES.to_set.freeze
+      private_constant :CHECK_RULES
+
       def apply(diagnostics, configuration)
-        diagnostics.filter_map { |diagnostic| stamp(diagnostic, configuration) }
+        disabled = CheckRules.expand_rule_tokens(configuration.disabled_rules)
+        diagnostics.filter_map do |diagnostic|
+          next nil if config_disabled_row?(diagnostic, disabled)
+
+          stamp(diagnostic, configuration)
+        end
+      end
+
+      # A built-in check-rule row answers to the expanded list by its id or `all`; a plugin's `plugin.<id>.*` row
+      # by its qualified id or `plugin.<id>` only ({CheckRules.plugin_row_disabled?}, issue #1953). Every other
+      # row is out of the list's reach.
+      def config_disabled_row?(diagnostic, disabled)
+        return CheckRules.config_disabled?(diagnostic.rule, disabled) if check_rule_row?(diagnostic)
+
+        CheckRules.plugin_row_disabled?(diagnostic, disabled)
+      end
+
+      # A built-in check-rule row: its id is in the CheckRules catalogue and no plugin emitted it.
+      def check_rule_row?(diagnostic)
+        diagnostic.source_family == Diagnostic::DEFAULT_SOURCE_FAMILY && CHECK_RULES.include?(diagnostic.rule)
       end
 
       def stamp(diagnostic, configuration)

data/lib/rigor/analysis/worker_session.rb

@@ -228,7 +228,7 @@ module Rigor
         scope = @template_units.seed(
           seed_project_scope(Scope.empty(environment: @environment, source_path: path)), path
         )
-        index = Inference::ScopeIndexer.index(root, default_scope: scope)
+        index = Inference::ScopeIndexer.index(root, default_scope: scope, widen_clauses: true)
         # ADR-53 B4 — built-in collectors + plugin node rules share one walk.
         node_collectors = CheckRules.build_node_collectors(path, index, root)
         node_results = node_rule_results_by_plugin(path, root, scope, node_collectors, index)
@@ -241,7 +241,8 @@ module Rigor
           node_collectors: node_collectors,
           stated_runtime_ruby: @configuration.stated_runtime_ruby
         )
-        diagnostics += plugin_emitted_diagnostics(path, root, scope, node_results)
+        plugin_rows = plugin_emitted_diagnostics(path, root, scope, node_results)
+        diagnostics += CheckRules.filter_plugin_suppressed(plugin_rows, path: path, comments: parse_result.comments)
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [analyzer_error(path, e.message)]
@@ -336,6 +337,45 @@ module Rigor
         end
       end
 
+      # Issue #1900 — `{plugin id => refused-read count}` over `registry`'s boundaries right now: the baseline
+      # a later drain subtracts, so it reports only the refusals made after the baseline was taken.
+      def self.refusal_counts(registry)
+        registry.plugins.to_h do |plugin|
+          summary = begin
+            plugin.io_boundary.refusal_summary
+          rescue StandardError
+            nil
+          end
+          [safe_plugin_id(plugin), summary ? summary[:count] : 0]
+        end
+      end
+
+      def self.safe_plugin_id(plugin)
+        plugin.manifest.id
+      rescue StandardError
+        plugin.class.to_s
+      end
+
+      # Issue #1900 — the {Plugin::IoBoundary} trust-policy refusals this session's plugin instances made
+      # since the previous drain, one `{plugin_id:, count:, first_path:, nearest_root:}` per plugin that hit
+      # any, in registry order. Unlike {#drain_run_disclosures} each drain reports only what is new — the
+      # boundary keeps its running total and this session remembers how much of it was already reported —
+      # because the coordinator SUMS the drains: a fork child inherits the parent's `#prepare` refusals,
+      # and reporting them again would count them once per worker. `first_path` is the boundary's first
+      # refusal overall, which is the delta's own first path whenever nothing was reported before it, and
+      # the coordinator keeps the first-merged path otherwise. It is not baselined after `#init`, so a plugin
+      # whose `#init` refuses differently here than on the coordinator registry can have this session's
+      # `#init` path named. Marshal-clean and Ractor-copyable.
+      def drain_trust_refusals
+        return [] if @plugin_registry.empty?
+
+        @plugin_registry.plugins.filter_map do |plugin|
+          trust_refusal_delta(plugin)
+        rescue StandardError
+          nil
+        end
+      end
+
       private
 
       # Mirrors {Runner#seed_project_scope}: applies the cross-file pre-pass discovery tables the
@@ -402,6 +442,10 @@ module Rigor
       def run_plugin_prepare
         return [] if @plugin_registry.empty?
 
+        # Issue #1900 — per plugin id, how much of its boundary's count is already reported. Starts at what
+        # `#init` refused while the registry was materialised: `#init` runs on the coordinator-side registry
+        # too, which reports those reads itself, so counting them here as well would double them.
+        @reported_refusal_counts = self.class.refusal_counts(@plugin_registry)
         @plugin_registry.plugins.flat_map do |plugin|
           plugin.prepare(plugin.services)
           []
@@ -490,6 +534,18 @@ module Rigor
         )
       end
 
+      def trust_refusal_delta(plugin)
+        summary = plugin.io_boundary.refusal_summary
+        return nil if summary.nil?
+
+        plugin_id = safe_plugin_id(plugin)
+        delta = summary[:count] - @reported_refusal_counts.fetch(plugin_id, 0)
+        return nil unless delta.positive?
+
+        @reported_refusal_counts[plugin_id] = summary[:count]
+        summary.merge(count: delta, plugin_id: plugin_id)
+      end
+
       def safe_plugin_id(plugin)
         plugin.manifest.id
       rescue StandardError

data/lib/rigor/cache/descriptor.rb

@@ -82,7 +82,12 @@ module Rigor
       # an unchanged file would fold as "no possible fact" where a cold walk records one.
       # v18: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`; a pre-18 bundle
       # carries it empty, so an unchanged file's conditional visibility would fold as certain.
-      SCHEMA_VERSION = 18
+      # v19: #1555 / #1962 — the run-result dependency descriptor now carries a `:kind` row per analysis root,
+      # `pre_eval:` entry and project signature root (configured, or the auto-detected `sig`), so one that
+      # appears, vanishes or changes kind invalidates the warm entry. A
+      # pre-19 entry carries none of them and would validate fresh across exactly those edits, so cached
+      # entries must read as misses once and rebuild carrying the rows.
+      SCHEMA_VERSION = 19
 
       # Per-slot entry value objects. Constructors validate enums / required fields and freeze the resulting
       # struct so no caller can mutate after the entry is in a Descriptor.
@@ -96,7 +101,7 @@ module Rigor
         # It MUST NOT be placed in a descriptor used as a cache KEY (its value carries machine-local,
         # per-run-nondeterministic stat data); {RbsDescriptor.build}'s env-cache `files` therefore stay
         # `:digest`, while the {Runner} run-dependency descriptor and plugin {IoBoundary} reads use `:stat`.
-        VALID_COMPARATORS = %i[digest stat mtime exists].freeze
+        VALID_COMPARATORS = %i[digest stat mtime kind exists].freeze
 
         # The two `:exists` values — `File.exist?`'s answer rendered with `to_s`, which is what
         # {Descriptor#file_entry_fresh?} compares the live answer against.
@@ -163,6 +168,32 @@ module Rigor
           new(path: path, comparator: :exists, value: PRESENT)
         end
 
+        # The four `:kind` values, in the order {Analysis::Runner}'s path expansion asks: a directory, a regular
+        # file, something else that exists (a FIFO, a socket), nothing (a missing path or a dangling symlink).
+        # Each predicate follows symlinks, as the expansion's do.
+        KIND_DIRECTORY = "directory"
+        KIND_FILE = "file"
+        KIND_OTHER = "other"
+        KIND_ABSENT = "absent"
+
+        # #1962 — the kind row: fresh while `path` is still the same kind of thing, stale once it appears,
+        # vanishes, or a directory and a file trade places. It is the row for an analysis root, whose
+        # diagnostics (`no such file or directory`, `not a Ruby file`) answer to exactly that and to nothing
+        # else about the path, and for a `pre_eval:` entry and a signature root: an existence row would read a
+        # directory replaced by a file of the same name as fresh (ADR-45 WD1b's bound), and what the path holds
+        # has rows of its own (the analysed-file set the key carries, a signature root's `.rbs` rows).
+        def self.kind(path:)
+          new(path: path, comparator: :kind, value: kind_of(path))
+        end
+
+        def self.kind_of(path)
+          if File.directory?(path) then KIND_DIRECTORY
+          elsif File.file?(path) then KIND_FILE
+          elsif File.exist?(path) then KIND_OTHER
+          else KIND_ABSENT
+          end
+        end
+
         # @return whether this row records the path as absent (see {.absent}).
         def absent?
           comparator == :exists && value == ABSENT
@@ -413,10 +444,11 @@ module Rigor
 
       # File-comparator strictness ordering. `:stat` is strictest (it carries the content digest AND a stat
       # tuple, so it validates content-authoritatively while short-circuiting on an unmoved stat); `:digest` is
-      # deterministic across machines; `:mtime` is cheaper but local; `:exists` is the weakest signal. Ranking
-      # `:stat` and `:digest` apart guarantees a path contributed under both never raises a value {Conflict}
-      # (their `value` strings differ by construction) — the stricter one wins and its value is used.
-      COMPARATOR_STRICTNESS = { stat: 3, digest: 2, mtime: 1, exists: 0 }.freeze
+      # deterministic across machines; `:mtime` is cheaper but local; `:kind` answers what the path is and
+      # `:exists` only whether it is there, the weakest signal. Ranking `:stat` and `:digest` apart guarantees a
+      # path contributed under both never raises a value {Conflict} (their `value` strings differ by
+      # construction) — the stricter one wins and its value is used.
+      COMPARATOR_STRICTNESS = { stat: 4, digest: 3, mtime: 2, kind: 1, exists: 0 }.freeze
       private_constant :COMPARATOR_STRICTNESS
 
       # Composes any number of descriptors into a single descriptor whose slots are the union of the inputs'
@@ -505,6 +537,8 @@ module Rigor
           FileDigest.stat_fresh?(entry.path, entry.value)
         when :mtime
           File.exist?(entry.path) && File.mtime(entry.path).to_i.to_s == entry.value
+        when :kind
+          FileEntry.kind_of(entry.path) == entry.value
         when :exists
           File.exist?(entry.path).to_s == entry.value
         else

data/lib/rigor/cache/engine_source.rb

@@ -59,6 +59,19 @@ module Rigor
       # `apps/` and `tool/` are not loaded by an analysis and stay out.
       SOURCE_DIRECTORIES = %w[lib plugins].freeze
 
+      # Engine DATA the analysis reads at runtime, relative to the gem root (issue #1492). A data edit moves
+      # diagnostics as surely as a `lib/` edit, yet the caches that key only on `signature_paths` plus this
+      # digest (the `--incremental` snapshot fingerprint, `Protection::MutationCache`) see nothing else.
+      #
+      # - YAML: `data/builtins` (`MethodCatalog::DATA_ROOT`) and `data/effects` (`Effects::Catalog`,
+      #   `Effects::Registry`).
+      # - RBS: every `.rbs` under `data/` (`core_overlay`, `vendored_gem_sigs`, `capability_roles`,
+      #   `gem_overlay`) plus each bundled plugin's `plugins/*/sig`. `RbsDescriptor` digests the same files
+      #   into the run-result and env caches, but those are the only two consumers that do.
+      #
+      # Tooling-only trees (`data/oss-sweep`) are not read by an analysis and stay out.
+      DATA_GLOBS = %w[data/builtins/**/*.yml data/effects/**/*.yml data/**/*.rbs plugins/*/sig/**/*.rbs].freeze
+
       # The one directory whose absence means "this is not an engine tree". `plugins/` may legitimately be
       # missing (a slimmed install contributes nothing); a missing `lib/` would silently shrink the digest
       # to whatever else happened to be there, which is exactly the weakening this module forbids.
@@ -153,8 +166,9 @@ module Rigor
         !File.exist?(File.join(root, ".git"))
       end
 
-      # A SHA-256 over every engine `.rb` file: its ROOT-RELATIVE path (so the digest survives moving or
-      # re-cloning the checkout) followed by its bytes, in sorted path order.
+      # A SHA-256 over every engine `.rb` file and {DATA_GLOBS} data file: its ROOT-RELATIVE
+      # path (so the digest survives moving or re-cloning the checkout) followed by its bytes, in sorted path
+      # order.
       #
       # The walk itself is not memoised — {.process_identity} is where a production caller gets the
       # once-per-process value, and this stays the computation so a spec can point it at another tree.
@@ -178,12 +192,12 @@ module Rigor
         raise Unavailable, "engine source under #{root} could not be read: #{e.message}"
       end
 
-      # Sorted absolute paths of every engine `.rb` file, across the directories that exist.
+      # Sorted, de-duplicated absolute paths of every engine `.rb` file and {DATA_GLOBS} data file, across
+      # the directories that exist. `plugins/*/sig/**/*.rbs` overlaps nothing else but is de-duplicated anyway.
       def source_files(root)
-        SOURCE_DIRECTORIES.flat_map do |relative|
-          directory = File.join(root, relative)
-          File.directory?(directory) ? Dir.glob(File.join(directory, "**", "*.rb")) : []
-        end.sort
+        sources = SOURCE_DIRECTORIES.flat_map { |relative| Dir.glob(File.join(root, relative, "**", "*.rb")) }
+        data = DATA_GLOBS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }
+        (sources + data).uniq.sort
       end
     end
   end