rigortype 0.4.6 → 0.4.8

data/lib/rigor/reflection/constant_ancestors.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../typing_state"
+require_relative "../memo_audit"
+
 module Rigor
   # {Reflection}'s constant-ancestor walk ([#354](https://github.com/rigortype/rigor/issues/354)), split out for
   # the reader rather than for the loader: the whole-spelling ladder's step 2 (`reflection.rb`) and the
@@ -7,13 +10,23 @@ module Rigor
   # name's owner inherits constants from, and this file answers that once for both. Reopening the module
   # keeps the walk behind the facade its callers already read.
   module Reflection
-    # #354 — thread-local slot for the per-run ancestor-scope memo. See {.ancestor_constant_scopes}.
-    ANCESTOR_SCOPES_KEY = :__rigor_ancestor_constant_scopes__
-    private_constant :ANCESTOR_SCOPES_KEY
-
-    # The recording run's slot. See {.recorded_ancestor_constant_scopes}.
-    RECORDED_ANCESTOR_SCOPES_KEY = :__rigor_recorded_ancestor_constant_scopes__
-    private_constant :RECORDED_ANCESTOR_SCOPES_KEY
+    # #354 — the per-run ancestor-scope memo. See {.ancestor_constant_scopes}. ADR-129 WD1 — a run-scoped Memo.
+    ANCESTOR_SCOPES = TypingState.memo(
+      :ancestor_constant_scopes,
+      run_scoped: true, audit: "ancestor constant scopes",
+      reason: "one [discovery, scopes by class name] slot keyed on the discovery index's identity, as the " \
+              "resolution chain the scopes are read from is (#2848)"
+    )
+    private_constant :ANCESTOR_SCOPES
+
+    # The recording run's slot. See {.recorded_ancestor_constant_scopes}. ADR-129 WD1 — a run-scoped Memo.
+    RECORDED_ANCESTOR_SCOPES = TypingState.memo(
+      :recorded_ancestor_constant_scopes,
+      run_scoped: true, audit: "recorded ancestor constant scopes",
+      reason: "one [discovery, scopes by class name] slot keyed on the discovery index's identity; a hit replays " \
+              "the chain's edges, so the key is exact"
+    )
+    private_constant :RECORDED_ANCESTOR_SCOPES
 
     module_function
 
@@ -35,11 +48,13 @@ module Rigor
     # constant it owns resolves only if the bare name reaches it at step 3: widening to the superclass's
     # RBS graph is a separate question with its own FP surface. See {.external_constant_owner}.
     #
-    # Memoised per run because step 2 runs on every constant reference whose lexical candidates all
-    # miss — which is the common case for a core-class reference (`String` inside `class Foo`). The
-    # bucket keys on the identity of the runner-seeded run-generation token (ADR-84 WD2), falling
-    # back to the per-file discovery table for runner-less scopes, so a re-run in one process (LSP,
-    # ADR-62 warm loop) cannot hit stale entries.
+    # Memoised because step 2 runs on every constant reference whose lexical candidates all miss — which
+    # is the common case for a core-class reference (`String` inside `class Foo`). The bucket keys on the
+    # identity of the discovery index, as the `Scope::ResolutionChain` memo it reads does: the chain's
+    # order depends on the analysing file's own view of the include order (a class declared in two files
+    # orders its `include`s from the reader's file first), so a run-generation key served one file's
+    # order to another (#2848). A re-run in one process (LSP, ADR-62 warm loop) builds a new index, so it
+    # cannot hit stale entries either.
     def ancestor_constant_scopes(class_name, scope)
       ancestor_constant_worlds(class_name, scope).first
     end
@@ -85,32 +100,76 @@ module Rigor
       # every call.
       return recorded_ancestor_constant_scopes(class_name, scope) if Analysis::DependencyRecorder.active?
 
-      generation = scope.run_generation || scope.discovered_superclasses
-      slot = Thread.current[ANCESTOR_SCOPES_KEY]
-      unless slot && slot[0].equal?(generation)
-        slot = [generation, {}]
-        Thread.current[ANCESTOR_SCOPES_KEY] = slot
+      # ADR-129 G2 — an audit recomputation bypasses the memo (neither read nor written).
+      if Inference::MemoAudit.enabled? && Inference::MemoAudit.suspended?
+        return compute_ancestor_constant_scopes(class_name, scope)
+      end
+
+      discovery = scope.discovery
+      state = TypingState.current
+      slot = state[ANCESTOR_SCOPES]
+      unless slot && slot[0].equal?(discovery)
+        slot = [discovery, {}]
+        state[ANCESTOR_SCOPES] = slot
       end
       bucket = slot[1]
-      bucket.fetch(class_name) { bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) }
+      worlds = bucket[class_name]
+      if worlds.nil?
+        return bucket[class_name] = Inference::MemoAudit.key_audit("ancestor constant scopes") do
+          compute_ancestor_constant_scopes(class_name, scope)
+        end
+      end
+      return worlds unless Inference::MemoAudit.enabled?
+
+      Inference::MemoAudit.check("ancestor constant scopes", audit_view(worlds), class_name) do
+        audit_view(compute_ancestor_constant_scopes(class_name, scope))
+      end
+      worlds
     end
     private_class_method :ancestor_constant_worlds
 
+    # `[scopes, chain]` compared by content: a recomputation builds a new chain object, equal to the stored one
+    # entry for entry when the key holds every input.
+    def audit_view(worlds) = [worlds[0], worlds[1].audit_signature]
+    private_class_method :audit_view
+
+    # A recomputation for the audit, its dependency reads withheld: the hit it checks files its own edges, so the
+    # recorded set stays what an unaudited run records.
+    def fresh_ancestor_constant_scopes(class_name, scope)
+      Analysis::DependencyRecorder.withhold { compute_ancestor_constant_scopes(class_name, scope) }.first
+    end
+    private_class_method :fresh_ancestor_constant_scopes
+
     # The recording run's memo. The answer is every project entry of the chain, so its edges are the
     # root's and every entry's — what `Scope::ResolutionChain#record` files, which a computation does and a
     # hit replays, in the same order. One slot keyed on the discovery index: the answer and the edges are
     # both read from it, so the key is exact, and the slot never pins more than the index it serves.
     def recorded_ancestor_constant_scopes(class_name, scope)
+      # ADR-129 G2 — an audit recomputation bypasses the memo (neither read nor written).
+      if Inference::MemoAudit.enabled? && Inference::MemoAudit.suspended?
+        return compute_ancestor_constant_scopes(class_name, scope)
+      end
+
       discovery = scope.discovery
-      slot = Thread.current[RECORDED_ANCESTOR_SCOPES_KEY]
+      state = TypingState.current
+      slot = state[RECORDED_ANCESTOR_SCOPES]
       unless slot && slot[0].equal?(discovery)
         slot = [discovery, {}]
-        Thread.current[RECORDED_ANCESTOR_SCOPES_KEY] = slot
+        state[RECORDED_ANCESTOR_SCOPES] = slot
       end
       bucket = slot[1]
       worlds = bucket[class_name]
-      return bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) if worlds.nil?
+      if worlds.nil?
+        return bucket[class_name] = Inference::MemoAudit.key_audit("recorded ancestor constant scopes") do
+          compute_ancestor_constant_scopes(class_name, scope)
+        end
+      end
 
+      if Inference::MemoAudit.enabled?
+        Inference::MemoAudit.check("recorded ancestor constant scopes", audit_view(worlds), class_name) do
+          audit_view(fresh_ancestor_constant_scopes(class_name, scope))
+        end
+      end
       chain = Scope::ResolutionChain.for(scope, class_name.to_s, :instance, :constants)
       chain.record(scope)
       record_external_owner_edges(chain)
@@ -228,7 +287,7 @@ module Rigor
     end
     private_class_method :ancestry_unknown_before?
 
-    # Ruby places these after every entry of a chain, so a constant they own is the top level's (step 4).
+    # Ruby places these after every entry of a chain, so a constant they own is the top level's.
     IMPLICIT_ANCESTORS = %w[Object Kernel BasicObject].freeze
     private_constant :IMPLICIT_ANCESTORS
 

data/lib/rigor/reflection/declaration_collectors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "prism"
+
+# Not required on its own: `rigor/inference/declaration_walk` loads it once the walk exists, and
+# {Reflection.class_declarations_in} loads that entry point on first use. Keeping the walk out of `Reflection`'s own
+# load keeps the engine-free paths engine-free (ADR-104).
+module Rigor
+  module Reflection
+    # The walk's collector behind {.class_declarations_in}; the plugin never sees it.
+    class DeclarationCollector
+      include Inference::DeclarationWalk::Collector
+
+      EMPTY_NESTING = [].freeze
+
+      attr_reader :classes
+
+      def initialize
+        @classes = []
+      end
+
+      def on_declaration(node, context, body_context)
+        if node.is_a?(Prism::ClassNode)
+          name = body_context.prefix.join("::")
+          @classes << ClassDeclaration.new(name: name, nesting: frozen_nesting(context), node: node) unless name.empty?
+        end
+        Inference::DeclarationWalk::DESCEND
+      end
+
+      private
+
+      # The walk's chain, frozen: the root's `[]` is one array shared by every top-level declaration.
+      def frozen_nesting(context)
+        nesting = context.nesting || EMPTY_NESTING
+        nesting.frozen? ? nesting : nesting.dup.freeze
+      end
+    end
+
+    # {DeclarationCollector} that also forwards every call. A subclass, because the walk dispatches only the events a
+    # collector's class overrides, so a classes-only run pays for no call event.
+    class DeclarationCallCollector < DeclarationCollector
+      def initialize(on_call)
+        super()
+        @on_call = on_call
+      end
+
+      def on_call(node, context)
+        owner = context.prefix.join("::")
+        @on_call.call(DeclaredCall.new(node: node, owner: owner.empty? ? nil : owner))
+        Inference::DeclarationWalk::DESCEND
+      end
+    end
+    private_constant :DeclarationCollector, :DeclarationCallCollector
+  end
+end

data/lib/rigor/reflection/declarations.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  # {Reflection}'s per-file declaration walk for plugins (ADR-128, #2708): {.class_declarations_in} answers which
+  # classes a parsed file declares under their `Module.nesting`-correct names, and hands each call the walk visits
+  # to a plugin together with the class or module its position reaches. It replaces a plugin's own
+  # `DeclarationWalk::Collector`, so the walk's context, its control constants and its collector protocol stay
+  # internal.
+  module Reflection
+    # One `class` header of a file, as {.class_declarations_in} reports it.
+    #
+    # - `name` — the qualified name the header's body is keyed under (`"Admin::User"` for `class User` in
+    #   `module Admin`, and for `class Admin::User`); never empty.
+    # - `nesting` — `Module.nesting` where the header is written, innermost first, not counting the class itself
+    #   (`["Admin"]` for `class User` in `module Admin`; `[]` at the top level). Frozen.
+    # - `node` — the `Prism::ClassNode`, for its `superclass` and `body`.
+    ClassDeclaration = Data.define(:name, :nesting, :node)
+
+    # One call the walk visited, as {.class_declarations_in} yields it.
+    #
+    # - `node` — the `Prism::CallNode`.
+    # - `owner` — the qualified name of the innermost `class` / `module` the call is lexically inside, or nil where
+    #   none is (the top level, or below a bare header in a `class << self` body).
+    DeclaredCall = Data.define(:node, :owner)
+
+    module_function
+
+    # ADR-128, #2708 — the classes a parsed file declares, in the order their headers are written. A class
+    # reopened in the file appears once per header. A `module`, a `class << self` and a class no name reaches
+    # (`Class.new { … }`, a header below `class << self`) are not reported.
+    #
+    # With a block, the walk also yields a {DeclaredCall} for the calls the engine's declaration walk visits, in
+    # source order, outer calls before the calls inside them. Those are the calls in statements and in the bodies of
+    # `class` / `module` / `class << self` / blocks, at any depth. The owner is lexical, not `self`: a call in
+    # `class << self` or in a `Class.new { … }` block reports the class around it.
+    #
+    # The block does not see every call node of the file. The walk does not enter, so the block never sees:
+    #
+    # - a class or module header's own expressions: the superclass (`class Foo < Struct.new(:a)`) and the constant
+    #   path (`class foo::Bar`);
+    # - the factory call a constant write binds (`K = Class.new { … }`), whose receiver, arguments and block body the
+    #   walk does enter;
+    # - the tail of such a write (`K = Class.new { … }.freeze` yields what is inside the block, not `freeze`), and
+    #   the constant-path parent of a write target (`P` in `P::K = …`).
+    #
+    # `root` is a `Prism::Node`, typically `Prism.parse(source).value`.
+    def class_declarations_in(root, &on_call)
+      # Loaded on first use, not with `Reflection`: the walk heads the analysis engine, which the engine-free
+      # paths (a warm `rigor effects`) load `Reflection` without. The walk's entry point loads the collectors.
+      require_relative "../inference/declaration_walk"
+      collector = on_call ? DeclarationCallCollector.new(on_call) : DeclarationCollector.new
+      Inference::DeclarationWalk.run(root, [collector], Inference::DeclarationWalk::Context.root(nesting: []))
+      collector.classes
+    end
+  end
+end

data/lib/rigor/reflection/project_method.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Rigor
+  # {Reflection}'s ancestor facade for plugins (ADR-128 WD1), split out for the reader rather than for the
+  # loader: {.project_method_defined} turns the two `Scope` ancestor walks into one `Trinary` answer. Reopening
+  # the module keeps it behind the facade its callers already read.
+  module Reflection
+    module_function
+
+    PROJECT_METHOD_KINDS = %i[instance singleton].freeze
+    PROJECT_METHOD_SOURCES = %i[def discovered either].freeze
+    private_constant :PROJECT_METHOD_KINDS, :PROJECT_METHOD_SOURCES
+
+    # ADR-128 WD1 — does the project define `method_name` on `class_name` or on an ancestor the project itself
+    # declares? Answers a {Trinary}: `yes` where the walk found a definer, `no` where it found none and its
+    # `ResolutionChain` was not truncated, and `maybe` where the chain was truncated at its budget before it found one
+    # (ADR-41 WD4), so a definer past the cut cannot be ruled out. It replaces a plugin's direct call to the
+    # two `Scope` walks, whose budget answers differ and are not a promise to plugin authors.
+    #
+    # - `kind:` is `:instance` or `:singleton`; each walks its own chain.
+    # - `source:` names the walk outright, with that walk's order and settling:
+    #   - `:def` — the first project `def` (`Scope#user_def_through_ancestors`, or `#singleton_def_through_ancestors`
+    #     for `kind: :singleton`). It does not count `attr_*` or `define_method`.
+    #   - `:discovered` — the discovery table (`Scope#discovered_method_through_ancestors?`), which also counts
+    #     `attr_*` and `define_method`.
+    #   - `:either` — their union as a three-valued OR: `yes` wins, then `maybe`, then `no`.
+    #
+    # A site that tested the `:def` walk's old answer tests `.yes?` (that walk read a cut as absent); a site that
+    # tested the `:discovered` walk's tests `!no?` (that walk read a cut as present).
+    def project_method_defined(class_name, method_name, kind:, source:, scope:)
+      raise ArgumentError, "unknown kind #{kind.inspect}" unless PROJECT_METHOD_KINDS.include?(kind)
+      raise ArgumentError, "unknown source #{source.inspect}" unless PROJECT_METHOD_SOURCES.include?(source)
+
+      case source
+      when :def then project_def_defined(class_name, method_name, kind, scope)
+      when :discovered then project_discovered_defined(class_name, method_name, kind, scope)
+      else project_either_defined(class_name, method_name, kind, scope)
+      end
+    end
+
+    # Does RBS declare `method_name` on `class_name` or on an ancestor the project's own ancestry reaches? A
+    # project class (`class ArticlesController < ActionController::Base`) is rarely in RBS itself; its RBS-known
+    # ancestors are the EXTERNAL entries of its `ResolutionChain`, which the RBS-only reads
+    # ({.instance_method_definition}) cannot reach from the project class's name. This walks the chain and asks RBS
+    # of each entry (every candidate spelling of an external one), on the side the entry sits.
+    #
+    # Answers a {Trinary}: `yes` when an entry's RBS declares the method, `no` when none does and the chain was
+    # not truncated, `maybe` when the chain was cut at its budget (ADR-41 WD4) before one did. `kind:` is
+    # `:instance` or `:singleton`; a `nil` `class_name` answers `no`.
+    def rbs_method_defined(class_name, method_name, kind:, scope:)
+      chain = ancestry_chain(class_name, kind, scope)
+      return Trinary.no if chain.nil?
+
+      found = chain.search(scope) do |entry|
+        chain_entry_names(entry).any? { |name| !rbs_method_on_side(name, method_name, entry.side, scope).nil? }
+      end
+      chain_answer(found, chain)
+    end
+
+    # Does the project ancestry of `class_name` reach any of `ancestor_names` (qualified names, a leading `::`
+    # ignored)? An external ancestor counts by any candidate spelling, so a superclass the project names but
+    # does not declare (`ActionController::Base`, with no RBS loaded) is found. Same `Trinary` and `kind:` as
+    # {.rbs_method_defined}.
+    def ancestry_reaches(class_name, ancestor_names, kind:, scope:)
+      chain = ancestry_chain(class_name, kind, scope)
+      return Trinary.no if chain.nil?
+
+      wanted = ancestor_names.map { |name| name.to_s.delete_prefix("::") }
+      found = chain.search(scope) do |entry|
+        chain_entry_names(entry).any? { |name| wanted.include?(name.to_s.delete_prefix("::")) }
+      end
+      chain_answer(found, chain)
+    end
+
+    def ancestry_chain(class_name, kind, scope)
+      raise ArgumentError, "unknown kind #{kind.inspect}" unless PROJECT_METHOD_KINDS.include?(kind)
+      return nil if class_name.nil?
+
+      Scope::ResolutionChain.for(scope, class_name.to_s, kind, :methods)
+    end
+    private_class_method :ancestry_chain
+
+    def chain_answer(found, chain)
+      return Trinary.yes if found
+
+      chain.truncated? ? Trinary.maybe : Trinary.no
+    end
+    private_class_method :chain_answer
+
+    def chain_entry_names(entry)
+      entry.external? ? entry.candidates : [entry.name]
+    end
+    private_class_method :chain_entry_names
+
+    def rbs_method_on_side(class_name, method_name, side, scope)
+      if side == :singleton
+        singleton_method_definition(class_name, method_name, scope: scope)
+      else
+        instance_method_definition(class_name, method_name, scope: scope)
+      end
+    end
+    private_class_method :rbs_method_on_side
+
+    # `yes` wins, then `maybe`, then `no`. The early return is a short-circuit and carries no answer of its own:
+    # `yes.or(x)` is `yes`, so removing it changes only which walks run, and so which dependencies they read.
+    def project_either_defined(class_name, method_name, kind, scope)
+      by_def = project_def_defined(class_name, method_name, kind, scope)
+      return by_def if by_def.yes?
+
+      by_def.or(project_discovered_defined(class_name, method_name, kind, scope))
+    end
+    private_class_method :project_either_defined
+
+    # The def walk answers `[node, owner]` or `[nil, nil]`, and `[nil, nil]` both when the chain holds no definer
+    # and when it was cut; the chain (memoised, so this is the one the walk read) tells the two apart.
+    def project_def_defined(class_name, method_name, kind, scope)
+      found = if kind == :singleton
+                scope.singleton_def_through_ancestors(class_name, method_name)
+              else
+                scope.user_def_through_ancestors(class_name, method_name)
+              end
+      return Trinary.yes if found.first
+
+      project_chain_truncated?(class_name, kind, scope) ? Trinary.maybe : Trinary.no
+    end
+    private_class_method :project_def_defined
+
+    # The discovery walk answers `true` both for a definer and for a cut chain, so a `true` on a cut chain is
+    # settled by searching the chain's entries for a definer, as the walk does.
+    #
+    # Issue #2968 — where the walk finds none, a class on the chain whose side is open (an open-names mark: a
+    # splatted `Struct.new(*FIELDS)`, `attr_accessor(*NAMES)`, a `define_method` under a computed name) answers
+    # `maybe`: it defines methods under names no table holds. Issue #2994 — so does an instance side whose chain mixes
+    # in a module no table names (`include(*MODS)`, `ResolutionChain#unnamed_mixin?`); the #618 top-level-`def` veto
+    # (`ExpressionTyper#instance_self_answers?`) reads the same mark, so a plugin that stands down here does not hand
+    # the call to a top-level `def`.
+    def project_discovered_defined(class_name, method_name, kind, scope)
+      unless scope.discovered_method_through_ancestors?(class_name, method_name, kind)
+        return open_side?(class_name, kind, scope) ? Trinary.maybe : Trinary.no
+      end
+      # A shortcut, not a decision: on an untruncated chain the search below finds the same definer.
+      return Trinary.yes unless project_chain_truncated?(class_name, kind, scope)
+
+      chain = Scope::ResolutionChain.for(scope, class_name.to_s, kind, :methods)
+      found = chain.search(scope) do |entry|
+        # A guard, not a decision: it mirrors `Scope#discovered_method_through_ancestors?`, whose search skips
+        # an external entry (no project name to look up). `discovered_method?(nil, ...)` is false anyway.
+        next false if entry.external?
+
+        scope.discovered_method?(entry.name, method_name, discovered_entry_kind(entry, kind))
+      end
+      found ? Trinary.yes : Trinary.maybe
+    end
+    private_class_method :project_discovered_defined
+
+    def open_side?(class_name, kind, scope)
+      return true if Scope::DiscoveryIndex.open_names_on_chain?(scope, class_name, kind)
+
+      kind == :instance && Scope::DiscoveryIndex.unnamed_mixin_on_chain?(scope, class_name)
+    end
+    private_class_method :open_side?
+
+    # A singleton-side entry reads the singleton table; a module on the singleton chain answers with its
+    # INSTANCE methods; on the instance chain the caller's kind stands (`Scope#kind_for`).
+    def discovered_entry_kind(entry, kind)
+      return :singleton if entry.side == :singleton
+
+      kind == :singleton ? :instance : kind
+    end
+    private_class_method :discovered_entry_kind
+
+    def project_chain_truncated?(class_name, kind, scope)
+      Scope::ResolutionChain.for(scope, class_name.to_s, kind, :methods).truncated?
+    end
+    private_class_method :project_chain_truncated?
+  end
+end

data/lib/rigor/reflection.rb

@@ -511,3 +511,5 @@ end
 # private candidate lookups, so the facade has to exist first.
 require_relative "reflection/constant_ancestors"
 require_relative "reflection/constant_path"
+require_relative "reflection/project_method"
+require_relative "reflection/declarations"

data/lib/rigor/rooted_glob.rb

@@ -20,7 +20,7 @@ module Rigor
 
     module_function
 
-    # @param root — a directory path (String or Pathname), taken literally
+    # @param root — a directory path, taken literally
     # @param pattern — a `Dir.glob` pattern relative to `root`
     # @return the matches spelled under `root`, in `Dir.glob` order; empty when `root` is not a directory
     def glob(root, pattern)
@@ -32,5 +32,36 @@ module Rigor
     def literal(name)
       name.to_s.gsub(METACHARACTERS, "\\\\\\0")
     end
+
+    # A configured file path (#2222), absolute or relative to the working directory, as the `[root, pattern]` pair
+    # that `glob(root, pattern)` reads as exactly that file. A relative path stays under the working directory, as
+    # it always did. An absolute one is split into its own directory and a literal basename: `File.join(".", "/abs")`
+    # reads `./abs`, so an absolute path joined under `"."` matched nothing.
+    #
+    # A `~`-prefixed path is expanded before the split (#2586): the readers apply `File.expand_path`, so `~/x.yml`
+    # reads `$HOME/x.yml` and the watch must be split from that spelling — `[".", "~/x.yml"]` would watch
+    # `./~/x.yml` and never fire. Only the `~` form is expanded; expanding every path would change how relative
+    # entries are watched.
+    #
+    # @param path — a file path, taken literally
+    # @return `[root, pattern]`: `"."` and the literal path when relative, else the directory and the literal basename
+    def split_file(path)
+      path = expand_home(path.to_s)
+      return [".", literal(path)] unless File.absolute_path?(path)
+
+      [File.dirname(path), literal(File.basename(path))]
+    end
+
+    # `File.expand_path`'s `~` handling, kept literal on failure: `~nouser/x` (or an unset HOME) names no home
+    # directory and raises `ArgumentError`; the readers fail on the same path, so the unexpanded spelling —
+    # watched under `"."` like any other relative entry — is the consistent answer.
+    def expand_home(path)
+      return path unless path.start_with?("~")
+
+      File.expand_path(path)
+    rescue ArgumentError
+      path
+    end
+    private_class_method :expand_home
   end
 end

data/lib/rigor/run_scoped_slots.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "English"
+require_relative "typing_state"
+require_relative "memo_audit"
+
+module Rigor
+  # Issues #2412 and #2399 — the run-end hook for per-thread state whose contents belong to one analysis run. An
+  # owner declares such a slot in {TypingState} with `run_scoped: true` where it names it, and each entry point that
+  # runs an analysis calls {.release} in its `ensure`, so a finished run, or one that raised, leaves none of its
+  # scopes, discovery tables or environment behind on the thread.
+  #
+  # A slot that holds its run until the next run overwrites it retains one run per thread. A slot whose value
+  # reaches its own key retains every run, as `LoopValueRecord`'s `ObjectSpace::WeakKeyMap` did: the map holds
+  # its values strongly, and a recorded scope reaches the parse tree that holds the key node. Releasing at run end
+  # bounds both. Inside a run nothing changes: every memo keeps its key and its hit rate, and a slot read outside
+  # a run (a language-server hover on the main thread) refills on its first miss.
+  #
+  # Only Tables, Memos and Resources are run-scoped. A Frame a `with_*` block installs and restores is already empty
+  # when the frame returns, and clearing it from inside a frame would break the frame.
+  #
+  # ADR-129 — run-scoped state is a `run_scoped: true` {TypingState} slot, and nothing else registers: this module
+  # keeps no key list of its own.
+  module RunScopedSlots
+    # Empties every run-scoped {TypingState} slot on the calling thread.
+    #
+    # ADR-129 WD5 (#2785) — with the memo audit on, a mismatch no file drained (one raised by typing outside the
+    # per-file loop: return summaries, return re-evaluation, sig-gen) would be released here unreported, so it is
+    # raised after the release, unless an exception is already leaving the run.
+    def self.release
+      undrained = Inference::MemoAudit.enabled? ? Inference::MemoAudit.drain : nil
+      TypingState.release_run_scoped
+      raise undrained.first if undrained && !undrained.empty? && $ERROR_INFO.nil?
+
+      nil
+    end
+  end
+end

data/lib/rigor/runtime/jit.rb

@@ -37,7 +37,7 @@ module Rigor
     # *remaining* deadline rather than restarting the window; see its own
     # comment for why that distinction is worth the bookkeeping.
     module Jit
-      # Opt-out switch: `RIGOR_DISABLE_YJIT=1` disables both entry points.
+      # Opt-out switch: `RIGOR_DISABLE_YJIT=1` disables every entry point.
       DISABLE_ENV = "RIGOR_DISABLE_YJIT"
 
       # Advanced / calibration override of the {enable_after} deadline, in