rigortype 0.3.5 → 0.3.7

data/lib/rigor/inference/content_join.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # The element / key / value **content join** shared by every path that observes a collection
+    # being content-mutated in place.
+    #
+    # {MutationWidening} forgets what a mutation falsified — a literal's arity, and (for a
+    # slot-rewriting mutator) its value pinning. That half only ever subtracts. This module is the
+    # other half: it adds back what the mutation is known to have PUT in the collection, so the
+    # continuation carrier covers the mutated contents instead of only the seed's.
+    #
+    # Two callers share it, and they must agree:
+    #
+    # - the **block-capture** path (ADR-56 slice C) — `out = [0]; xs.each { |x| out << x }` types
+    #   `out` as `Array[0 | Integer]`, not `Array[0]`;
+    # - the **straight-line** path (issue #560) — `u = [1, 2]; u.push(6)` types `u` as
+    #   `Array[1 | 2 | Integer]`, not `Array[1 | 2]`. Before the join, `u.last` read back `1 | 2`,
+    #   the constant-comparison fold turned `u.last == 6` into `Constant[false]`, and a correct
+    #   program drew a false `flow.always-truthy-condition`. `mail`'s ragel tables are the same root
+    #   seen from the precision side: `stack = []; stack[top] = cs` widened to `Array[untyped]`
+    #   where the join reads `Array[Integer]` (issue #533 item 8).
+    module ContentJoin
+      # Array content-mutators that append/store ELEMENTS. The appended element type is the call's
+      # argument type(s); `[]=`'s value is its LAST argument (the keys precede it). Subset of
+      # {MutationWidening::ARRAY_MUTATORS}: only the element-INTRODUCING methods (removers /
+      # reorderers add no new element evidence and are already covered by the arity-forget).
+      ARRAY_CONTENT_ADDERS = %i[
+        << push append prepend unshift concat insert []= fill replace
+      ].to_set.freeze
+
+      # Hash content-mutators that store a key→value pair. For `[]=` / `store` the key is the first
+      # argument and the value the last.
+      HASH_CONTENT_ADDERS = %i[[]= store].to_set.freeze
+
+      # String content-mutators that append to the buffer. String carries no element parameter, so
+      # these contribute nothing to a join — they are listed so the orchestrator recognises them as
+      # content mutators (the binding already widens to `String` via normal typing); the join
+      # helpers below short-circuit on a non-collection pre-state.
+      STRING_CONTENT_ADDERS = %i[<< concat prepend insert replace].to_set.freeze
+
+      # Every method name that mutates a collection's CONTENT — the union the orchestrators scan a
+      # block body for, and the gate the straight-line path types its arguments behind.
+      CONTENT_ADDERS = (ARRAY_CONTENT_ADDERS | HASH_CONTENT_ADDERS | STRING_CONTENT_ADDERS).freeze
+
+      module_function
+
+      # The element types a single content-mutator call introduces into an Array, given the
+      # per-argument types (already typed by the caller in the scope the arguments are evaluated
+      # in). `concat`/`replace` take collection arguments, so their element evidence is the
+      # arguments' OWN element types unioned; the rest append the argument values directly. Returns
+      # `[]` when there is no element evidence (e.g. a `<<` with no resolvable arg).
+      def array_added_elements(method_name, arg_types)
+        return [] if arg_types.empty?
+
+        case method_name
+        when :concat, :replace
+          arg_types.flat_map { |t| collection_element_types(t) }
+        when :insert
+          # `insert(index, *objs)` — first arg is the position.
+          arg_types.drop(1)
+        when :[]=
+          # `arr[i] = v` / `arr[i, n] = v` — value is the last argument.
+          #
+          # The SPLICE forms (`arr[i, n] = other` / `arr[range] = other`) store `other`'s ELEMENTS,
+          # not `other` itself, so reading the value as one element over-widens: `a[0, 2] = [1, 2]`
+          # contributes `Array[Integer]` where `Integer` is the truth. Left alone deliberately —
+          # the answer is a superset either way, so it can only cost precision, and splitting the
+          # arities here would need the receiver's own element type to unwrap against. Revisit if a
+          # corpus site ever reads an element back through a splice-built array.
+          [arg_types.last]
+        when :fill
+          # `fill(value)` — only the no-block single-value form adds a concrete element; block /
+          # range forms are conservatively ignored (the arity-forget already widened the binding).
+          arg_types.size == 1 ? arg_types : []
+        else # << push append prepend unshift
+          arg_types
+        end
+      end
+
+      # Builds the continuation Array type from the pre-state binding and the appended element
+      # types. The floor is `Array[Dynamic[top]]` (the sound empty-seed behaviour) when there is no
+      # element evidence at all.
+      #
+      # **Every arm the seed carries survives, a `Dynamic` arm included.** A gradual seed element is
+      # a statement about what the collection ALREADY holds — a parameter declared `Array[untyped]`,
+      # a local seeded from a call whose signature returns the same, a literal `[x]` whose slot the
+      # engine could not type — and the stores a body adds are evidence about what the body put in,
+      # never about what was there first. Dropping the
+      # arm once concrete evidence appeared closed a declared `Array[untyped]` parameter to
+      # `Array[Integer]` under `[1, 2].each { a.push(rand(9)) }` and drew `undefined method 'upcase'`
+      # on `a.first.upcase`, which the declaration licenses (issue #586).
+      #
+      # What this method therefore never sees is the arity-forget's OWN floor: `widen_tuple` spells
+      # an empty `[]` as `Array[untyped]`, and read back through here that `untyped` would be
+      # indistinguishable from a declared one. Each caller keeps that floor out at its source by
+      # reading the seed from before the widening ran — the block seam from the pre-widen scope, the
+      # loop seam from the pre-body scope — so an empty literal contributes no element and `out = [];
+      # xs.each { out << x*2 }` still reads `Array[Integer]`. The straight-line seam passes the
+      # widened carrier, and adds the same `Dynamic` as its one-store floor anyway.
+      #
+      # **The rederived carrier replaces only the members it stands for** — see {#array_residue}.
+      def join_array_content(pre_state, added_elements)
+        elements = collection_element_types(pre_state) + added_elements.compact
+        element_t = elements.empty? ? Type::Combinator.untyped : Type::Combinator.union(*elements)
+        with_residue(Type::Combinator.nominal_of("Array", type_args: [element_t]), array_residue(pre_state))
+      end
+
+      # Builds the continuation Hash type from the pre-state binding and a list of `[key_type,
+      # value_type]` pairs stored by `[]=` / `store`. The seed's key and value arms survive on the
+      # same terms as {#join_array_content}'s elements: a declared `Hash[untyped, untyped]` stays
+      # gradual on both sides however many pairs the body stores, and a pre-state member that is not
+      # a Hash carrier at all survives whole ({#hash_residue}).
+      def join_hash_content(pre_state, added_pairs)
+        seed_keys, seed_values = hash_shape_key_values(pre_state)
+        keys = seed_keys + added_pairs.map(&:first).compact
+        values = seed_values + added_pairs.map(&:last).compact
+        key_t = keys.empty? ? Type::Combinator.untyped : Type::Combinator.union(*keys)
+        value_t = values.empty? ? Type::Combinator.untyped : Type::Combinator.union(*values)
+        with_residue(Type::Combinator.nominal_of("Hash", type_args: [key_t, value_t]), hash_residue(pre_state))
+      end
+
+      # ----------------------------------------------------------------
+      # Union residue — the members the rederived carrier does NOT stand for (issue #631).
+      #
+      # A join REPLACES the binding with one freshly built `Nominal`, and that is the right answer
+      # only for the pre-state members the mutation actually applied to as a collection of that
+      # class. A `Union` seed can carry members that are not collection carriers at all, and those
+      # contribute no element / key / value evidence — `collection_element_types` and
+      # `hash_shape_key_values` both answer "nothing" for them. Before this rule they were simply
+      # gone:
+      #
+      #     out = flag ? u : [2]     # Dynamic[top] | [2]
+      #     [1].each { out << 2 }    # -> Array[2]; the whole-variable Dynamic arm dropped
+      #     out.first.upcase         # undefined method `upcase' for 2 -- on correct code
+      #
+      # This is WD2.9's rule ("a seed's own gradual arm survives the rederivation") one level out:
+      # there the surviving `Dynamic` was an ELEMENT of an Array carrier, here it is the whole
+      # variable. Both say the same thing — the body's stores are evidence about what the body put
+      # in, never about what the variable WAS — and the straight-line seam already reads the union
+      # through untouched, so the block and loop seams were the outliers.
+      #
+      # A member survives whole; it is never re-examined for element evidence, so nothing is
+      # double-counted. `Array.new`'s bare `Nominal[Array]` (no type args) IS a carrier and is
+      # absorbed, so #615's seed keeps closing rather than growing a second arm.
+      #
+      # **`nil` is the one member the mutation itself refutes, and it does not survive.** The rule
+      # above is a rule about ABSENCE of evidence — the seam cannot say a `Dynamic` or a foreign
+      # `Nominal` was mutated as an Array, so it must not rewrite it. `NilClass` defines no content
+      # mutator at all, so on every path where the body ran the binding was not nil; only the
+      # zero-iteration path keeps the arm, and that path is modelled upstream (the `while` base
+      # scope's nil-injection, slice A's `Constant[nil]` fixpoint seed) rather than here. Keeping it
+      # measured out as a pure cost: `r = nil; while …; r ||= []; r << x; end; r.each` gained a
+      # `call.possible-nil-receiver` on an idiom Rubyists write deliberately, while the genuinely
+      # live nil arm is already reported once — at the mutation site, where `r << x` draws the same
+      # diagnostic. This is the only member the join can refute without a method lookup it has no
+      # environment for; the general "the mutator is undefined on this member" rule would buy
+      # rarer shapes for machinery this seam does not have.
+      NON_SURVIVING_CLASSES = %w[NilClass].freeze
+
+      # Pre-state members the rederived Array does not stand for: a whole-variable `Dynamic`, a
+      # non-nil `Constant`, a foreign `Nominal`, a `Refined`. Mirrors {#collection_element_types}'s
+      # recursion so the absorbed set and the residue partition the union exactly. A `Difference` is
+      # absorbed with its base (`non-empty-array[T]` is an Array carrier) and otherwise kept whole,
+      # refinement and all.
+      def array_residue(type)
+        case type
+        when Type::Union then type.members.flat_map { |m| array_residue(m) }
+        when Type::Tuple then []
+        when Type::Nominal then type.class_name == "Array" ? [] : keep_member(type)
+        when Type::Difference then array_residue(type.base).empty? ? [] : [type]
+        else keep_member(type)
+        end
+      end
+
+      # The Hash-side twin of {#array_residue}, mirroring {#hash_shape_key_values}. A bare
+      # `Nominal[Hash]` with no type args is a carrier here even though it yields no key/value
+      # evidence — `Hash.new` must close like `Array.new`, not grow an arm.
+      def hash_residue(type)
+        case type
+        when Type::Union then type.members.flat_map { |m| hash_residue(m) }
+        when Type::HashShape then []
+        when Type::Nominal then type.class_name == "Hash" ? [] : keep_member(type)
+        when Type::Difference then hash_residue(type.base).empty? ? [] : [type]
+        else keep_member(type)
+        end
+      end
+
+      # `[type]`, unless the mutation refutes the member outright — see {NON_SURVIVING_CLASSES}.
+      def keep_member(type)
+        NON_SURVIVING_CLASSES.include?(evidence_class(type)) ? [] : [type]
+      end
+
+      def with_residue(carrier, residue)
+        residue.empty? ? carrier : Type::Combinator.union(*residue, carrier)
+      end
+
+      # ----------------------------------------------------------------
+      # Seed-admissibility — the straight-line join's signature gate (issue #560).
+      #
+      # A join is not free: it grows the carrier's element union, and a carrier that grows a member
+      # the enclosing method's HAND-WRITTEN signature does not admit turns a correct program into a
+      # `def.return-type-mismatch`. haml's temple builders are the corpus shape —
+      #
+      #     def compile_html(node)          # sig: (untyped) -> Array[:multi]
+      #       temple = [:multi]
+      #       temple << [:static, "<style>\n"]
+      #       temple
+      #     end
+      #
+      # — where joining the appended tuple precisely reads `Array[:multi | [:static, String]]` and
+      # draws a mismatch against `Array[:multi]` on eight sites. (PR #561 hit the same wall from the
+      # other direction and had to scope value-pin widening away from adders to avoid it.) A gradual
+      # member does NOT rescue that: `Array[:multi | [:static, String] | untyped]` is still rejected,
+      # because every non-`Dynamic` member is judged on its own. The gate is what keeps the foreign
+      # member out; the caller's gradual floor is a separate concern and neither substitutes for the
+      # other.
+      #
+      # So added evidence is admitted per member, against the class set the SEED already carries:
+      #
+      # - the seed's class set already admits the added member's class — the collection is
+      #   homogeneous in the sense that matters, and the member joins as itself
+      #   (`u = [1, 2]; u.push(6)` contributes `Integer`);
+      # - it does not — the collection is provably heterogeneous, and between the literal seed and
+      #   the author's signature the engine has no ground to adjudicate. It contributes
+      #   `Dynamic[top]` instead of a foreign precise member;
+      # - the seed carries nothing to contradict — an empty literal, or a slot the engine cannot type
+      #   — and every member is admitted as itself.
+      #
+      # The second case only ever replaces a WRONG precise element type with a gradual one, so it is
+      # a soundness improvement paid for in opacity on exactly the sites that were lying.
+      #
+      # What this module does NOT decide is whether the resulting parameter may be CLOSED. That is
+      # the caller's call, and it turns on whether the caller saw every store —
+      # {MutationWidening#join_added_elements} carries the rule and the counter-example.
+
+      # `added`, with every member the seed's class set does not admit replaced by `Dynamic[top]`.
+      #
+      # A seed that carries nothing to contradict admits everything: an empty literal has no class
+      # set, and a `Dynamic` member means the engine could not type that slot, so it cannot rule
+      # anything out either.
+      #
+      # Both sides are flattened through their `Union` members before matching. Judging a union
+      # wholesale would floor `["a", 1]`-shaped evidence against an `Integer` seed even though its
+      # `Integer` half is admissible, and `evidence_class` has no answer for a `Union` at all — so
+      # the wholesale reading is strictly worse and no simpler.
+      def admissible_evidence(seed_members, added)
+        members = seed_members.flat_map { |m| union_members(m) }
+        return added if members.empty? || members.any?(Type::Dynamic)
+
+        classes = members.filter_map { |m| evidence_class(m) }.to_set
+        added.flat_map { |type| admit_members(union_members(type), classes) }
+      end
+
+      # Each member of one added type, kept when its class is admitted and floored when it is not.
+      # A type whose members are all admitted returns them unchanged, so the common single-member
+      # case is `[type]`.
+      def admit_members(members, classes)
+        members.map { |m| classes.include?(evidence_class(m)) ? m : Type::Combinator.untyped }
+      end
+
+      # The class name a type carrier commits its values to, or `nil` when it commits to none. A
+      # `nil` answer is never admitted: an unnameable carrier cannot be shown compatible with the
+      # seed, so it takes the gradual floor.
+      def evidence_class(type)
+        case type
+        when Type::Nominal then type.class_name
+        when Type::Constant then type.value.class.name
+        when Type::Tuple then "Array"
+        when Type::HashShape then "Hash"
+        end
+      end
+
+      def union_members(type)
+        type.is_a?(Type::Union) ? type.members : [type]
+      end
+
+      # Element types carried by a collection binding, regardless of which carrier holds them: a
+      # `Tuple` lists them, a `Nominal[Array, [E]]` has one element param, a bare `Array` /
+      # anything else yields none.
+      #
+      # A `Difference` reads through to its base: `non-empty-array[T]` holds `T`s, and the seams
+      # that read a seed from BEFORE the arity-forget ran (see {#join_array_content}) meet the
+      # refinement carrier itself where they used to meet the base the widening had left. Declining
+      # it there would hand the continuation the widened base ALONE, with every appended arm missing
+      # — a wrong type, not a wide one.
+      def collection_element_types(type)
+        case type
+        when Type::Tuple
+          type.elements
+        when Type::Nominal
+          type.class_name == "Array" ? type.type_args : []
+        when Type::Union
+          # A loop's single-pass join can union the widened collection with its un-widened literal
+          # seed (`Array[0] | [0]`); pull element evidence from every Array-ish member.
+          type.members.flat_map { |m| collection_element_types(m) }
+        when Type::Difference
+          collection_element_types(type.base)
+        else
+          []
+        end
+      end
+
+      # `[keys, values]` evidence from a Hash-ish pre-state binding — a `HashShape` (literal pairs)
+      # or a `Nominal[Hash, [K, V]]`. A `Difference` (`non-empty-hash[K, V]`) reads through to its
+      # base, as {#collection_element_types} does for the Array side.
+      def hash_shape_key_values(type)
+        case type
+        when Type::HashShape
+          return [[], []] if type.pairs.empty?
+
+          [[key_union_for(type.pairs.keys)], type.pairs.values]
+        when Type::Nominal
+          type.class_name == "Hash" && type.type_args.size == 2 ? [[type.type_args[0]], [type.type_args[1]]] : [[], []]
+        when Type::Union
+          type.members.each_with_object([[], []]) do |m, (ks, vs)|
+            mk, mv = hash_shape_key_values(m)
+            ks.concat(mk)
+            vs.concat(mv)
+          end
+        when Type::Difference
+          hash_shape_key_values(type.base)
+        else
+          [[], []]
+        end
+      end
+
+      # Maps a literal Ruby key set to a union of the corresponding type carriers. Symbol / String /
+      # Integer / Float keys widen to their class nominal; the `true` / `false` / `nil` singleton
+      # keys keep their constant carrier (the constant IS the class's whole value set, and `nil`
+      # reads better than `NilClass` in a widened `Hash[K, V]`). We deliberately do NOT fold the
+      # widenable kinds to a `Constant<:k1> | Constant<:k2>` union — that would be a precision
+      # improvement that complicates the widening contract; the goal there is to LOSE precision, not
+      # to record a new fact set.
+      def key_union_for(keys)
+        carriers = keys.map do |key|
+          next Type::Combinator.constant_of(key) if [true, false, nil].include?(key)
+
+          Type::Combinator.nominal_of(key.class.name)
+        end.uniq
+        carriers.size == 1 ? carriers.first : Type::Combinator.union(*carriers)
+      end
+    end
+  end
+end

data/lib/rigor/inference/def_handle.rb

@@ -6,7 +6,7 @@ module Rigor
     # 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:
+    # the four things needed to resolve, fingerprint, or scope 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
@@ -16,8 +16,20 @@ module Rigor
     # - `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.
+    # - `nesting` — the `Module.nesting` in force where the def is WRITTEN (issue #681's chain), `[]` for a
+    #   top-level def (issue #716: that is Ruby's answer, not the absence of one), and nil only when no
+    #   declaration walk recorded any. The cross-file `def_nestings` table is keyed by node IDENTITY, and
+    #   {DefNodeResolver} hands back a node from its OWN parse, so no identity-keyed table built by the
+    #   discovery walk can ever contain it. Travelling on the handle is what lets the resolver re-attach the
+    #   chain to the node it mints, instead of the re-walk falling back to peeling the receiver's qualified
+    #   name — which cannot tell a compact `class Admin::Maker` from the nested spelling, so an unchanged
+    #   file's callee answered a different constant on the warm path than on a cold run ([#707]).
     #
-    # Marshal-clean by construction (Integer + Strings), so it rides the `IncrementalSnapshot` blob directly.
-    DefHandle = Data.define(:path, :node_id, :name, :fingerprint)
+    # A required member rather than a defaulted one: a writer that has a chain and forgets to pass it
+    # reintroduces exactly the divergence above, silently, so the constructor is where that must fail loudly.
+    #
+    # Marshal-clean by construction (Integer + Strings + a String array), so it rides the
+    # `IncrementalSnapshot` blob directly.
+    DefHandle = Data.define(:path, :node_id, :name, :fingerprint, :nesting)
   end
 end

data/lib/rigor/inference/def_node_resolver.rb

@@ -28,15 +28,24 @@ module Rigor
       private_constant :MEMO_KEY
 
       # Installs a fresh per-run resolution memo, restoring the previous one on exit (always, even on a raise).
-      # `nodes` caches the resolved node per `(path, node_id)`; `indexes` caches each file's parse index.
+      # `nodes` caches the resolved node per `(path, node_id)`; `indexes` caches each file's parse index;
+      # `nestings` re-attaches each handle's recorded `Module.nesting` to the node this module minted for it
+      # ({.rehydrated_nesting}).
       def self.with_run
         previous = Thread.current[MEMO_KEY]
-        Thread.current[MEMO_KEY] = { nodes: {}, indexes: {} }
+        Thread.current[MEMO_KEY] = { nodes: {}, indexes: {}, nestings: {}.compare_by_identity }
         yield
       ensure
         Thread.current[MEMO_KEY] = previous
       end
 
+      # Whether a per-run memo scope is in force. The rehydrated `Module.nesting` ({.rehydrated_nesting}) is
+      # recorded only inside one, so this names the precondition the internal spec's "within the resolver's
+      # per-run memo scope" clause states — and lets a spec assert that no handle-consuming entry point
+      # resolves outside it, which is the difference between the peel fallback being a documented edge and
+      # being silently reachable from production.
+      def self.run_scope? = !Thread.current[MEMO_KEY].nil?
+
       # Resolves `handle` to a `Prism::DefNode` (the same object across the run for a given (path, node_id)), or
       # nil. A non-handle argument is returned unchanged, so callers can pass a table value that is either a live
       # node (cold / re-walked file) or a handle (unchanged file) without branching.
@@ -50,8 +59,58 @@ module Rigor
         nodes = memo[:nodes]
         return nodes[key] if nodes.key?(key)
 
-        nodes[key] = locate(handle, memo[:indexes])
+        node = nodes[key] = locate(handle, memo[:indexes])
+        record_nesting(memo, node, handle.nesting)
+        node
+      end
+
+      # Issue #707 — the recorded `Module.nesting` for a node this module minted from a {DefHandle}, or nil.
+      #
+      # This is a REHYDRATION of `Scope::DiscoveryIndex#discovered_def_nestings`, not a rival source for the
+      # same question, and the single reader ({Inference::ExpressionTyper#recorded_def_nesting}) may consult
+      # the table first and fall through here without shadowing a live answer. Two independent facts license
+      # that order, and the tempting third one is FALSE:
+      #
+      # 1. OBJECT PROVENANCE — no node can be a key in both. {.build_file_index} runs its OWN `Prism.parse`,
+      #    and both tables are `compare_by_identity`, so a node this module mints is never the object any
+      #    walk over the analyzer's own parse produced. This holds per NODE and needs nothing about files.
+      # 2. AGREEMENT — where both tables answer for the same DEF (through different objects), they answer the
+      #    same chain. A bundle is only reused when the file's content SHA-256 matches
+      #    ({Cache::FileDigest.hexdigest}, the digest tier, not the stat one), and `build_def_nestings` is a
+      #    pure function of that file's AST, so identical bytes yield an identical chain.
+      #
+      # What is NOT true — and was asserted here before it was measured — is that a file takes exactly ONE of
+      # the two branches per run. It does so in the cross-file pre-pass only. An UNCHANGED file re-analysed as
+      # a dependent is served from its bundle there AND walked live by `ScopeIndexer#merge_def_node_tables`
+      # for its own per-file index, contributing keys to both tables in one `Runner#run`. Fact 1 is what makes
+      # that harmless, so a future change must preserve the separate parse, not the file-level split.
+      #
+      # `--verify-incremental` is the standing detector for the whole property: it compares the warm and cold
+      # diagnostics project-wide, so a disagreement surfaces as a reported incremental-only / full-only
+      # diagnostic rather than as a silently preferred answer.
+      #
+      # Outside a run scope ({.with_run} never entered) nothing is recorded and the reader keeps
+      # `Reflection.lexical_nesting_chain`'s peel fallback — the same gradual answer that path already gives.
+      # Every entry point that CONSUMES a handle runs inside `with_run`; `spec/rigor/inference/
+      # def_node_resolver_spec.rb` pins that, so a new one added outside a run scope fails there rather than
+      # silently reverting to the peel.
+      def self.rehydrated_nesting(node)
+        memo = Thread.current[MEMO_KEY]
+        memo && memo[:nestings][node]
+      end
+
+      # Files the chain the bundle recorded against the node just minted for it. Issue #716 — an EMPTY chain
+      # is recorded like any other: it is the bundle saying the def is written at the top level, and dropping
+      # it would leave the warm path peeling the caller's namespace where a cold run resolves at the top
+      # level. Only `nil` — a bundle that recorded nothing for the def — is skipped, and
+      # `Cache::IncrementalSnapshot::SCHEMA` 17 is what keeps a pre-#716 blob (where `nil` MEANT top level)
+      # from being read as one.
+      def self.record_nesting(memo, node, nesting)
+        return if node.nil? || nesting.nil?
+
+        memo[:nestings][node] = nesting
       end
+      private_class_method :record_nesting
 
       # Finds the node for `handle` using a per-file `{node_id => DefNode}` + `{name => DefNode}` index cache.
       def self.locate(handle, index_cache)