rigortype 0.4.6 → 0.4.8

data/lib/rigor/analysis/incremental_session.rb

@@ -27,10 +27,8 @@ module Rigor
     #
     # The invariant the verify harness (and the spec) assert: `#recheck`'s merged diagnostics are
     # byte-identical to a full `--no-cache` re-analysis of the edited tree, in the same order (#1524; the gate
-    # itself compares sorted sets). This is the `--verify-incremental` acceptance gate, here without disk
-    # persistence or CLI wiring (the cache is in-process). It models the body tier only: an edit that adds /
-    # removes / moves a *file* is outside the analyzed set it maintains and falls to a fresh {#baseline} (the
-    # structural tier is a later slice).
+    # itself compares sorted sets). The `--verify-incremental` gate runs this engine; `#run_incremental` adds the
+    # snapshot persistence that `--incremental` uses.
     # The class-length budget is relaxed: this is one cohesive orchestrator of the incremental state
     # (per-file diagnostics cache, the file-level / symbol-level / negative dependency graphs, and the ADR-85
     # seed bundles), clearer read together than split across micro-classes that would all share the same ivars.
@@ -101,8 +99,8 @@ module Rigor
         # ADR-85 WD2 — per-file discovery seed bundles keyed by logical path. A cold baseline builds them; a
         # warm recheck folds them (re-walking only changed files) and refreshes the set. Ride the snapshot.
         @seed_bundles = {}
-        @cache = {}              # analyzed path => [Diagnostic]
-        @sources = {}            # analyzed path => Set<source path it read from>
+        @cache = {}              # analyzed path => its diagnostics
+        @sources = {}            # analyzed path => the source paths it read from
         @digests = {}            # analyzed path => ADR-87 packed stat-digest entry at last analysis
         # Issue #1583 — discovered-not-analysed path => the same packed entry, for a run over path arguments that
         # #684 widened to the configured `paths:`. Empty on every run over the configured paths.
@@ -110,25 +108,29 @@ module Rigor
         @analyzed = []           # the project files analyzed last round
         @dependents = {}         # inverted @sources (file-level)
         # ADR-46 slice 4 — symbol-granularity tracking.
-        @symbol_sources = {}     # consumer => { source_path => Set<"ClassName#method"> }
-        @ancestry_sources = {}   # consumer => Set<source_path> (class-ancestry deps)
+        @symbol_sources = {}     # consumer => { source_path => the "ClassName#method" symbols it read }
+        @ancestry_sources = {}   # consumer => source paths (class-ancestry deps)
         @symbol_fingerprints = {}  # path => { "ClassName#method" => sha256_hex }
-        @symbol_dependents = {}    # [source, symbol] => Set<consumer>
-        @ancestry_dependents = {}  # source => Set<consumer> (inverted ancestry_sources)
+        @symbol_dependents = {}    # [source, symbol] => consumers
+        @ancestry_dependents = {}  # source => consumers (inverted ancestry_sources)
         # ADR-46 slice 3 — negative (missing) dependencies: a consumer that
         # looked up a name and resolved nothing must be re-checked when that
         # name later appears (e.g. a `call.unresolved-toplevel` whose target
         # is defined by a later edit).
-        @missing = {}              # consumer => Set<"kind:name"> it looked up and missed
-        @negative_dependents = {}  # "kind:name" => Set<consumer> (inverted @missing)
-        @class_decls = {}          # path => Set<qualified class name declared in the file>
+        @missing = {}              # consumer => the "kind:name" keys it looked up and missed
+        @negative_dependents = {}  # "kind:name" => consumers (inverted @missing)
+        @class_decls = {}          # path => qualified class names declared in the file
         # Issue #644 — the value-constant twin: path => { qualified constant name => publication descriptor }.
         # Diffed on a recheck to find every constant whose PUBLISHED answer could have moved, which satisfies
         # the `constant:` edges a reader records at every reference, resolved or not.
         @constant_decls = {}
-        # ADR-89 WD2 — per-def observed-key return summaries: [path, symbol] => { keys:, returns:, effects: }.
+        # ADR-89 WD2 — per-def observed-key return summaries: [path, symbol] => { keys:, returns:, effects:,
+        # guard_constants: }.
         # Harvested from the ADR-84 return memo after each run; drives the behavioural-stability gate.
         @return_summaries = {}
+        # Issue #3180 — what the ADR-89 WD2 gate's probe read for the pairs it passed, from the closure decision
+        # until {#absorb} folds it into the skipped readers; nil when no pair passed.
+        @gate_observations = nil
         # ADR-67 WD6c lift — the `parameter_inference:` seed table the cached diagnostics were computed
         # under (`{}` when the gate is off — the gate state is constant across a snapshot's lifetime because
         # the configuration is part of the global fingerprint). A recheck recomputes the table fresh and
@@ -265,7 +267,7 @@ module Rigor
         # digest (issue #1536).
         @seed_bundles = source_rbs_gate.stamp(runner.seed_bundles, whole_project: true)
         absorb_dependency_graph(runner)
-        @return_summaries = runner.return_summaries # ADR-89 WD2 — the full-run behavioural surface.
+        @return_summaries = baseline_return_summaries(runner)
         # ADR-67 WD6c lift — the seed table the runner's own pre-pass computed ({} when the gate is off).
         # Reading it back, rather than computing it here, keeps the baseline single-collect.
         @param_table = runner.param_inferred_types
@@ -393,6 +395,8 @@ module Rigor
       # whole project — what a `sig/` edit already costs through the snapshot fingerprint.
       def affected_closure(changed, added, removed, param_files = Set.new, param_pairs = Set.new)
         @stale_plugin_readers = plugin_read_affected | disclosure_refreshers(removed)
+        # Issue #3180 — a recheck that passed the gate and then re-baselined absorbed nothing: start without it.
+        @gate_observations = nil
         return whole_project_closure(changed, added) if source_rbs_gate.moved?(@seed_bundles, changed, added, removed)
 
         (gated_closure(changed, added, removed, param_files, param_pairs) | @stale_plugin_readers).freeze
@@ -579,8 +583,10 @@ module Rigor
       # surfaces are its return type and its content-mutation effects (no instance/class variable write, no
       # `yield`, no implicit-self call whose transitive effect a caller could observe). For a candidate the
       # session compares its content-mutation effects (pure AST) then re-evaluates its return at every
-      # persisted key (a runner probe); a pair passes only when BOTH are unchanged. Any missing summary,
-      # ineligible def, changed effect, changed return, or uncomputable key keeps the pair — the conservative
+      # persisted key (a runner probe), with the published-constant spellings its body reads (issue #3186,
+      # {#guard_constants_unmoved?}); a pair passes only when all three are unchanged. Any missing summary (which is
+      # also how a def whose keys could not all be recorded is stored, issues #3116 and #3160), ineligible def,
+      # changed effect, changed return, or uncomputable key keeps the pair — the conservative
       # direction the `--verify-incremental` and byte-identical recheck specs backstop.
       def behaviourally_unstable_pairs(changed_pairs, unstable, scan_index)
         return changed_pairs if @return_summaries.empty? || scan_index.nil?
@@ -633,9 +639,21 @@ module Rigor
         runner = build_runner
         files = @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
         rebind_buffer(files)
-        files
+        admit_new_buffer(files)
       end
 
+      # Issue #2233 — a buffer for a file that is not on disk (a new file) is in no expansion, so the set above never
+      # names it: the recheck neither analyses it nor sees its declarations, and the run answers "re-analysed 0 file(s)"
+      # with no diagnostics for the buffer. Option A (single-file scope) analyses the logical path whether or not it
+      # exists; option B joins it to the set the same way, as an added file, so the closure analyses it like any new
+      # file. A buffer already matched by {#rebind_buffer} is in `files` and is returned as it is.
+      def admit_new_buffer(files)
+        return files if @buffer.nil? || files.include?(@buffer.logical_path)
+
+        files + [@buffer.logical_path]
+      end
+      private :admit_new_buffer
+
       # Verification engine (the `--verify-incremental` gate): with NO source edit, re-analyze `subset` fresh
       # and serve every other analyzed file from the baseline cache. Because nothing on disk changed, the
       # merged result MUST equal a full analysis — so this exercises the subset-analysis and cache-merge
@@ -1226,10 +1244,79 @@ module Rigor
         # with anything its closure demanded for itself, so this is the same union the next run replays.
         @run_level_rows = runner.run_level_rows
         @synthetic_surface_digest = synthetic_surface_digest_of(runner)
-        refresh_return_summaries(runner, analyze_set)
+        refresh_gated_state(runner, analyze_set)
         refresh_effect_collections(runner, analyze_set)
       end
 
+      # The summaries, then the skipped readers' edges, in that order ({#refresh_return_summaries}), with what the
+      # gate's probe observed for this recheck taken and cleared. The clear is a guard no spec pins:
+      # {#affected_closure} resets the slot before every {#absorb}, so nothing reads it again. It only keeps a
+      # consumed observation from outliving its recheck, should absorb gain another caller.
+      def refresh_gated_state(runner, analyze_set)
+        observations = @gate_observations
+        @gate_observations = nil
+        refresh_return_summaries(runner, analyze_set, observations)
+        absorb_gate_reads(observations, analyze_set)
+      end
+
+      # Issue #3180 — give every reader the ADR-89 WD2 gate skipped the edges its probe recorded for the pair it
+      # passed ({#gate_observations}): the reader reaches those defs, classes and names through the edited def now,
+      # and no analysis of the reader will record that until something else re-analyses it. The probe evaluated the
+      # def at all of its stored keys and a reader observes it under some of them, so the reader may gain an edge it
+      # does not need; that costs a re-analysis, never an answer. Runs after {#refresh_return_summaries}, which reads
+      # the dependents as they stood before these edges. Independent of the summaries: a pooled recheck over
+      # summaries a sequential run stored can pass the gate too, and its skipped readers need the edges as much.
+      def absorb_gate_reads(observations, analyze_set)
+        return if observations.nil?
+
+        analyzed = analyze_set.to_set
+        skipped = observations.reads.keys.to_h do |pair|
+          [pair, ((@symbol_dependents[pair] || Set.new) - analyzed).to_a]
+        end
+        return if skipped.each_value.all?(&:empty?)
+
+        credit_probe_plugin_rows(observations, skipped)
+        skipped.each { |pair, readers| readers.each { |reader| add_recorded_reads(reader, observations.reads[pair]) } }
+        invert_dependency_graph
+      end
+
+      # Issue #3187 — the plugin reads the probe made while evaluating a passed pair's def, credited to each reader of
+      # the pair it skipped, as an analysis of that reader would have credited them: a later edit of what the plugin
+      # read re-analyses the reader ({#plugin_read_affected}). Like the edges, a reader may gain a row it does not
+      # need, which costs a re-analysis. Run-scoped registrations are not credited: a pair whose probe registered one
+      # does not pass ({#readers_hold_disclosures?}).
+      def credit_probe_plugin_rows(observations, skipped)
+        skipped.each do |pair, readers|
+          rows = observations.plugin_reads[pair]
+          next if rows.nil?
+
+          readers.each { |reader| @plugin_reads[reader] = ((@plugin_reads[reader] || []) | rows).freeze }
+        end
+      end
+
+      # `record`'s reads added to `reader`'s, less the reads of `reader`'s own file (a file records no edge to
+      # itself). Builds new sets: a restored snapshot's are not this session's to mutate. The self-filter on the
+      # ancestry edges is a guard no spec pins: it mirrors the two that are pinned, and no row was built in which
+      # the edited def comes to read the ancestry of a class its skipped reader's file declares.
+      def add_recorded_reads(reader, record)
+        symbols = (@symbol_sources[reader] || {}).dup
+        record.symbol_sources.each do |path, names|
+          symbols[path] = (symbols[path] || Set.new) | names unless path == reader
+        end
+        @symbol_sources[reader] = symbols
+        @ancestry_sources[reader] = (@ancestry_sources[reader] || Set.new) | (record.ancestry_sources - [reader])
+        @sources[reader] = (@sources[reader] || Set.new) | (record.sources - [reader])
+        @missing[reader] = (@missing[reader] || Set.new) | record.missing
+      end
+
+      # The inverted indexes of the four per-consumer edge tables.
+      def invert_dependency_graph
+        @dependents          = Incremental.invert(@sources)
+        @symbol_dependents   = Incremental.invert_symbols(@symbol_sources)
+        @ancestry_dependents = Incremental.invert(@ancestry_sources)
+        @negative_dependents = Incremental.invert(@missing)
+      end
+
       # ADR-103 WD13 / #382 — the effects analogue of {#refresh_return_summaries}, and the same soundness
       # order: drop every re-analyzed file's collection first, then fold this run's harvest in. A file the
       # recheck did NOT analyze keeps the collection the snapshot carried, which is exactly the reuse the
@@ -1245,21 +1332,97 @@ module Rigor
         @effect_plugin_digest = effect_plugin_digest_of(runner)
       end
 
-      # ADR-89 WD2 — replace the behavioural summaries of every re-analyzed file with THIS run's harvest: drop
-      # the analyzed files' old summaries first, then fold the fresh ones. Dropping first is the soundness
-      # invariant — a summary for a file is valid only if it came from a run that analyzed that file. On the
-      # sequential path (the default + `--verify-incremental`) the harvest is complete, so a re-analyzed def's
-      # summary is simply refreshed. On a pooled recheck the callee bodies are evaluated in worker processes,
-      # so the main-process memo harvest is sparse; dropping first means a re-analyzed file with no fresh
-      # summary loses its stale one (WD2 then conservatively re-checks its dependents) rather than comparing a
-      # later edit against a pre-edit summary. Files NOT re-analyzed keep their (unchanged, valid) summaries.
-      # A def whose symbol dependents WD2 skipped is observed under fewer keys, so its refreshed summary may
-      # shrink — sound (fewer keys = more conservative) and self-correcting (an empty summary stops the gate
-      # firing, so the callers re-analyse and repopulate).
-      def refresh_return_summaries(runner, analyze_set)
+      # ADR-89 WD2 / issues #3160, #3180 — bring the behavioural summaries up to date with THIS run. The invariant
+      # the gate reads them under: a pair's summary holds every key under which a CURRENT symbol dependent of the
+      # def observes it, directly or through other defs, each with the def's current return; and every file that
+      # observes the def is one of its symbol dependents. A summary that cannot be shown to is deleted, and a pair
+      # with no summary keeps its dependents, so every doubt below resolves to "no summary".
+      #
+      # A run's harvest ({Runner#return_summaries}) is what the files it analysed observed. The keys the gate's
+      # probe observed for the pairs it passed (`observations`, {#gate_observations}) count as this run's too: they
+      # are what the readers the gate skipped observe through the edited def. So per pair:
+      #
+      # - the run cannot list the keys it observed (a pool run, a def past the per-def or total cap, a call the
+      #   memo refused to store): delete;
+      # - every dependent was analysed: the harvest is the whole key set, and replaces the summary (deleting it
+      #   when no analysed file observed the def, which is where a def with no dependent left ends up);
+      # - otherwise the summary keeps the keys of the dependents that were not analysed, and gains this run's
+      #   ({#merged_return_summary}), which are none when no dependent was analysed. The kept returns are current:
+      #   a dependent stays out of the closure of its callee's edit only when the gate proved the returns unmoved
+      #   at every kept key, or when the def's own text did not change. With no summary to keep, the other
+      #   dependents' keys are unknown.
+      #
+      # Fewer keys are never the conservative direction: each key protects the readers that observe the def under
+      # it, so a summary missing one skips a reader whose answer the edit moved.
+      #
+      # "Every dependent" is read off the edges as they stood BEFORE {#absorb_gate_reads} adds the probe's. A
+      # skipped reader that gains its first edge to a def there observes it only through the pair the gate passed,
+      # so the probe's keys are all of its keys; one that already held an edge was not analysed, and the pair keeps
+      # its stored keys.
+      def refresh_return_summaries(runner, analyze_set, observations = nil)
+        harvest = harvest_with_gate_summaries(runner.return_summaries, observations&.summaries)
         analyzed = analyze_set.to_set
-        @return_summaries.reject! { |(path, _symbol), _| analyzed.include?(path) }
-        @return_summaries.merge!(runner.return_summaries)
+        (@return_summaries.keys | (harvest || {}).keys).each do |pair|
+          dependents = @symbol_dependents[pair] || Set.new
+          summary = refreshed_return_summary(pair, harvest, dependents.subset?(analyzed))
+          summary.nil? ? @return_summaries.delete(pair) : @return_summaries[pair] = summary
+        end
+        @return_summaries = capped_return_summaries(@return_summaries)
+      end
+
+      # Issue #3180 — `harvest` (this run's) with the keys the gate's probe observed (`probed`, see
+      # {#gate_observations}) counted as observed by this run: they are what the readers the gate skipped observe
+      # through the def it passed, each with the callee's current return. A def either side cannot list the keys
+      # of has none, and so has one whose keys together pass the per-def cap. A run with no harvest stays without.
+      def harvest_with_gate_summaries(harvest, probed)
+        return harvest if harvest.nil? || probed.nil? || probed.empty?
+
+        probed.each_with_object(harvest.dup) do |(pair, summary), merged|
+          mine = merged.fetch(pair, summary)
+          merged[pair] = mine.nil? || summary.nil? ? nil : merged_return_summary(mine, summary)
+        end
+      end
+
+      # ADR-89 WD2 — the full-run behavioural surface: every file was analysed, so the harvest is every reader's.
+      # A def the run could not list the keys of (nil in the harvest) and a pool run (no harvest) record nothing.
+      def baseline_return_summaries(runner)
+        capped_return_summaries((runner.return_summaries || {}).compact)
+      end
+
+      # `pair`'s summary after a run whose harvest is `harvest` (nil for a run that has none), or nil for none.
+      # `complete` says every dependent of the def was analysed by that run.
+      def refreshed_return_summary(pair, harvest, complete)
+        return nil if harvest.nil?
+
+        fresh = harvest[pair]
+        return nil if fresh.nil? && harvest.key?(pair)
+        return fresh if complete
+
+        merged_return_summary(@return_summaries[pair], fresh)
+      end
+
+      # Issue #3160 — `kept` (the summary of a def some of whose dependents this run did not analyse) with the
+      # keys `fresh` (this run's harvest for the def, or nil) adds. A kept key stays unless `fresh` holds the same
+      # key with the same return; one whose return differs stays beside it, which no re-evaluation can satisfy, so
+      # the gate keeps the def's dependents. nil when there is nothing to keep or the keys pass the per-def cap.
+      def merged_return_summary(kept, fresh)
+        return nil if kept.nil?
+        return kept if fresh.nil?
+
+        rows = fresh[:keys].zip(fresh[:returns])
+        rows += kept[:keys].zip(kept[:returns]).reject { |row| rows.include?(row) }
+        return nil if rows.size > Runner::RETURN_SUMMARY_KEYS_PER_DEF
+
+        { keys: rows.map(&:first), returns: rows.map(&:last), effects: fresh[:effects],
+          guard_constants: fresh[:guard_constants] }
+      end
+
+      # The first {Runner::RETURN_SUMMARY_TOTAL_CAP} of `summaries`, so the snapshot stays small however many runs
+      # fed it. A def past the cap has no summary, which keeps its dependents.
+      def capped_return_summaries(summaries)
+        return summaries if summaries.size <= Runner::RETURN_SUMMARY_TOTAL_CAP
+
+        summaries.first(Runner::RETURN_SUMMARY_TOTAL_CAP).to_h
       end
 
       # Evict a removed file from every per-file map so its stale diagnostics are never served and it drops
@@ -1292,10 +1455,7 @@ module Rigor
           @ancestry_sources[path] = record.ancestry_sources.dup
           @missing[path]          = record.missing.dup
         end
-        @dependents          = Incremental.invert(@sources)
-        @symbol_dependents   = Incremental.invert_symbols(@symbol_sources)
-        @ancestry_dependents = Incremental.invert(@ancestry_sources)
-        @negative_dependents = Incremental.invert(@missing)
+        invert_dependency_graph
         @symbol_fingerprints.merge!(runner.symbol_fingerprints)
         # Wholesale replace (the subset runner's pre-pass is complete): a file that lost its last class must
         # drop out of the map so a later re-add registers as an appearance.
@@ -1384,6 +1544,11 @@ module Rigor
       # (`ResolutionChain#record_hooks`), so a new file that taints `Comparable` with `include(*MODS)` re-checks the
       # readers of a chain through it. It is not `mark:`, which a plain reopening of a module moves (the bucket's
       # module mark) and which would re-check every reader of `Kernel` on any `module Kernel` reopening.
+      #
+      # Issue #3005 — a moved {Scope::DiscoveryIndex::ENVELOPE_DYNAMIC_MARK} fires the owner's `mixin:` keys too: a new
+      # file whose body-level `send(:then)` marks an external `Comparable` makes a reader of a chain through it decline,
+      # and that reader filed `mixin:Comparable`, not `mark:Comparable`. The mark moves only with such a call, not on a
+      # plain reopening.
       def mark_affected(paths, summary)
         def_index = summary && summary[:def_index]
         before = paths.map { |path| @seed_bundles.dig(path, :parameter_envelopes) }
@@ -1391,16 +1556,22 @@ module Rigor
         tainted = Incremental.changed_unpositioned_owners(
           paths.map { |path| @seed_bundles.dig(path, :unpositioned_mixins) },
           [def_index && def_index[:unpositioned_mixins]]
-        )
+        ) | dynamic_owners(moved)
         return Set.new if moved.empty? && tainted.empty?
 
         keys = moved.map { |(class_name, _mark)| "mark:#{class_name.split('::').last}" }.uniq
         keys.concat(mixin_keys(tainted))
         extended = Scope::DiscoveryIndex::ENVELOPE_OBJECT_EXTENDED_MARK
-        keys << "mark:*" if moved.any? { |(_class_name, mark)| mark == extended }
+        meta = Scope::DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK
+        keys << "mark:*" if moved.any? { |(_class_name, mark)| mark == extended || mark == meta }
         Incremental.negative_closure(keys, @negative_dependents)
       end
 
+      def dynamic_owners(moved)
+        dynamic = Scope::DiscoveryIndex::ENVELOPE_DYNAMIC_MARK
+        moved.filter_map { |(class_name, mark)| class_name if mark == dynamic }
+      end
+
       # Issue #1661 — the `mixin:` keys an owner of a moved unpositioned edge fires. The table keys a receiver-form
       # owner by the spelling written (`class File; Constants.include(*MODS); end` is `"Constants"`), not the constant
       # Ruby resolves it to, while the chain files the qualified candidate (`mixin:File::Constants`). The table does
@@ -1505,7 +1676,7 @@ module Rigor
       end
 
       # The qualified class/module names declared in the pre-parsed `index` (shared with
-      # {#symbol_fingerprints_from_index}, so the changed set is parsed once). `{ path => Set<class name> }`.
+      # {#symbol_fingerprints_from_index}, so the changed set is parsed once), keyed by path.
       def class_declarations_from_index(index)
         return {} if index.nil?
 
@@ -1545,7 +1716,9 @@ module Rigor
 
       # ADR-89 WD2 — true when the ONLY cross-file body surfaces of `node` a symbol dependent can consume are
       # its return type and its content-mutation effects — so comparing exactly those two is a COMPLETE
-      # behavioural check. A def qualifies when its body writes no instance / class variable (an ivar
+      # behavioural check. (Issue #3186: the truthiness rule's one-hop body scan reads a third, the published
+      # constants the body names, which the probe compares too; no node kind makes a def ineligible for it.)
+      # A def qualifies when its body writes no instance / class variable (an ivar
       # definite-assignment a same-class caller consumes), does not `yield` (a block-parameter surface a
       # caller passing a block consumes), and makes no implicit-self call (which could carry a transitive
       # shared-state write). Deliberately conservative + purely syntactic: a def with a self-call or a
@@ -1597,29 +1770,104 @@ module Rigor
       end
 
       def content_effects_for(node)
-        (@effects_evaluator ||= Inference::StatementEvaluator.new(scope: Scope.empty))
-          .content_mutated_parameter_positions(node)
+        effects_evaluator.content_mutated_parameter_positions(node)
       rescue StandardError
         nil
       end
 
+      # The evaluator {#content_effects_for} asks, kept for as long as the calling thread's {TypingState} is the one it
+      # was built under. An evaluator caches that state, and the owner evaluators it builds cache theirs, so one kept
+      # across the language server's save rounds, each on a thread of its own, would keep writing its run-scoped memos
+      # into a finished round's state, which that round's release has already emptied (ADR-129).
+      def effects_evaluator
+        state = TypingState.current
+        unless @effects_state.equal?(state)
+          @effects_state = state
+          @effects_evaluator = Inference::StatementEvaluator.new(scope: Scope.empty)
+        end
+        @effects_evaluator
+      end
+
       # ADR-89 WD2 — the subset of `pairs` whose (edited) def re-evaluates to the SAME return descriptor at
       # every persisted key. Runs one runner probe (`evaluate_return_types` — builds the discovery + env once,
       # no file analysis) over all candidate defs, then keeps a pair only when every key's re-evaluated
       # descriptor is present (not a memo refusal) and equal to the persisted one. A probe failure yields an
       # empty set (keep everything).
       def return_stable_pairs(pairs, scan_index)
-        specs = pairs.filter_map { |pair| return_spec_for(pair, scan_index) }
+        specs = pairs.reject { |pair| readers_hold_disclosures?(pair) }.filter_map do |pair|
+          return_spec_for(pair, scan_index)
+        end
         return Set.new if specs.empty?
 
-        results = probe_return_types(specs)
-        specs.each_with_object(Set.new) do |spec, stable|
-          descriptors = results[[spec[:class_name], spec[:method_name], spec[:singleton]]]
-          expected = @return_summaries[spec[:pair]][:returns]
-          next if descriptors.nil? || descriptors.length != expected.length
-          next unless descriptors.each_with_index.all? { |d, i| !d.nil? && d == expected[i] }
+        runner, results = probe_return_types(specs)
+        passed = specs.each_with_object({}) do |spec, pairs|
+          triple = [spec[:class_name], spec[:method_name], spec[:singleton]]
+          next unless returns_unmoved?(spec[:pair], results[triple])
+          next unless guard_constants_unmoved?(spec[:pair], runner.probe_guard_constants[triple])
+          # Issue #3187 — a run-scoped row the probe registered keeps the readers ({#readers_hold_disclosures?}).
+          next if runner.probe_disclosures.key?(triple)
 
-          stable << spec[:pair]
+          pairs[spec[:pair]] = triple
+        end
+        @gate_observations = gate_observations(runner, passed) unless passed.empty?
+        passed.keys.to_set
+      end
+
+      # Issue #3187 — whether a symbol dependent of `pair` holds a run-scoped plugin row ({RunDisclosureLedger}), which
+      # keeps the pair's readers, as a probe that registers one does. A skipped reader replays the rows its last
+      # analysis registered, and which of them came through the edited def, under which key, is not recorded; nor
+      # can rows the probe registers be credited to a reader without that key, or ever be retracted once its def
+      # stops registering them. So a reader holding any row is re-analysed, which settles its rows afresh.
+      def readers_hold_disclosures?(pair)
+        (@symbol_dependents[pair] || Set.new).any? { |reader| @plugin_disclosures.files.key?(reader) }
+      end
+
+      # Issue #3186 — whether the probe's `current` constant spellings ({Runner#guard_constants}) are `pair`'s stored
+      # ones. A reader's `flow.always-truthy-condition` withholds when a def it calls reads a constant another file
+      # published, whatever the def returns, so a return-preserving edit that adds or drops such a read moves the
+      # reader's diagnostics. nil on either side (a list the runner could not make, a summary stored before the list
+      # existed) reads as moved.
+      def guard_constants_unmoved?(pair, current)
+        stored = @return_summaries[pair][:guard_constants]
+        !current.nil? && !stored.nil? && current == stored
+      end
+
+      # Whether the probe's `descriptors` are `pair`'s stored returns, key for key, none of them a memo refusal.
+      def returns_unmoved?(pair, descriptors)
+        expected = @return_summaries[pair][:returns]
+        return false if descriptors.nil? || descriptors.length != expected.length
+
+        descriptors.each_with_index.all? { |descriptor, index| !descriptor.nil? && descriptor == expected[index] }
+      end
+
+      # Issue #3180 — what the gate's probe observed for the pairs it passed. A reader the gate skips is not
+      # re-analysed, yet it now reaches whatever the edited def reaches: a callee the def did not call before, or
+      # one it calls under another key. The probe evaluated the def at every key its readers observe it under, so
+      # its reads are a superset of theirs through this def, and its memo holds every key those evaluations put to
+      # another def. `reads` is each passing pair's {DependencyRecorder::Record}; `summaries` is the probe's own
+      # harvest ({Runner#return_summaries}: nil for a def it cannot list the keys of, nil as a whole in pool mode),
+      # cut down to the defs a passing pair read. A failing pair's observations are left out: its readers are all
+      # re-analysed, and the run's harvest speaks for them. Issue #3187 — `plugin_reads` is each passing pair's plugin
+      # boundary rows ({Runner#probe_plugin_reads}); a pair whose evaluation read none has no key.
+      GateObservations = Data.define(:reads, :summaries, :plugin_reads)
+      private_constant :GateObservations
+
+      # `passed` maps each passing pair to its spec triple. The probe recorded reads for every def it evaluated, and
+      # it evaluated each of these: a summary holds at least one key, so a def the probe could not find answered nil
+      # and did not pass.
+      def gate_observations(runner, passed)
+        reads = passed.transform_values { |triple| runner.probe_reads[triple] }
+        observed = reads.each_value.with_object(Set.new) do |record, pairs|
+          record.symbol_sources.each { |path, symbols| symbols.each { |symbol| pairs << [path, symbol] } }
+        end
+        GateObservations.new(reads: reads, summaries: runner.return_summaries&.slice(*observed),
+                             plugin_reads: probe_rows(passed, runner.probe_plugin_reads))
+      end
+
+      # `table` (spec triple => rows) re-keyed by each passing pair, leaving out a pair with no rows.
+      def probe_rows(passed, table)
+        passed.each_with_object({}) do |(pair, triple), rows|
+          rows[pair] = table[triple] if table.key?(triple)
         end
       end
 
@@ -1634,10 +1882,15 @@ module Rigor
           singleton: singleton, keys: @return_summaries[pair][:keys] }
       end
 
+      # The probe's runner and its `spec triple => descriptors` answer ({} when the probe failed).
       def probe_return_types(specs)
-        build_runner.evaluate_return_types(@paths, specs)
+        runner = build_runner
+        [runner, runner.evaluate_return_types(@paths, specs)]
+      rescue Inference::MemoAudit::Mismatch
+        # ADR-129 WD5 (#2785) — the audit's mismatch (raised by the run's release) fails the session, not the probe.
+        raise
       rescue StandardError
-        {}
+        [runner, {}]
       end
 
       TOP_LEVEL_KEY = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY

data/lib/rigor/analysis/reachability/plugin_roots.rb

@@ -3,6 +3,7 @@
 require_relative "../../plugin"
 require_relative "../../plugin/loader"
 require_relative "../../plugin/services"
+require_relative "../../plugin/trust_policy"
 require_relative "../../reflection"
 require_relative "../../type/combinator"
 
@@ -107,14 +108,16 @@ module Rigor
         end
 
         # Mirrors `Analysis::WorkerSession`'s services: the shared fact store plus whatever cache store the
-        # caller holds. Holding the `Services` is what gives access to the fact store the loaded plugins
-        # share — the loader hands the same instance to every plugin.
+        # caller holds, and the run's trust policy — `rigor unused`'s plugin roots read the same scope
+        # `rigor check` does (#2586). Holding the `Services` is what gives access to the fact store the
+        # loaded plugins share — the loader hands the same instance to every plugin.
         def build_services(configuration, cache_store)
           Plugin::Services.new(
             reflection: Reflection,
             type: Type::Combinator,
             configuration: configuration,
-            cache_store: cache_store
+            cache_store: cache_store,
+            trust_policy: Plugin::TrustPolicy.for_configuration(configuration)
           )
         end
 

data/lib/rigor/analysis/rule_catalog.rb

@@ -25,7 +25,7 @@ module Rigor
     #   profile, taken from `Configuration::SeverityProfile::PROFILES`.
     # - `evidence_tier` — `:high` / `:medium` / `:low` (or `nil` for informational helpers), Rigor's own
     #   confidence that a firing is a true positive, derived from the rule's firing gates. `:high` rules
-    #   fire only on a concrete, statically- known type with no metaprogramming escape (Rigor's
+    #   fire only on a concrete, statically-known type with no metaprogramming escape (Rigor's
     #   false-positive discipline has already filtered the uncertain cases); `:medium` rules rest on flow /
     #   inference proofs that inherit a documented FP envelope (loop / mutation / RBS-strictness modelling
     #   gaps); `:low` rules are resolution- or coverage-gap signals where a firing often reflects missing
@@ -101,7 +101,9 @@ module Rigor
             "of the class are open, and an inherited Object / Kernel signature no longer decides " \
             "`call.wrong-arity` or `call.argument-type-mismatch` on it.",
             "The program may answer the call another way (#1722): a `method_missing` on the receiver's class or an " \
-            "ancestor; a module mixed into either that defines the method (`Integer.include(Ext)` counts wherever " \
+            "ancestor, in source or in RBS (#2792; an RBS `method_missing` on `BasicObject`, `Object` or " \
+            "`Kernel` does not count); " \
+            "a module mixed into either that defines the method (`Integer.include(Ext)` counts wherever " \
             "it is written); singleton methods given to the receiver local (`s.extend(M)`, " \
             "`define_singleton_method`, `class << s`); or, for a receiver typed by its class's name rather than a " \
             "literal, a project subclass that defines the method."
@@ -1087,6 +1089,40 @@ module Rigor
           since: "0.4.0"
         ),
 
+        CheckRules::RULE_PLUGIN_API_SURFACE => Entry.new(
+          id: CheckRules::RULE_PLUGIN_API_SURFACE,
+          summary: "Plugin code calls a member a `Rigor::Plugin` interface does not declare.",
+          fires_when: [
+            "The call's receiver is typed by a `Rigor::Plugin` interface (`_Scope`, `_Environment`, " \
+            "`_Services`, `_FactStore`, `_Configuration`), possibly with `nil`: a hook's `scope`, " \
+            "`scope.environment`, `services.fact_store`, and so on.",
+            "The interface does not declare the called method, and neither does `Object` (with `Kernel` and " \
+            "`BasicObject`).",
+            "The call sits inside a class whose superclass chain reaches `Rigor::Plugin::Base`.",
+            "The `plugin-api-surface` bleeding-edge feature is enabled, or a `severity_overrides:` key names " \
+            "`plugin.api-surface` (the rule resolves `:off` otherwise; a dot-free `plugin` key does not reach it)."
+          ],
+          does_not_fire_when: [
+            "The interface declares the method (`scope.type_of(node)`), or every object answers it " \
+            "(`scope.nil?`, `scope.respond_to?(...)`). A call that a `respond_to?` guard protects still fires.",
+            "The value lost its interface type: a join with an untyped value, a helper parameter with no " \
+            "signature, or the result of a `&.` call on a value that may be nil. It reads as `untyped` there.",
+            "The call is outside a `Rigor::Plugin::Base` subclass, or inside `Rigor::Plugin::Base` itself.",
+            "The `plugin-api-surface` bleeding-edge feature is not enabled (the default)."
+          ],
+          suppression: "`# rigor:disable plugin.api-surface` on the call line, or " \
+                       "`disable: [\"plugin.api-surface\"]` in `.rigor.yml`. The fix is to call a member the " \
+                       "interface declares or a public namespace (`Rigor::Reflection`, ...).",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :off, strict: :off },
+          # The receiver's interface type comes from Rigor's own signatures and the member list is the
+          # interface's declaration, so a firing is a call outside the declared surface. It ships `:off`
+          # behind `bleeding_edge:` because it is a new discipline (ADR-50 Decision 3), not for lack of
+          # confidence.
+          evidence_tier: :high,
+          since: "0.4.8"
+        ),
+
         CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER => Entry.new(
           id: CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER,
           summary: "A comment uses a suppression marker Rigor does not recognise " \
@@ -1120,7 +1156,7 @@ module Rigor
 
       module_function
 
-      # Looks up a rule by canonical id, legacy alias, or family wildcard. Returns an Array<Entry>:
+      # Looks up a rule by canonical id, legacy alias, or family wildcard. Returns the matching entries:
       #
       # - canonical id → 1-element array,
       # - legacy alias → 1-element array (resolved to canonical),