rigortype 0.2.8 → 0.3.0

data/lib/rigor/inference/expression_typer.rb

@@ -3,8 +3,10 @@
 require "prism"
 
 require_relative "../type"
+require_relative "../reflection"
 require_relative "../ast"
 require_relative "../source/constant_path"
+require_relative "../source/node_children"
 require_relative "../analysis/self_call_resolution_recorder"
 require_relative "block_parameter_binder"
 require_relative "body_fixpoint"
@@ -209,6 +211,11 @@ module Rigor
       }.freeze
       private_constant :PRISM_DISPATCH
 
+      # Sentinel distinguishing "the key is not a value-pinned literal" from the legitimate literal hash
+      # keys `nil` and `false` (see {#static_hash_key}).
+      NO_STATIC_HASH_KEY = Object.new.freeze
+      private_constant :NO_STATIC_HASH_KEY
+
       def initialize(scope:, tracer: nil)
         @scope = scope
         @tracer = tracer
@@ -244,6 +251,29 @@ module Rigor
         fallback_for(node, family: :prism)
       end
 
+      # ADR-89 WD2 — the return type of `def_node` called with `receiver` / `arg_types`, computed exactly as a
+      # resolved in-body dispatch does (through the ADR-84 memo, so it is cheap and yields FINAL values only).
+      # Public entry point for the incremental session's return-summary re-evaluation: it re-drives a
+      # declaration-stable changed callee at each previously-observed call key to prove its return is
+      # unchanged before skipping the callee's symbol dependents. nil for an abstract / bodyless def, or when
+      # the memo refuses a transient result — the caller treats either as "not provably stable" (keeps the
+      # dependents), the conservative direction.
+      def return_type_for(def_node, receiver, arg_types)
+        infer_user_method_return(def_node, receiver, arg_types)
+      end
+
+      # ADR-89 WD2 — the current run's return memo bucket as `{ def_node => [MemoEntry, …] }` (only entries
+      # that carry a call descriptor, i.e. every stored entry). Read by the incremental session right after a
+      # recording run to harvest each analyzed callee's observed call keys → return descriptors. Returns an
+      # empty hash when no bucket exists (a run that memoised nothing). Class method: the bucket lives on
+      # `Thread.current`, independent of any one `ExpressionTyper` instance.
+      def self.harvest_return_memo
+        slot = Thread.current[RETURN_MEMO_KEY]
+        return {} if slot.nil?
+
+        slot[1].transform_values(&:values)
+      end
+
       private
 
       attr_reader :scope, :tracer
@@ -385,75 +415,49 @@ module Rigor
       # `Inference::FallbackTracer` from inside `Rigor::CLI::Foo` resolves to
       # `Rigor::Inference::FallbackTracer`.
       def type_of_constant_read(node)
-        resolve_constant_name(node.name.to_s) || fallback_for(node, family: :prism)
+        resolve_constant_name(node.name.to_s) || unresolved_constant_fallback(node, node.name.to_s)
       end
 
       def type_of_constant_path(node)
         full_name = Source::ConstantPath.qualified_name_or_nil(node)
         return fallback_for(node, family: :prism) if full_name.nil?
 
-        resolve_constant_name(full_name) || fallback_for(node, family: :prism)
+        resolve_constant_name(full_name) || unresolved_constant_fallback(node, full_name)
       end
 
-      # Try the literal name first, then walk Ruby's lexical lookup by progressively prefixing the surrounding
-      # class path (peeled one `::segment` at a time). For each candidate the lookup consults
-      # `Environment#singleton_for_name` (a class object) and then `Environment#constant_for_name` (a
-      # non-class constant value such as `BUCKETS: Array[Symbol]`). Returns the matched `Rigor::Type` or nil;
-      # the caller decides whether to fall back.
-      def resolve_constant_name(name)
-        env = scope.environment
-        discovered = scope.discovered_classes
-        in_source = scope.in_source_constants
-        lexical_constant_candidates(name).each do |candidate|
-          singleton = env.singleton_for_name(candidate)
-          return singleton if singleton
-
-          in_source_class = discovered[candidate]
-          return in_source_class if in_source_class
-
-          # In-source value-bearing constants take precedence over RBS constant decls because user code is
-          # the authoritative source for its own constants.
-          in_source_value = in_source[candidate]
-          return in_source_value if in_source_value
-
-          value = env.constant_for_name(candidate)
-          return value if value
-        end
-        nil
-      end
+      # ADR-82 WD9 — an unresolved constant whose root name a locked, RBS-less gem declares carries the
+      # `external_gem_without_rbs` cause instead of the generic `unsupported_syntax`. The constant read is
+      # where the class name is last visible (a no-RBS gem's receiver never types Nominal, so the dispatch
+      # tiers that record this cause under ADR-10 / `pre_eval:` opt-ins can't see it); WD6 chain inheritance
+      # then carries the cause through `Faraday.new.get(...)`. Side-channel only — the type stays the same
+      # `Dynamic[top]`, and an unindexed constant (project typo, unanalyzed project path) keeps the generic
+      # cause: the fail-open direction is a missing label, never a wrong one.
+      def unresolved_constant_fallback(node, full_name)
+        root = full_name.delete_prefix("::").split("::").first
+        owner = root && scope.environment.missing_rbs_gem_owner(root)
+        return fallback_for(node, family: :prism) unless owner
 
-      # The candidate qualified names to try, in Ruby's lexical order: most-qualified first (the surrounding
-      # class path joined to `name`), then progressively less-qualified, then the bare `name`. Top-level
-      # scopes (no `self_type`) yield only `[name]`, preserving the pre-walk behaviour.
-      def lexical_constant_candidates(name)
-        prefix = enclosing_class_path
-        candidates = []
-        while prefix && !prefix.empty?
-          candidates << "#{prefix}::#{name}"
-          # Strip the last `::` segment without `rpartition`'s throwaway 3-element array + extra substrings
-          # (this loop is the sole caller of the `String#rpartition` allocation seen in the profile): `rindex`
-          # + slice gives the same prefix, or nil.
-          idx = prefix.rindex("::")
-          prefix = idx ? prefix[0, idx] : nil
-        end
-        candidates << name
-        candidates
+        inner = dynamic_top
+        record_fallback(node, family: :prism, inner_type: inner, origin: DynamicOrigin::EXTERNAL_GEM_WITHOUT_RBS)
+        scope.record_dynamic_origin(node, DynamicOrigin::EXTERNAL_GEM_WITHOUT_RBS)
+        inner
       end
 
-      # Pulls the enclosing qualified class name out of `scope.self_type` when one is set. `Nominal[T]` and
-      # `Singleton[T]` both expose `class_name`. Returns nil when no class context is available (top-level).
-      def enclosing_class_path
-        st = scope.self_type
-        case st
-        when Type::Nominal, Type::Singleton then st.class_name
-        end
+      # Resolves a constant reference through Ruby's lexical constant lookup. Delegates to the shared
+      # `Reflection.resolve_constant_type` owner so the same walk (registry singleton, discovered class,
+      # in-source value, RBS constant, across the peeled `::` prefix candidates) is reused by
+      # `Inference::Narrowing`'s `Constant[Regexp]` match-operand recognition. Returns the matched
+      # `Rigor::Type` or nil; the caller decides whether to fall back.
+      def resolve_constant_name(name)
+        Reflection.resolve_constant_type(name, scope: scope)
       end
 
       # Slice 5 phase 1 upgrades hash literals to `HashShape{...}` when every entry is a static `AssocNode`
-      # whose key is a `SymbolNode` or `StringNode` with a known value (covering the `{ a: 1, "b" => 2 }`
-      # pattern and falling back to the generic `Hash[K, V]` form otherwise). Splatted entries (`{ **other }`)
-      # and dynamic keys widen to the underlying `Hash[K, V]` form by unioning the types each entry exposes;
-      # when no concrete pair survives we fall back to the raw `Hash` so callers stay backward compatible.
+      # whose key is a value-pinned scalar literal — Symbol, plain String, Integer, Float, `true`, `false`,
+      # or `nil` (covering `{ a: 1, "b" => 2 }` and `{ 1 => 2, 1.0 => 4 }` alike) — falling back to the
+      # generic `Hash[K, V]` form otherwise. Splatted entries (`{ **other }`) and dynamic keys widen to the
+      # underlying `Hash[K, V]` form by unioning the types each entry exposes; when no concrete pair
+      # survives we fall back to the raw `Hash` so callers stay backward compatible.
       def type_of_hash(node)
         elements = node.respond_to?(:elements) ? node.elements : []
         # v0.0.7 — `{}` resolves to the empty `HashShape{}` carrier rather than `Nominal[Hash]`, mirroring the
@@ -473,16 +477,22 @@ module Rigor
         )
       end
 
-      # Builds `HashShape{...}` when every entry is an `AssocNode` whose key is a static Symbol or String
-      # literal. Returns nil otherwise so the caller falls back to the generic shape.
+      # Builds `HashShape{...}` when every entry is an `AssocNode` whose key is a value-pinned scalar
+      # literal (Symbol, plain String, Integer, Float, true, false, nil). Returns nil otherwise so the
+      # caller falls back to the generic shape.
+      #
+      # Duplicate keys are LAST-WINS, matching the runtime (`{ a: 1, a: 2 }` keeps `a: 2`; Ruby itself
+      # only warns under `-w`). Key identity is Ruby `Hash` `eql?` identity because `pairs` is a native
+      # Hash — `1` and `1.0` stay distinct entries, `1.0` and `1.00` collide. The plain re-assignment
+      # also reproduces the runtime's ordering: the key keeps its FIRST insertion position while the
+      # value comes from the LAST occurrence.
       def static_hash_shape_for(elements)
         pairs = {}
         elements.each do |entry|
           return nil unless entry.is_a?(Prism::AssocNode)
 
           key = static_hash_key(entry.key)
-          return nil if key.nil?
-          return nil if pairs.key?(key)
+          return nil if key.equal?(NO_STATIC_HASH_KEY)
 
           pairs[key] = type_of(entry.value)
         end
@@ -491,16 +501,22 @@ module Rigor
         Type::Combinator.hash_shape_of(pairs)
       end
 
-      # Returns the static (Symbol|String) literal carried by a hash key node, or nil when the key is
-      # dynamic. We only treat SymbolNode#value and StringNode#unescaped as static when they are non-nil
-      # (interpolation produces a nil unescaped).
+      # Returns the value-pinned scalar literal carried by a hash key node, or {NO_STATIC_HASH_KEY} when
+      # the key is dynamic (a computed expression, an interpolated string — SymbolNode#value /
+      # StringNode#unescaped are nil under interpolation — a constant, a local, …). `nil` / `false` are
+      # real key values here, hence the sentinel rather than a nil return.
       def static_hash_key(node)
         case node
         when Prism::SymbolNode
           raw = node.value
-          raw&.to_sym
+          raw.nil? ? NO_STATIC_HASH_KEY : raw.to_sym
         when Prism::StringNode
-          node.unescaped
+          node.unescaped || NO_STATIC_HASH_KEY
+        when Prism::IntegerNode, Prism::FloatNode then node.value
+        when Prism::TrueNode then true
+        when Prism::FalseNode then false
+        when Prism::NilNode then nil
+        else NO_STATIC_HASH_KEY
         end
       end
 
@@ -1591,18 +1607,106 @@ module Rigor
       # args change folds (`factorial(5)` vs `factorial(6)`), so a coarser key would serve a stale fold. The
       # third unsafe dimension — the ADR-55 recursion machinery (unroll fuel / fixpoint Kleene
       # assumption / WD1 clamp) producing a TRANSIENT result rather than a final return — is excluded
-      # structurally: the memo is consulted and populated ONLY when the incoming guard stack is empty (a
-      # genuine top-of-stack entry, whose result is final and cannot be an in-progress assumption or a
-      # clamped value). Frames entered with a non-empty stack bypass the memo entirely and compute as before.
+      # post-hoc (ADR-84 WD3): candidacy only requires that the plain signature not already be on the
+      # recursion guard stack (a frame inside its own cycle returns a Kleene iterate by construction), and
+      # the store gate brackets the compute over the transient-event depth log
+      # (TRANSIENT_EVENT_DEPTHS_KEY), refusing only when an event referenced a frame BELOW the bracket's
+      # entry depth — proof the ancestor context (an in-flight ancestor summary, the shared unroll fuel, a
+      # possibly-ancestor-caused clamp) influenced the result. Events at-or-above the entry depth are the
+      # compute's own deterministic machinery — a recursive method's own converged fixpoint stores from a
+      # top-of-stack entry (standalone by construction: fuel reseeds, summary tables cleared at the
+      # previous drain) — and a nested compute whose bracket saw no below-entry event ran as if standalone
+      # (fuel consumed without exhausting is invisible; every summary read fires a logged guard event). A
+      # memo HIT while an unroll is merely in flight elsewhere on the stack is legal (stored values are
+      # final and context-free). This replaced the blanket unroll-in-flight candidacy exclusion, which
+      # refused 82% of mail's body evaluations for results that were overwhelmingly final (PR #79
+      # counters; ADR-84).
       #
-      # Keyed by the identity of the frozen discovery `def_nodes` table (a new analysis generation lands in
-      # a fresh bucket, mirroring `class_graph_buckets`) then by the identity of the `def_node` and the
-      # `[receiver, *args]` descriptor tuple. `ExpressionTyper` is rebuilt per `Scope#type_of`, so the store
-      # lives on `Thread.current`; fork-pool workers are separate processes, so it never crosses a project
-      # boundary.
+      # Bucket scope (ADR-84 WD2): ONE bucket per analysis run, keyed by the identity of the run-generation
+      # token `Analysis::Runner#run_analysis` mints and seeds through `scope.discovery` — hits cross
+      # consumer-file boundaries within a run, and a re-run in the same process (LSP re-check, ADR-62 warm
+      # loop) rolls the bucket over. Scopes without a runner seed (single-file probes) fall back to the
+      # per-file merged `discovered_def_nodes` identity — exactly the pre-WD2 per-file scope. Inside the
+      # bucket, entries key on the `def_node`'s object identity (the identity Hash holds the node strongly,
+      # so a collected parse can never recycle an object id into a stale hit) and then on the
+      # `[receiver, *args]` descriptor tuple; a callee may appear under at most two node identities per run
+      # (the project-index parse every OTHER file resolves through, plus the defining file's own analysis
+      # parse). Only the current generation's bucket is retained (single slot) — a rolled-over run's entries
+      # become garbage instead of accumulating across LSP runs. `ExpressionTyper` is rebuilt per
+      # `Scope#type_of`, so the store lives on `Thread.current`; fork-pool workers are separate processes,
+      # so it never crosses a project boundary (ADR-84 WD5).
       RETURN_MEMO_KEY = :__rigor_user_method_return_memo__
       private_constant :RETURN_MEMO_KEY
 
+      # ADR-84 WD2 — one memo entry: the final inferred return plus, when the entry was computed under
+      # ADR-46 dependency recording, the frozen `Analysis::DependencyRecorder::ReadSet` its body walk
+      # produced (nil on non-recording runs — recording is decided per run and the bucket never outlives a
+      # run, so a recording run only ever hits entries that carry a read-set; pinned by
+      # return_memo_recording_spec's rollover example). ADR-89 WD2 additionally carries the CALL DESCRIPTOR
+      # (`receiver` + `arg_types`) so the incremental session can harvest each observed call key and persist
+      # it as a return-summary — a recheck re-evaluates the (declaration-stable) callee at those keys and,
+      # when every return is unchanged, skips its symbol dependents. Carrying two frozen type refs is
+      # negligible on the memo-store path (already in scope) and never enters memo equality (entries are
+      # keyed by `memo_key`, retrieved by `.result` / `.read_set`).
+      MemoEntry = Data.define(:result, :read_set, :receiver, :arg_types)
+      private_constant :MemoEntry
+
+      # ADR-84 WD3 — thread-local transient-machinery event log, appended by `note_transient_fallback` at
+      # EVERY site where the ADR-55 recursion machinery substitutes transient state for a plain body
+      # evaluation. Each entry is the STACK POSITION (guard-stack index) of the frame whose in-flight state
+      # the event referenced — the consulted owner for a guard hit, 0 for the whole-stack resources (shared
+      # unroll fuel; conservatively the clamp), the owner's own position for its cap collapse.
+      # `consult_and_store_return_memo` brackets a candidate's compute over the log and refuses to store
+      # only when an event referenced a frame BELOW the bracket's entry depth: such an event proves the
+      # ancestor context influenced the result, while events at-or-above the entry depth are the compute's
+      # OWN deterministic machinery (a recursive method's own converged fixpoint, a sub-cycle that opened
+      # and closed inside the bracket) which a standalone recompute reproduces event-for-event. A
+      # top-of-stack compute (entry depth 0) can never see a below-entry event — it is standalone by
+      # construction (fuel reseeds on an empty stack, the summary tables were cleared at the previous
+      # drain). Cleared with the other per-outermost-entry tables when the guard stack drains. LOAD-BEARING:
+      # unlike `BudgetTrace` counters the log must be maintained on every run, not only under
+      # RIGOR_BUDGET_TRACE.
+      #
+      # Audit table (ADR-84 WD3) — every early-return / fallback in the recursion machinery, each either
+      # LOGGED (routes through `note_transient_fallback` with the referenced frame's position) or PROVABLY
+      # FINAL (a deterministic pure function of the frame's own inputs, so a standalone recompute
+      # reproduces it):
+      #
+      #   compute_user_method_return
+      #     - in-cycle re-entry (`stack.include?(signature)` → `consult_summary`)  LOGGED at the consulted
+      #       owner's stack position (the outermost frame carrying the plain signature — the seeder whose
+      #       in-flight Kleene iterate the re-entry returns)
+      #   evaluate_guarded_user_method_body
+      #     - non-outermost plain evaluation, clamp pass-through                   PROVABLY FINAL (plain
+      #       body eval; nested transient events log at their own sites)
+      #     - `clamp_unroll_result` clamp branch (ADR-55 WD1 → `untyped`)          LOGGED at 0 (the
+      #       would-have-been-guarded match may be an ancestor frame; position not threaded — conservative)
+      #   fixpoint_user_method_return
+      #     - `degrade_entangled_fixpoint` (foreign in-flight consult)             LOGGED at the degrading
+      #       owner's own position (the foreign consult that caused it was already logged at the ancestor's
+      #       position by the guard site, which is what taints the enclosing brackets)
+      #     - "summary never consulted" early return (body did not recurse)        PROVABLY FINAL
+      #     - `resolve_bot_collapse` (widened re-run / explicit-return floor)      PROVABLY FINAL in itself
+      #       (deterministic); transient events inside the re-run log at their own sites
+      #     - `fixpoint_step` convergence (`joined == assumption`)                 converged value; any
+      #       consults the iterations performed were already LOGGED at the guard site
+      #     - `fixpoint_step` cap collapse (`RECURSION_FIXPOINT_CAP` → `untyped`)  LOGGED at the owner's own
+      #       position (per-owner constant cap — deterministic for every enclosing bracket; the iterates'
+      #       context-dependence, if any, logs separately at its own sites)
+      #   unroll helpers
+      #     - `unroll_fuel_remaining` exhaustion (extended key denied → plain)     LOGGED at 0 (fuel is ONE
+      #       shared resource seeded at stack bottom, so a nested frame's unroll budget depends on what ran
+      #       before it — the hazard the blanket exclusion used to over-approximate)
+      #     - `constant_argument_value_key` / `pinned_value_descriptor` nil        PROVABLY FINAL (pure
+      #       functions of `arg_types`)
+      #
+      # Adding a fallback? Route it through `note_transient_fallback` unless it is provably final in the
+      # sense above — position 0 is always a sound (conservative) choice; spec/rigor/inference/
+      # return_memo_taint_spec.rb pins this (no raw `BudgetTrace.hit` on the recursion categories outside
+      # the helper).
+      TRANSIENT_EVENT_DEPTHS_KEY = :__rigor_user_method_transient_event_depths__
+      private_constant :TRANSIENT_EVENT_DEPTHS_KEY
+
       # Per-inference recursion context threaded through the guard / fixpoint helpers (ADR-55 slice 2).
       # Bundles the call descriptor (`receiver`, `arg_types`, `plain_signature`), the thread-local summary
       # table, and the WD1 clamp flag so the helpers stay within the parameter-list budget. `def_node` is
@@ -1629,7 +1733,7 @@ module Rigor
       RECURSION_VALUE_SIZE_CAP = 64
       private_constant :RECURSION_VALUE_SIZE_CAP
 
-      def infer_user_method_return(def_node, receiver, arg_types) # rubocop:disable Metrics/AbcSize
+      def infer_user_method_return(def_node, receiver, arg_types)
         return nil if def_node.body.nil?
 
         body_scope = build_user_method_body_scope(def_node, receiver, arg_types)
@@ -1646,6 +1750,9 @@ module Rigor
         stack = (Thread.current[INFERENCE_GUARD_KEY] ||= [])
         summaries = (Thread.current[INFERENCE_SUMMARY_KEY] ||= {})
 
+        # WD0 (RIGOR_BUDGET_TRACE) — one entry into user-method return inference. No-op when disabled.
+        BudgetTrace.hit(BudgetTrace::MEMO_ENTRIES)
+
         # ADR-57 follow-up — return memo. The inferred return is a pure function of `(def_node, receiver,
         # arg_types)` and the frozen discovery index whenever the computation does NOT depend on a transient
         # ADR-55 Kleene assumption (an in-flight fixpoint summary). Two structural preconditions decide
@@ -1661,25 +1768,104 @@ module Rigor
         # call, re-walking the shared sub-readers combinatorially (~932k body evaluations for ~20 tiny
         # methods). The computation itself lives in `compute_user_method_return`.
         unless memo_candidate?(stack, plain_signature)
+          trace_memo_refusal(stack, plain_signature)
           return compute_user_method_return(def_node, body_scope, stack, summaries,
                                             receiver, arg_types, plain_signature)
         end
 
-        memo = return_memo_bucket
-        memo_key = [def_node.object_id, receiver.describe(:short),
+        # INVARIANT (ADR-46 recording soundness, ADR-84 WD2) — the deep cross-file dependency edges (the
+        # reads a callee body's dispatches perform through the instrumented `Scope` accessors) are recorded,
+        # per consumer, only as a side effect of evaluating that body, and a memo hit serves the return
+        # WITHOUT re-evaluating it. Since the bucket is run-scoped, hits CROSS consumer-file boundaries, so
+        # every cross-file hit is PAIRED WITH CACHE-AND-REPLAY of the callee's read-set: under recording,
+        # the first evaluation of a key captures the recorder events of its body walk
+        # (`DependencyRecorder.capture` — observe-and-forward, so the first consumer's own record is
+        # untouched) onto the entry, and a hit replays that set into the current consumer's accumulator
+        # (`DependencyRecorder.replay`, which re-applies the per-consumer self-read filter). A memo hit is
+        # thereby edge-equivalent to a fresh body evaluation for EVERY consumer. The naive alternative —
+        # bypassing the memo while the recorder is active — measured >200x wall on analyzer-shaped files
+        # (ActiveStorage video_analyzer.rb's subtree, 0.43s -> >90s; PR #79) and stays rejected. Pinned by
+        # spec/rigor/inference/return_memo_recording_spec.rb (cross-file replay completeness) and
+        # dependency_recorder_spec.rb's transitive deep-edge example.
+        consult_and_store_return_memo(def_node, body_scope, stack, summaries,
+                                      receiver, arg_types, plain_signature)
+      end
+
+      # The candidate-frame memo path: consult the current run generation's bucket, and on a miss compute
+      # and store a FINAL result. Reached only when `memo_candidate?` held (see `infer_user_method_return`).
+      # The store gate (ADR-84 WD3): a result is stored when the ADR-55 fixpoint consult counter did not
+      # move across the compute (the WD0 `MEMO_REFUSE_CONSULT_TAINTED` non-store) AND no transient-machinery
+      # event during the bracket referenced a stack frame BELOW the bracket's entry depth (see
+      # TRANSIENT_EVENT_DEPTHS_KEY). Below-entry events — an ancestor's in-flight Kleene iterate read by a
+      # guard hit, a shared-fuel exhaustion, a possibly-ancestor-caused WD1 clamp — mean the ancestor
+      # context influenced `result`, which a standalone recompute would not reproduce; at-or-above-entry
+      # events are the compute's own deterministic machinery (its own converged fixpoint, sub-cycles that
+      # opened and closed inside the bracket) and do not block the store. A top-of-stack compute (entry
+      # depth 0) is standalone by construction. A hit under ADR-46 recording replays the entry's captured
+      # read-set into the current consumer (see the INVARIANT comment at the call site).
+      def consult_and_store_return_memo(def_node, body_scope, stack, summaries,
+                                        receiver, arg_types, plain_signature)
+        per_def = (return_memo_bucket[def_node] ||= {})
+        memo_key = [receiver.describe(:short),
                     arg_types.map { |type| type.describe(:short) }]
-        return memo[memo_key] if memo.key?(memo_key)
+        if (entry = per_def[memo_key])
+          BudgetTrace.hit(BudgetTrace::MEMO_HITS)
+          Analysis::DependencyRecorder.replay(entry.read_set) if Analysis::DependencyRecorder.active?
+          return entry.result
+        end
+        BudgetTrace.hit(BudgetTrace::MEMO_MISSES)
+        trace_distinct_memo_key(plain_signature, def_node, memo_key)
+
+        entry_depth = stack.size
+        event_mark = transient_event_mark
+        consults_before = summary_consult_count
+        result, read_set = compute_with_read_capture(def_node, body_scope, stack, summaries,
+                                                     receiver, arg_types, plain_signature)
+
+        if summary_consult_count != consults_before
+          BudgetTrace.hit(BudgetTrace::MEMO_REFUSE_CONSULT_TAINTED)
+        elsif context_tainted?(event_mark, entry_depth)
+          BudgetTrace.hit(BudgetTrace::MEMO_REFUSE_TRANSIENT)
+        else
+          per_def[memo_key] = MemoEntry.new(result: result, read_set: read_set,
+                                            receiver: receiver, arg_types: arg_types)
+        end
+        result
+      end
 
-        consults_before = Thread.current[SUMMARY_CONSULT_COUNTER_KEY] || 0
-        result = compute_user_method_return(def_node, body_scope, stack, summaries,
-                                            receiver, arg_types, plain_signature)
-        consults_after = Thread.current[SUMMARY_CONSULT_COUNTER_KEY] || 0
+      def transient_event_mark
+        Thread.current[TRANSIENT_EVENT_DEPTHS_KEY]&.size || 0
+      end
 
-        # Store only a FINAL result. If a fixpoint summary was consulted during the computation, `result`
-        # embeds a transient Kleene iterate whose value depends on the iteration in flight, so it must not
-        # be shared across call sites.
-        memo[memo_key] = result if consults_after == consults_before
-        result
+      def summary_consult_count
+        Thread.current[SUMMARY_CONSULT_COUNTER_KEY] || 0
+      end
+
+      # ADR-84 WD3 — true when a transient-machinery event logged during the bracket (entries past
+      # `event_mark`) referenced a frame below `entry_depth`. The log is cleared when the guard stack drains
+      # (only possible mid-bracket for a top-of-stack compute, whose events are deterministic anyway), so a
+      # missing / shorter log reads as untainted.
+      def context_tainted?(event_mark, entry_depth)
+        log = Thread.current[TRANSIENT_EVENT_DEPTHS_KEY]
+        return false if log.nil? || log.size <= event_mark
+
+        log[event_mark..].any? { |depth| depth < entry_depth }
+      end
+
+      # ADR-84 WD2 — the memo-miss compute, wrapped in a `DependencyRecorder.capture` window when ADR-46
+      # recording is active so the entry can carry its replayable read-set. Returns `[result, read_set]`
+      # (`read_set` nil when not recording).
+      def compute_with_read_capture(def_node, body_scope, stack, summaries,
+                                    receiver, arg_types, plain_signature)
+        unless Analysis::DependencyRecorder.active?
+          return [compute_user_method_return(def_node, body_scope, stack, summaries,
+                                             receiver, arg_types, plain_signature), nil]
+        end
+
+        Analysis::DependencyRecorder.capture do
+          compute_user_method_return(def_node, body_scope, stack, summaries,
+                                     receiver, arg_types, plain_signature)
+        end
       end
 
       # The ADR-55 recursion-guard + value-unroll + fixpoint body of user-method return inference, factored
@@ -1687,6 +1873,7 @@ module Rigor
       # unchanged from pre-memo behaviour).
       def compute_user_method_return(def_node, body_scope, stack, summaries,
                                      receiver, arg_types, plain_signature)
+        trace_body_eval(plain_signature)
         # ADR-55 slice 1: when every bound argument is value-pinned, extend the guard key with a stable
         # descriptor of the argument *values* so distinct constant frames may recurse (e.g. `factorial(5)`
         # folds to `Constant[120]`). Distinct constant frames are bounded by `RECURSION_UNROLL_FUEL` per
@@ -1698,7 +1885,10 @@ module Rigor
         signature = [plain_signature, value_key] if extended
 
         if stack.include?(signature)
-          BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+          # ADR-84 WD3 — the referenced frame is the consulted owner: the OUTERMOST frame carrying this
+          # plain signature (the seeder whose in-flight iterate the re-entry returns).
+          note_transient_fallback(BudgetTrace::RECURSION_GUARD,
+                                  stack.index { |frame| plain_part(frame) == plain_signature } || 0)
           # ADR-55 slice 2: in-cycle re-entries return the current assumed summary (Kleene iterate, seeded
           # `bot`) instead of bare `untyped`. The fixpoint loop below seeds the entry on the outermost frame;
           # if a re-entry beats it here the entry already exists. The WD4 composition: slice 1's clamp/fuel
@@ -1724,30 +1914,85 @@ module Rigor
         evaluate_guarded_user_method_body(def_node, body_scope, stack, signature, context)
       end
 
-      # True when this frame's result is a candidate for the return memo: the structural preconditions, both
-      # stable across the body walk, that are necessary (but not sufficient) for a FINAL result. Sufficiency
-      # is decided post-hoc in `infer_user_method_return` by the consult-counter check (no transient
-      # fixpoint summary was read during the compute) — so unlike the prior `memoisable_return?` this
-      # deliberately does NOT require an empty `summaries` table: inert seeded-but-unconsulted entries left
-      # by unrelated outermost frames do not contaminate a result, and gating on them disabled the memo for
-      # an entire non-recursive DAG (the scaling wall). The two preconditions: no constant-arg unroll in
-      # flight (its value-keyed frames are transient) and this plain signature not itself on the recursion
-      # guard stack (else we are inside its own cycle, returning a Kleene iterate).
+      # True when this frame's result is a candidate for the return memo: the one structural precondition,
+      # stable across the body walk, that is necessary (but not sufficient) for a FINAL result — this plain
+      # signature must not itself be on the recursion guard stack (else we are inside its own cycle,
+      # returning a Kleene iterate by construction). Sufficiency is decided post-hoc in
+      # `consult_and_store_return_memo` by the two bracket counters (fixpoint consults + ADR-84 WD3
+      # transient-machinery events) — so unlike the prior form this deliberately does NOT refuse while a
+      # constant-arg unroll is in flight: a nested frame whose compute finishes without a single transient
+      # event ran exactly as it would standalone (fuel consumption without exhaustion is invisible), and
+      # the blanket exclusion refused 82% of mail's body evaluations for such final results (ADR-84).
       def memo_candidate?(stack, plain_signature)
-        # Read the unroll fuel WITHOUT the decrement side effect of `unroll_fuel_remaining`: a constant-arg
-        # unroll has begun iff the thread-local is set and the stack is non-empty (the `ensure` in
-        # `evaluate_guarded_user_method_body` clears it at stack-empty).
-        unroll_idle = stack.empty? || Thread.current[INFERENCE_UNROLL_FUEL_KEY].nil?
-        unroll_idle &&
-          stack.none? { |frame| plain_part(frame) == plain_signature }
+        stack.none? { |frame| plain_part(frame) == plain_signature }
       end
 
-      # Run-scoped return-memo bucket for the current discovery generation. Keyed by the identity of the
-      # frozen `def_nodes` table so a new analysis generation (or any scope that swaps the index)
-      # transparently lands in a fresh bucket. See RETURN_MEMO_KEY.
+      # Run-scoped return-memo bucket (ADR-84 WD2): a single retained slot keyed by the identity of the
+      # run-generation token the runner seeds (`Scope#run_generation`), falling back to the per-file merged
+      # `def_nodes` table identity for runner-less scopes (single-file probes) — the pre-WD2 per-file
+      # scope. A generation mismatch drops the previous bucket whole, so a re-run in one process (LSP,
+      # ADR-62 warm loop) can neither hit stale entries nor accumulate them. The bucket maps `def_node`
+      # (object identity, held strongly — see RETURN_MEMO_KEY) to its per-descriptor entries.
       def return_memo_bucket
-        store = (Thread.current[RETURN_MEMO_KEY] ||= {}.compare_by_identity)
-        store[scope.discovered_def_nodes] ||= {}
+        generation = scope.run_generation || scope.discovered_def_nodes
+        slot = Thread.current[RETURN_MEMO_KEY]
+        unless slot && slot[0].equal?(generation)
+          slot = [generation, {}.compare_by_identity]
+          Thread.current[RETURN_MEMO_KEY] = slot
+        end
+        slot[1]
+      end
+
+      # WD0 (RIGOR_BUDGET_TRACE) trace helpers. Each guards on `BudgetTrace.enabled?` before doing any work
+      # beyond a single boolean check, so a normal run pays nothing (no signature-label string built, no
+      # stack scan). Attributes a non-candidate frame's non-store to on-stack vs unroll-in-flight; since
+      # ADR-84 WD3 reduced candidacy to the on-stack check alone, the unroll-in-flight branch is
+      # structurally unreachable and is kept only so the printed counter table still shows the category
+      # (pinned ~0 — the ADR-84 WD3 gate).
+      def trace_memo_refusal(stack, plain_signature)
+        return unless BudgetTrace.enabled?
+
+        if stack.any? { |frame| plain_part(frame) == plain_signature }
+          BudgetTrace.hit(BudgetTrace::MEMO_REFUSE_ON_STACK)
+        else
+          BudgetTrace.hit(BudgetTrace::MEMO_REFUSE_UNROLL)
+        end
+      end
+
+      # The observed member is the full `(def-node identity, receiver, args)` entry key, so the per-signature
+      # count also surfaces the ADR-84 WD2 dual-parse duplication (project-index parse vs the defining
+      # file's own parse — at most 2 node identities per def per run).
+      def trace_distinct_memo_key(plain_signature, def_node, memo_key)
+        return unless BudgetTrace.enabled?
+
+        BudgetTrace.observe_distinct(
+          BudgetTrace::MEMO_DISTINCT_KEY_BY_SIGNATURE, signature_label(plain_signature),
+          [def_node.object_id, memo_key]
+        )
+      end
+
+      def trace_body_eval(plain_signature)
+        return unless BudgetTrace.enabled?
+
+        BudgetTrace.hit(BudgetTrace::MEMO_BODY_EVALS)
+        BudgetTrace.observe(BudgetTrace::MEMO_BODY_EVAL_BY_SIGNATURE, signature_label(plain_signature))
+      end
+
+      # `"Receiver#method"` label for a `[receiver_descriptor, method_name]` plain signature — the bucket key
+      # for the WD0 per-signature distributions. Built only under `BudgetTrace.enabled?`.
+      def signature_label(plain_signature)
+        "#{plain_signature[0]}##{plain_signature[1]}"
+      end
+
+      # ADR-84 WD3 — the single choke point every transient-machinery fallback routes through: appends the
+      # referenced frame's stack position to the load-bearing thread-local event log (regardless of
+      # RIGOR_BUDGET_TRACE) and forwards the category to `BudgetTrace`. The taint spec pins that no
+      # recursion-machinery `BudgetTrace.hit` exists outside this helper, so a future fallback cannot
+      # silently join unlogged (see the audit table at TRANSIENT_EVENT_DEPTHS_KEY; `context_depth` 0 is
+      # always a sound conservative choice).
+      def note_transient_fallback(category, context_depth)
+        (Thread.current[TRANSIENT_EVENT_DEPTHS_KEY] ||= []) << context_depth
+        BudgetTrace.hit(category)
       end
 
       # Pushes the recursion-guard frame, evaluates the body (the outermost frame for a plain signature runs
@@ -1772,6 +2017,7 @@ module Rigor
             Thread.current[INFERENCE_UNROLL_FUEL_KEY] = nil
             Thread.current[INFERENCE_SUMMARY_KEY] = nil
             Thread.current[SUMMARY_CONSULT_DEPTHS_KEY] = nil
+            Thread.current[TRANSIENT_EVENT_DEPTHS_KEY] = nil
           end
         end
       end
@@ -1861,12 +2107,21 @@ module Rigor
       # soundness fix, 2026-06-12), parking `untyped` in the assumption so any consumer that still reads
       # this signature's summary sees the floor, not the stale `bot` seed.
       def degrade_entangled_fixpoint(summaries, plain_signature)
-        BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        # ADR-84 WD3 — logged at the degrading owner's own position: the foreign consult that caused the
+        # entanglement was already logged at the ANCESTOR's position by the guard site.
+        note_transient_fallback(BudgetTrace::RECURSION_GUARD, own_guard_frame_position)
         scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
         summaries[plain_signature][:assumption] = Type::Combinator.untyped
         Type::Combinator.untyped
       end
 
+      # The stack position of the currently-evaluating owner frame (the guard stack's top) — the
+      # self-referential `context_depth` for events that are deterministic per owner (ADR-84 WD3).
+      def own_guard_frame_position
+        size = Thread.current[INFERENCE_GUARD_KEY]&.size || 0
+        size.positive? ? size - 1 : 0
+      end
+
       # One Kleene-iteration step of the fixpoint loop. Joins `computed` into the running assumption
       # (widening value-pinned constituents on the final permitted iteration to force convergence) and
       # either returns a final type — convergence, or the capped `untyped` collapse — or `:continue` to
@@ -1882,9 +2137,9 @@ module Rigor
         return candidate if joined == assumption
 
         if last_iteration
-          # Out of iterations and still unstable — collapse to today's
-          # widening behaviour.
-          BudgetTrace.hit(BudgetTrace::RECURSION_FIXPOINT_CAP)
+          # Out of iterations and still unstable — collapse to today's widening behaviour. ADR-84 WD3: the
+          # cap is a per-owner constant, so the event references the owner's own frame.
+          note_transient_fallback(BudgetTrace::RECURSION_FIXPOINT_CAP, own_guard_frame_position)
           scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
           summaries[plain_signature][:assumption] = Type::Combinator.untyped
           return Type::Combinator.untyped
@@ -1944,7 +2199,14 @@ module Rigor
         return false if RETURN_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
         return true if node.is_a?(Prism::ReturnNode)
 
-        node.compact_child_nodes.any? { |child| body_has_explicit_return?(child) }
+        found = false
+        node.rigor_each_child do |child|
+          next unless body_has_explicit_return?(child)
+
+          found = true
+          break
+        end
+        found
       end
 
       # Returns the current assumed summary for `plain_signature`, recording that it was consulted (so the
@@ -1967,7 +2229,9 @@ module Rigor
       def clamp_unroll_result(type, would_have_been_guarded)
         return type unless would_have_been_guarded && !fully_value_pinned?(type)
 
-        BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        # ADR-84 WD3 — position 0 (conservative): the would-have-been-guarded match may be an ancestor
+        # frame, and the matched position is not threaded through RecursionContext.
+        note_transient_fallback(BudgetTrace::RECURSION_GUARD, 0)
         scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
         # ADR-55 WD1 clamp: a guarded extended frame whose body is non-pinned must be byte-identical to the
         # plain guard's `untyped`. This path deliberately does NOT route to the in-progress fixpoint summary:
@@ -1998,7 +2262,9 @@ module Rigor
         if remaining.positive?
           Thread.current[INFERENCE_UNROLL_FUEL_KEY] = remaining - 1
         else
-          BudgetTrace.hit(BudgetTrace::RECURSION_UNROLL_FUEL)
+          # ADR-84 WD3 — position 0: fuel is one shared resource seeded at the stack bottom, so its
+          # exhaustion is context-dependent for every nested bracket.
+          note_transient_fallback(BudgetTrace::RECURSION_UNROLL_FUEL, 0)
         end
         remaining
       end