rigortype 0.2.8 → 0.3.0

data/lib/rigor/environment/rbs_loader.rb

@@ -90,10 +90,48 @@ module Rigor
           add_project_signatures(env, signature_paths)
           add_virtual_rbs(env, virtual_rbs)
           synthesize_missing_namespaces(env)
-          resolved = env.resolve_type_names
+          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs)
           stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
         end
 
+        # True when `content` parses as an RBS signature. {#virtual_rbs_collision_quarantined} uses this to
+        # tell a collision-dropped virtual entry (parses, but absent from the env) from a parse-failed one
+        # (the synthesizer's own WD6 skip, reported separately).
+        def parseable_rbs?(content)
+          ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: "(rigor: virtual parse check)", content: content))
+          true
+        rescue ::RBS::BaseError
+          false
+        end
+
+        # Backstop for a virtual-vs-anything `RBS::DuplicatedDeclarationError` that only materialises at
+        # `resolve_type_names` (which rebuilds the env from `sources`). {.add_virtual_rbs}'s transactional
+        # rescue already handles the add-time case — empirically everything on rbs 4.x — but the rbs gemspec
+        # range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an rbs-internal choice
+        # this code must not depend on. Resolution rule is the same as the add-time path: the explicit
+        # signature wins, the colliding VIRTUAL buffer is dropped whole (`RBS::Environment#unload`) and
+        # resolution retries; every pass removes at least one virtual buffer, so the loop is bounded by the
+        # virtual-entry count. A duplicate involving no virtual buffer (sig-vs-sig), or an env without
+        # `#unload` (rbs 3.x), re-raises into the existing one-warning degrade path.
+        #
+        # The dropped set is not returned: consumers recover it from the built env via
+        # {#virtual_rbs_collision_quarantined}, which also works on a cache HIT where this build never ran.
+        def resolve_quarantining_virtual_collisions(env, virtual_rbs)
+          virtual_names = virtual_rbs.to_set { |name, _content| name.to_s }
+          (virtual_names.size + 1).times do
+            return [env, env.resolve_type_names]
+          rescue ::RBS::DuplicatedDeclarationError => e
+            raise unless env.respond_to?(:unload)
+
+            culprits = e.decls.filter_map { |decl| decl.location&.buffer&.name }
+                              .uniq.select { |name| virtual_names.include?(name) }
+            raise if culprits.empty?
+
+            env = env.unload(culprits)
+          end
+          [env, env.resolve_type_names]
+        end
+
         # ADR-5 robustness, second tier. A project `signature_paths:` RBS that *references* a type no loaded
         # signature declares — `def x: () -> DRb::DRbServer` when the `drb` RBS is not available, or a stale
         # reference to its own removed `Textbringer::EditorError` — makes
@@ -356,9 +394,20 @@ module Rigor
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
             add_parsed_decls(env, buffer, directives, decls)
           rescue ::RBS::BaseError
-            # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down. The
-            # plugin layer records a `source-rbs-synthesis-failed` info diagnostic in slice 2; here we just
-            # skip the entry.
+            # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down — for
+            # a parse error, skipping the entry is enough. But `RBS::Environment#add_source` appends to
+            # `env.sources` BEFORE inserting decls, so when the raise is a mid-insert
+            # `RBS::DuplicatedDeclarationError` (the entry declares a constant the project's own `sig/`
+            # already declares — the expected state for a project migrating between `sig/` and inline
+            # annotations, not an authoring error), the POISONED SOURCE is left behind, and
+            # `resolve_type_names` — which rebuilds the env from `sources` — re-raises the same error outside
+            # this rescue and collapses the WHOLE env to nil (measured on herb: 1,490 classes → 0, `require`
+            # itself stopped resolving, 74 false `call.unresolved-toplevel`). Make the skip transactional:
+            # drop the poisoned source. The explicit `.rbs` declaration wins — the spec keeps standalone
+            # `.rbs` files "the preferred place for complete type definitions" (`overview.md`) — and
+            # {#warn_about_virtual_rbs_collisions} names the dropped file. `sources` is the rbs 4.x shape;
+            # under the 3.x API this degrades to today's behaviour.
+            env.sources.reject! { |source| source.buffer.name == buffer.name } if env.respond_to?(:sources)
           end
         end
 
@@ -478,6 +527,55 @@ module Rigor
         names_synthesized_in(SYNTHETIC_NAMESPACE_BUFFER)
       end
 
+      # The project `signature_paths:` files that were QUARANTINED this run (they do not parse, so
+      # {RbsLoader.add_project_signatures} skipped them to keep the rest of the env alive), as
+      # `[absolute_path, first_error_line]` pairs. Memoised per loader: the detection re-parses only the user's
+      # own `sig/` set, but every consumer (the `rbs.coverage.quarantined-signature` diagnostic, `rigor doctor`,
+      # the stderr banner) reads it, and a cache HIT reaches it too — the env was built with the file already
+      # quarantined, so the condition is invisible in the cached env itself.
+      #
+      # @return [Array<Array(String, String)>] empty when every `signature_paths:` file parses.
+      def quarantined_signatures
+        @state[:quarantined] ||= self.class.quarantined_project_signatures(@signature_paths).freeze
+      end
+
+      # The total RBS-environment build failure captured this run, or nil when the env built. Unlike
+      # {#quarantined_signatures} — which the env survives, one file lighter, and which is re-derived by
+      # re-parsing so a cache HIT reports it too — a total failure (typically `RBS::DuplicatedDeclarationError`:
+      # a `signature_paths:` entry redeclaring a constant/class Rigor's bundled RBS already ships) collapses the
+      # WHOLE env to nil. A failed build produces no cached success to hide behind (nothing is persisted, so
+      # every run re-attempts and re-raises), so this is captured directly in {#env}'s rescue rather than
+      # re-derived. Forcing `env` (any query does) populates it.
+      #
+      # @return [Array(String, String, Array<String>), nil] `[error_class_name, first_error_line,
+      #   conflicting_buffer_names]`, or nil when the environment built successfully.
+      def env_build_failure
+        env unless @state[:env_loaded]
+        @state[:env_build_failure]
+      end
+
+      # Virtual (inline-synthesized) contributions dropped by the collision quarantine
+      # ({.resolve_quarantining_virtual_collisions}): buffer names absent from the built env even though the
+      # entry's content is non-empty and parses (a parse failure is the synthesizer's own WD6 skip, reported
+      # through the synthesis reporter instead). Derived from the env rather than recorded during build —
+      # the {#quarantined_signatures} trick — so a cache HIT, which never runs the build, reports the same
+      # condition: the marshalled env simply lacks the dropped buffers.
+      #
+      # @return [Array<String>] virtual buffer names (source-file paths) whose contribution was dropped.
+      def virtual_rbs_collision_quarantined
+        @state[:virtual_rbs_collisions] ||= begin
+          built = @state[:env]
+          if built.nil? || @virtual_rbs.empty?
+            [].freeze
+          else
+            present = built.buffers.to_set(&:name)
+            @virtual_rbs.filter_map do |name, content|
+              name if !content.empty? && !present.include?(name) && self.class.parseable_rbs?(content)
+            end.freeze
+          end
+        end
+      end
+
       # The referenced-but-undeclared types {.stub_missing_referenced_types} stubbed so the project classes
       # that mention them could build (e.g. an unavailable `DRb::DRbServer`, or a stale
       # `Textbringer::EditorError`). Recovered off the built env like {#synthesized_namespaces}, so it
@@ -970,8 +1068,10 @@ module Rigor
         @state[:env_loaded] = true
         @state[:env] = cache_store ? cached_env : build_env
         warn_about_quarantined_signatures
+        warn_about_virtual_rbs_collisions
         @state[:env]
       rescue ::RBS::BaseError => e
+        record_env_build_failure(e)
         warn_about_env_build_failure_once(e)
         @state[:env] = nil
       end
@@ -982,10 +1082,15 @@ module Rigor
       # is the visibility half of the fix: a shrinking diagnostic count must never be mistaken for a clean run
       # when it actually means "your sig/ stopped loading". No-op when `signature_paths:` is empty (the cost is
       # then a single empty-set check) or every file parses.
+      #
+      # `rigor check` ALSO reports this as the `rbs.coverage.quarantined-signature` diagnostic, which is what
+      # reaches JSON / SARIF / CI annotations / the LSP. The banner is kept because the commands that build an
+      # env WITHOUT producing a diagnostic stream (`coverage`, `sig-gen`) have no other channel, and a silently
+      # degraded env is exactly what misleads there too.
       def warn_about_quarantined_signatures
         return if @state[:quarantine_warned]
 
-        quarantined = self.class.quarantined_project_signatures(@signature_paths)
+        quarantined = quarantined_signatures
         return if quarantined.empty?
 
         @state[:quarantine_warned] = true
@@ -1002,6 +1107,60 @@ module Rigor
         )
       end
 
+      # The collision twin of {#warn_about_quarantined_signatures}: name, once per run, the source files
+      # whose inline-synthesized RBS was dropped because it collides with a declaration another signature
+      # source already made ({.resolve_quarantining_virtual_collisions} — the explicit `.rbs` wins). Without
+      # this the drop is silent, and "my `#:` annotation does nothing" has no visible cause. Reads the
+      # derived {#virtual_rbs_collision_quarantined}, so a cache HIT warns identically.
+      def warn_about_virtual_rbs_collisions
+        return if @state[:virtual_collision_warned]
+
+        dropped = virtual_rbs_collision_quarantined
+        return if dropped.empty?
+
+        @state[:virtual_collision_warned] = true
+        listed = dropped.first(QUARANTINE_WARN_LIMIT)
+        more = dropped.size - listed.size
+        lines = listed.map { |name| "    - #{name}" }
+        lines << "    … and #{more} more" if more.positive?
+        warn(
+          "rigor: dropped inline-RBS contribution(s) from #{dropped.size} file(s): they declare a
+  " \
+          "constant, alias, or global that another signature source (typically the project's own
+  " \
+          "`sig/`) already declares. The explicit `.rbs` declaration wins, so inline annotations in
+  " \
+          "these files do not bind. Remove the duplication from either side to restore them:
+" \
+          "#{lines.join("\n")}"
+        )
+      end
+
+      # Records the total RBS-environment build failure captured in {#env}'s rescue so the analysis layer can
+      # surface it as the `rbs.coverage.environment-build-failed` diagnostic (the twin of
+      # {#quarantined_signatures}: quarantine keeps the env alive minus one file, a total failure collapses the
+      # WHOLE env to nil, so every type-of query degrades to `Dynamic[top]` and most rules stop firing). Stored
+      # as `[error_class_name, first_error_line, conflicting_buffer_names]`. The buffer names are lifted off a
+      # `RBS::DuplicatedDeclarationError#decls` — the typical failure, a `signature_paths:` entry redeclaring a
+      # constant/class Rigor's bundled RBS already ships — so the diagnostic can name the colliding files.
+      def record_env_build_failure(error)
+        first_line = error.message.to_s.lines.first.to_s.strip
+        @state[:env_build_failure] = [error.class.name, first_line, env_build_conflict_buffers(error)].freeze
+      end
+
+      # The buffer (file) names carried by the colliding declarations of a `RBS::DuplicatedDeclarationError`, so
+      # the diagnostic names the conflicting signature files rather than guessing. A buffer name is a `String`
+      # path for a project `signature_paths:` file and a `Pathname` for a bundled RBS file, so each is coerced
+      # to `String`. Other RBS build errors carry no `.decls`; they yield an empty list and the diagnostic
+      # falls back to the message's first line alone.
+      def env_build_conflict_buffers(error)
+        return [].freeze unless error.respond_to?(:decls)
+
+        error.decls.filter_map { |decl| decl.location&.buffer&.name }.map(&:to_s).uniq.freeze
+      rescue ::RBS::BaseError, StandardError
+        [].freeze
+      end
+
       def warn_about_env_build_failure_once(error)
         return if @state[:env_build_warned]
 

data/lib/rigor/environment.rb

@@ -2,15 +2,18 @@
 
 require "digest"
 
+require_relative "environment/default_libraries"
 require_relative "environment/class_registry"
 require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
 require_relative "environment/reporters"
 require_relative "environment/hkt_registry_holder"
 require_relative "environment/constant_type_cache_holder"
+require_relative "environment/missing_gem_constant_index"
 require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/rbs_collection_discovery"
+require_relative "plugin/isolation"
 require_relative "environment/rbs_coverage_report"
 require_relative "inference/synthetic_method_index"
 require_relative "inference/project_patched_methods"
@@ -31,31 +34,8 @@ module Rigor
     DEFAULT_PROJECT_SIG_DIR = "sig"
     private_constant :DEFAULT_PROJECT_SIG_DIR
 
-    # Slice A stdlib expansion. Stdlib libraries that `Environment.for_project` loads on top of RBS core
-    # unless the caller passes an explicit `libraries:` array. Each entry MUST be a stdlib library name
-    # accepted by `RBS::EnvironmentLoader#has_library?`; unknown libraries MUST fail-soft
-    # (`RbsLoader#build_env` already filters through `has_library?`). The default set covers the common
-    # stdlib surface a Ruby program is likely to import (`pathname`, `optparse`, `json`, `yaml`, `fileutils`,
-    # `tempfile`, `uri`, `logger`, `date`) plus the analyzer-adjacent gems shipping their own RBS in this
-    # bundle (`prism`, `rbs`). On hosts where one of these libraries is not installed, the loader silently
-    # drops it.
-    #
-    # Callers MAY add to the default by passing `libraries: %w[csv ...]`; the explicit list is appended to
-    # `DEFAULT_LIBRARIES` and de-duplicated. Callers that need a strictly RBS-core view MUST construct an
-    # `RbsLoader` directly instead of going through `for_project`.
-    DEFAULT_LIBRARIES = %w[
-      pathname optparse json yaml fileutils tempfile tmpdir
-      stringio forwardable digest securerandom
-      uri logger date
-      pp delegate observable abbrev find tsort singleton
-      shellwords benchmark base64 did_you_mean
-      monitor mutex_m timeout
-      open3 erb etc ipaddr bigdecimal bigdecimal-math
-      prettyprint random-formatter time open-uri resolv
-      csv pstore objspace io-console cgi cgi-escape
-      strscan
-      prism rbs
-    ].freeze
+    # `DEFAULT_LIBRARIES` is defined in the light `environment/default_libraries.rb` (required below) so the
+    # ADR-87 WD4 boot-slimming probe can read it without loading the inference engine.
 
     # ADR-72 — a Gemfile.lock gem name mapped to the opt-in plugin id that ships the SAME core-ext RBS. When
     # that plugin is loaded the auto-overlay for the gem stands down, so the two never both declare the
@@ -84,7 +64,7 @@ module Rigor
                    rbs_extended_reporter: nil, boundary_cross_reporter: nil,
                    source_rbs_synthesis_reporter: nil,
                    synthetic_method_index: nil, project_patched_methods: nil,
-                   hkt_registry: nil)
+                   hkt_registry: nil, missing_rbs_gems: [], missing_rbs_bundle_path: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
       @plugin_registry = plugin_registry
@@ -109,6 +89,12 @@ module Rigor
       @hkt_registry_base = hkt_registry || Inference::HktRegistry::EMPTY
       @hkt_registry_holder = HktRegistryHolder.new
       @constant_type_cache = ConstantTypeCacheHolder.new
+      # ADR-82 WD9 — `[gem_name, version]` pairs for the locked gems with no resolvable RBS. The
+      # root-constant ownership index over them is built lazily (first unresolved constant read) so runs
+      # whose constants all resolve never pay the entry-file scan.
+      @missing_rbs_gems = missing_rbs_gems.freeze
+      @missing_rbs_bundle_path = missing_rbs_bundle_path
+      @missing_rbs_gem_constants_holder = HktRegistryHolder.new
       @name_scope = build_name_scope
       freeze
     end
@@ -133,6 +119,21 @@ module Rigor
       end
     end
 
+    # ADR-82 WD9 — the gem name owning `root_constant_name`, when that gem is locked in the project's
+    # Gemfile.lock, ships no resolvable RBS, and its entry file declares the constant at top level. Nil for
+    # everything else — the caller then keeps the generic provenance cause. The index is built once, lazily,
+    # from RubyGems metadata + a Prism parse of each gem's entry file; no gem code runs (see
+    # {MissingGemConstantIndex}). Under the fork pool a worker that never meets an unresolved constant never
+    # builds it.
+    def missing_rbs_gem_owner(root_constant_name)
+      return nil if @missing_rbs_gems.empty?
+
+      index = @missing_rbs_gem_constants_holder.fetch do
+        MissingGemConstantIndex.build(@missing_rbs_gems, bundle_path: @missing_rbs_bundle_path)
+      end
+      index[root_constant_name.to_s]
+    end
+
     # Backwards-compatible reporter accessors — every existing consumer (rbs_extended, method_dispatcher)
     # calls these. The frozen `@reporters` container is mutable for slot reassignment via
     # {#attach_reporters!} below.
@@ -220,6 +221,12 @@ module Rigor
           auto_detect: bundler_auto_detect,
           locked_gems: locked.empty? ? nil : locked
         ).map(&:to_s)
+        # ADR-82 WD9 — the resolved bundle root, so the missing-gem constant index reads each RBS-less gem's
+        # entry file from the TARGET's bundle (not rigor's own — see `MissingGemConstantIndex`). Resolved
+        # once here; passed through to the lazy index build.
+        bundle_root = resolve_target_bundle_root(
+          bundle_path: bundler_bundle_path, project_root: root, auto_detect: bundler_auto_detect
+        )
         # O4 Layer 3 slice 2 — when `rbs collection install` has been run for the target project, parse the
         # resulting `rbs_collection.lock.yaml` and feed each gem's `<collection_path>/<name>/<version>/`
         # directory into `signature_paths:`. Stdlib-typed entries are skipped (already covered by
@@ -248,10 +255,9 @@ module Rigor
         # diagnostic. Appended last so any RBS the project already supplies wins, and skipped for a gem whose
         # opt-in plugin twin is loaded (no duplicate declaration). The paths ride in
         # `loader_signature_paths`, so the env cache descriptor digests them for free.
-        overlay_paths = gem_overlay_paths(
-          locked: locked, default_libraries: merged_libraries,
-          bundle_sig_paths: gem_sig_paths, rbs_collection_paths: collection_paths,
-          plugin_registry: plugin_registry
+        missing_gems, overlay_paths = missing_gems_and_overlay_paths(
+          locked: locked, default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
+          rbs_collection_paths: collection_paths, plugin_registry: plugin_registry
         )
         loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths +
                                  collection_paths + overlay_paths
@@ -286,7 +292,9 @@ module Rigor
           source_rbs_synthesis_reporter: source_rbs_synthesis_reporter,
           synthetic_method_index: synthetic_method_index,
           project_patched_methods: project_patched_methods,
-          hkt_registry: Builtins::HktBuiltins.registry
+          hkt_registry: Builtins::HktBuiltins.registry,
+          missing_rbs_gems: missing_gems,
+          missing_rbs_bundle_path: bundle_root
         )
       end
       # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
@@ -298,22 +306,42 @@ module Rigor
         sig.directory? ? [sig] : []
       end
 
-      # ADR-72 — resolve the bundled RBS overlay directories to load for this project. A gem is eligible when
-      # it is locked in the Gemfile.lock, classified `:missing` by {RbsCoverageReport} (no RBS through
-      # default-library / vendored / bundle-`sig/` / rbs-collection), and its conflicting opt-in plugin (if
-      # any) is not loaded. Returns `[Pathname]`, deterministically ordered, or `[]` when no lockfile / no
-      # eligible gem.
-      def gem_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
-                            rbs_collection_paths:, plugin_registry:)
-        return [] if locked.empty?
-
-        missing = RbsCoverageReport.classify(
+      # ADR-82 WD9 — the resolved bundle root for the missing-gem constant index, doubling (ADR-90) as the
+      # hand-off to the plugin isolation layer: ADR-39 target-library invocation (`Plugin::Inflector` →
+      # activesupport, the Rack status table) can then require the analyzed project's own locked gems when
+      # Rigor's host gem environment does not carry them — the standalone `gem install rigortype` case,
+      # where activesupport is deliberately not a runtime dependency.
+      def resolve_target_bundle_root(bundle_path:, project_root:, auto_detect:)
+        bundle_root = BundleSigDiscovery.resolve_bundle_path(
+          bundle_path: bundle_path, project_root: project_root, auto_detect: auto_detect
+        )&.to_s
+        Plugin::Isolation.target_bundle_root = bundle_root
+        bundle_root
+      end
+
+      # The `:missing` classification (locked gems with no RBS through any resolution path), computed once
+      # and consumed twice: as `[gem_name, version]` pairs for the ADR-82 WD9 constant-ownership index, and
+      # as the eligible-gem set for the ADR-72 overlay resolution. Returns `[pairs, overlay_paths]`.
+      def missing_gems_and_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
+                                         rbs_collection_paths:, plugin_registry:)
+        return [[], []] if locked.empty?
+
+        rows = RbsCoverageReport.classify(
           locked_gems: locked, default_libraries: default_libraries,
           bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
-        ).select { |row| row.source == :missing }.map(&:gem_name)
+        ).select { |row| row.source == :missing }
+        overlays = gem_overlay_paths(missing_gem_names: rows.map(&:gem_name), plugin_registry: plugin_registry)
+        [rows.map { |row| [row.gem_name, row.version] }, overlays]
+      end
+
+      # ADR-72 — resolve the bundled RBS overlay directories to load for this project. A gem is eligible when
+      # it is classified `:missing` (see {missing_rbs_gem_rows}) and its conflicting opt-in plugin (if any)
+      # is not loaded. Returns `[Pathname]`, deterministically ordered, or `[]` when no eligible gem.
+      def gem_overlay_paths(missing_gem_names:, plugin_registry:)
+        return [] if missing_gem_names.empty?
 
         loaded_ids = plugin_registry ? plugin_registry.ids.to_set : Set.new
-        eligible = missing.reject do |gem_name|
+        eligible = missing_gem_names.reject do |gem_name|
           plugin_id = GEM_OVERLAY_PLUGIN_IDS[gem_name]
           plugin_id && loaded_ids.include?(plugin_id)
         end.sort

data/lib/rigor/inference/budget_trace.rb

@@ -8,6 +8,14 @@ module Rigor
     # docs/type-specification/inference-budgets.md is not yet wired); counting how often each fires on a real
     # project is the only way to see where inference actually stops.
     #
+    # A second family of counters (the `MEMO_*` categories) profiles the ADR-57 user-method return memo
+    # (`ExpressionTyper#infer_user_method_return`) rather than a cutoff — inference entries, memo hits/misses,
+    # the split of non-stored results by reason, and body-evaluation (compute) entries — plus two
+    # per-signature distributions (body-eval count and distinct-memo-key count). This is the evidence for the
+    # next return-memo design slice: a finalization-aware taint gate (recover the `consult-tainted`
+    # non-stores) vs memo-key normalization (collapse arg-granularity thrash — a signature whose distinct-key
+    # count far exceeds its body-eval savings).
+    #
     # Three categories, one per guard site:
     #
     # - {RECURSION_GUARD} — `ExpressionTyper#infer_user_method_return` detected a `(receiver, method)` cycle
@@ -44,9 +52,42 @@ module Rigor
       # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint.
       BLOCK_WRITEBACK_CAP = :block_writeback_cap
 
+      # ADR-57 return-memo profile counters (not cutoffs — see the module doc). All bumped by
+      # `ExpressionTyper#infer_user_method_return` / `#compute_user_method_return`.
+      # - {MEMO_ENTRIES} — every `infer_user_method_return` entry (a user-method return inference).
+      # - {MEMO_HITS} / {MEMO_MISSES} — the memo was consulted (candidate frame) and the key was present /
+      #   absent. Consults = hits + misses.
+      # - {MEMO_BODY_EVALS} — every `compute_user_method_return` entry (a body-evaluation compute; some are
+      #   in-cycle re-entries that consult an ADR-55 summary rather than walk the body — those coincide with a
+      #   `RECURSION_GUARD` hit). Body evals = misses + on-stack refusals (ADR-84 WD3 reduced candidacy to the
+      #   on-stack check, so unroll-in-flight refusals are structurally gone).
+      # - {MEMO_REFUSE_ON_STACK} — the frame was not a memo candidate (bypassed the memo and computed): its
+      #   plain `(receiver, method)` signature was already on the recursion guard stack.
+      # - {MEMO_REFUSE_UNROLL} — pre-ADR-84 blanket refusal (constant-arg unroll in flight). Kept in the table
+      #   as the ADR-84 WD3 gate pin: structurally unreachable, must read ~0.
+      # - {MEMO_REFUSE_CONSULT_TAINTED} — a candidate frame computed a result but an ADR-55 fixpoint summary
+      #   was *consulted* during the compute, so the result is a transient Kleene iterate and was NOT stored.
+      # - {MEMO_REFUSE_TRANSIENT} — ADR-84 WD3: a candidate frame's compute bracket saw a
+      #   transient-machinery event (recursion-guard hit / unroll-fuel exhaustion / ADR-55 WD1 clamp /
+      #   fixpoint-cap collapse — `ExpressionTyper#note_transient_fallback`) that referenced a stack frame
+      #   BELOW the bracket's entry depth, so the ancestor context influenced the result and it was NOT
+      #   stored. Own-machinery events (a recursive method's own fixpoint) do not refuse; top-of-stack
+      #   computes are standalone by construction. Replaces the blanket unroll-in-flight exclusion.
+      MEMO_ENTRIES = :memo_entries
+      MEMO_HITS = :memo_hits
+      MEMO_MISSES = :memo_misses
+      MEMO_BODY_EVALS = :memo_body_evals
+      MEMO_REFUSE_ON_STACK = :memo_refuse_on_stack
+      MEMO_REFUSE_UNROLL = :memo_refuse_unroll
+      MEMO_REFUSE_CONSULT_TAINTED = :memo_refuse_consult_tainted
+      MEMO_REFUSE_TRANSIENT = :memo_refuse_transient
+
       CATEGORIES = [
         RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
-        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP
+        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP,
+        MEMO_ENTRIES, MEMO_HITS, MEMO_MISSES, MEMO_BODY_EVALS,
+        MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_CONSULT_TAINTED,
+        MEMO_REFUSE_TRANSIENT
       ].freeze
 
       # Distribution (histogram) categories — read-only observations of a value's size at a site, used to
@@ -55,12 +96,28 @@ module Rigor
       # `Combinator.union` produces — the distribution the `union_size` budget default should be set from.
       UNION_ARITY = :union_arity
 
-      DISTRIBUTION_CATEGORIES = [UNION_ARITY].freeze
+      # ADR-57 return-memo per-signature distributions — `{signature => count}` maps, NOT integer-size
+      # histograms, so `summarize` (percentiles over integer values) does not apply; read them with
+      # {distribution}. Both keyed by the `"Receiver#method"` plain signature.
+      # - {MEMO_BODY_EVAL_BY_SIGNATURE} — body-eval (compute) count per signature (via {observe}).
+      # - {MEMO_DISTINCT_KEY_BY_SIGNATURE} — distinct memo keys per signature (via {observe_distinct}), i.e.
+      #   how many `(receiver, arg-type)` variants a signature was memoised under. A count far above the
+      #   signature's body-eval savings is arg-granularity thrash — the key-normalization candidate.
+      MEMO_BODY_EVAL_BY_SIGNATURE = :memo_body_eval_by_signature
+      MEMO_DISTINCT_KEY_BY_SIGNATURE = :memo_distinct_key_by_signature
+
+      DISTRIBUTION_CATEGORIES = [
+        UNION_ARITY, MEMO_BODY_EVAL_BY_SIGNATURE, MEMO_DISTINCT_KEY_BY_SIGNATURE
+      ].freeze
 
       @enabled = !ENV["RIGOR_BUDGET_TRACE"].to_s.empty?
       @mutex = Mutex.new
       @counts = Hash.new(0)
       @distributions = Hash.new { |h, k| h[k] = Hash.new(0) }
+      # Auxiliary de-duplication state for {observe_distinct}: category → Set of the `[bucket, member]`
+      # pairs already counted, so a repeated `(signature, memo-key)` observation is counted once. Only ever
+      # written when tracing is enabled; not part of the reported surface.
+      @distinct_seen = Hash.new { |h, k| h[k] = Set.new }
 
       module_function
 
@@ -101,6 +158,23 @@ module Rigor
         @mutex.synchronize { @distributions[category][value] += 1 }
       end
 
+      # Records one observation of `member` into `category`'s `{bucket => count}` map, but only the FIRST time
+      # a given `(bucket, member)` pair is seen — so the resulting count per bucket is the number of DISTINCT
+      # members, not the number of observations. Used for the distinct-memo-key-per-signature distribution.
+      # No-op (one boolean check) when disabled.
+      def observe_distinct(category, bucket, member)
+        return unless @enabled
+
+        @mutex.synchronize do
+          seen = @distinct_seen[category]
+          pair = [bucket, member]
+          unless seen.include?(pair)
+            seen << pair
+            @distributions[category][bucket] += 1
+          end
+        end
+      end
+
       # Frozen `{value => count}` histogram for a distribution category.
       def distribution(category)
         @mutex.synchronize { @distributions[category].dup.freeze }
@@ -137,6 +211,7 @@ module Rigor
         @mutex.synchronize do
           @counts.clear
           @distributions.clear
+          @distinct_seen.clear
         end
       end
     end

data/lib/rigor/inference/closure_escape_analyzer.rb

@@ -144,6 +144,16 @@ module Rigor
       RANGE_EXTRA = %i[step].freeze
       INTEGER_EXTRA = %i[times upto downto].freeze
 
+      # IO / File / StringIO line- and byte-iteration methods invoke the block immediately, once per line /
+      # byte / char, and never retain it — the same immediate-invocation contract as `Array#each`. Both the
+      # singleton `File.foreach` / `IO.foreach` (receiver `singleton(File)` → class name "File") and the
+      # instance `io.each_line` / `each_char` … forms resolve through the same class-name key. Without these,
+      # `File.foreach(path) { case … when … then flag = true when … then return true if flag end }` classifies
+      # `:unknown` and misses the loop-body re-narrowing, so a local written in one `when` arm reads its
+      # pre-loop value in a sibling arm and a guarding condition folds to a spurious constant.
+      IO_ITERATION = %i[each_line each each_byte each_char each_codepoint].freeze
+      IO_SINGLETON_ITERATION = %i[foreach].freeze
+
       NON_ESCAPING = {
         "Array" => (ENUMERABLE_NON_ESCAPING + ARRAY_EXTRA).freeze,
         "Hash" => (ENUMERABLE_NON_ESCAPING + HASH_EXTRA).freeze,
@@ -151,7 +161,10 @@ module Rigor
         "Set" => ENUMERABLE_NON_ESCAPING,
         "Integer" => INTEGER_EXTRA,
         "Enumerator" => ENUMERABLE_NON_ESCAPING,
-        "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING
+        "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING,
+        "IO" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
+        "File" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
+        "StringIO" => IO_ITERATION
       }.freeze
 
       # Methods that are documented to **retain** the block past the call. The block is stored or scheduled,

data/lib/rigor/inference/def_handle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-85 WD3 — a lazy reference to a `Prism::DefNode` stored in a cross-file discovery table, in place of
+    # the live node itself. When an incremental recheck rebuilds the discovery index from cached per-file seed
+    # bundles (ADR-85 WD2), the `def_nodes` / `singleton_def_nodes` tables carry handles for every unchanged
+    # file's methods: the file was never parsed this run, so there is no live node to store. A handle records
+    # the three things needed to resolve or fingerprint it without the node:
+    #
+    # - `path` + `node_id` — the resolution key. The per-run parse memo ({Scope#resolve_def_handle}) parses the
+    #   file once and returns the `Prism::DefNode` whose `node_id` matches (Prism `node_id` is stable across
+    #   repeated parses of identical bytes). `name` is the cross-check: a resolved node whose `name` differs
+    #   from the handle's forces a fresh walk (bundle/source skew that the digest gate should make impossible —
+    #   conservative, never silent).
+    # - `fingerprint` — the SHA-256 of the def's source slice, captured when the bundle was built. This lets
+    #   `Runner#symbol_fingerprints` read the change-detection fingerprint (ADR-46 slice 4) off the handle
+    #   without re-parsing the file — the one value-deref consumer besides the three accessor choke points.
+    #
+    # Marshal-clean by construction (Integer + Strings), so it rides the `IncrementalSnapshot` blob directly.
+    DefHandle = Data.define(:path, :node_id, :name, :fingerprint)
+  end
+end