rigortype 0.3.8 → 0.4.0

data/lib/rigor/reflection.rb

@@ -45,15 +45,13 @@ module Rigor
   # out of scope for the v0.0.7 first pass; v0.1.0's plugin API added it as a separate
   # concern.
   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
+    # Issue #1290 — what {.constant_type_at} answers for a candidate the project writes but no source types, on
+    # a ladder that checks the census. Never a type: {.resolve_constant_type} replaces it before it returns.
+    WRITTEN_CANDIDATE = Object.new.freeze
+    private_constant :WRITTEN_CANDIDATE
 
     module_function
 
-    # @param class_name [String, Symbol]
-    # @param scope [Rigor::Scope]
-    # @return [Boolean]
     def class_known?(class_name, scope: Scope.empty)
       return true if scope.discovered_classes.key?(class_name.to_s)
 
@@ -92,7 +90,7 @@ module Rigor
       loader.project_declared_class?(class_name)
     end
 
-    # @return [Symbol] one of `:equal`, `:subclass`, `:superclass`,
+    # @return one of `:equal`, `:subclass`, `:superclass`,
     #   `:disjoint`, `:unknown`.
     def class_ordering(lhs, rhs, scope: Scope.empty)
       scope.environment.class_ordering(lhs, rhs)
@@ -143,10 +141,16 @@ module Rigor
     # answer to `::Foo`, and falling back to it was the bug (`::Rails` inside `module MyApp` typed
     # as `MyApp::Rails`).
     #
+    # `caller_derived: false` drops what {.toplevel_first_constant_type} takes from the caller — its
+    # namespaces and ancestors, for a bare name and for a path's head — for a reader whose miss is a
+    # meaningful answer rather than a read Ruby raises on. A constant compound write is one: an unset
+    # top-level `REGISTRY ||= {}` is the memoization idiom, and the caller's `Plugin::REGISTRY` is a binding
+    # Ruby never consults there. A path's later segments still walk their owner's ancestors.
+    #
     # This is the shared owner of the lexical-constant resolution: `Inference::ExpressionTyper`
     # reads it to type a constant read, and `Inference::Narrowing` reads it to recognise a
     # value-pinned `Constant[Regexp]` match-predicate operand.
-    def resolve_constant_type(name, scope: Scope.empty, rooted: false)
+    def resolve_constant_type(name, scope: Scope.empty, rooted: false, caller_derived: true)
       # Issue #644 — the ADR-46 name edge, recorded ONCE PER REFERENCE and BEFORE the ladder, so it does not
       # depend on which resolver answers. A reference that resolves through RBS (`Math::PI`) or through the
       # class registry is exactly as dependent on the project's constant write set as one that resolves
@@ -156,10 +160,25 @@ module Rigor
       # go stale. Over-recording is ADR-46's safe direction.
       record_constant_reference(name) if Analysis::DependencyRecorder.active?
       return constant_type_at(name, scope) if rooted
+
+      # Issue #1290 — a candidate the project writes but no source types is where Ruby's lookup stops, so it
+      # REPLACES what a lower rung answers, and nothing else. The first pass hands the census's shadowing
+      # names to the rungs ({.constant_type_at}); a stop is `Dynamic[top]` only when the plain ladder, run
+      # again, answers below it. When nothing below answers, the reference stays unresolved exactly as before,
+      # so the nil its caller turns into the fallback, the missing-constant edge and the gem-origin label stay.
+      hit = lexical_constant_type(name, scope, caller_derived, scope.shadowing_constant_names(name.to_s))
+      return hit unless hit.equal?(WRITTEN_CANDIDATE)
+
+      Type::Combinator.untyped if lexical_constant_type(name, scope, caller_derived, nil)
+    end
+
+    # {.resolve_constant_type}'s unrooted ladder. `shadows` is the census's shadowing names for the
+    # reference, which the rungs above the last check their candidates against, or nil for the plain ladder.
+    def lexical_constant_type(name, scope, caller_derived, shadows)
       # Issue #716 — a body whose `Module.nesting` was RECORDED EMPTY is definitively top level, and Ruby
       # resolves its constants there no matter which namespace calls it. Steps 1 and 2 both derive from the
       # caller and are both wrong for it, so it takes its own ladder.
-      return toplevel_first_constant_type(name, scope) if recorded_toplevel_nesting?(scope)
+      return toplevel_first_constant_type(name, scope, caller_derived, shadows) if recorded_toplevel_nesting?(scope)
 
       # Step 1 — `Module.nesting`, innermost first. Each entry contributes only its OWN constants.
       #
@@ -171,18 +190,26 @@ module Rigor
       # § "Implementation Guidelines"). Only project ancestors are walked; an RBS-known superclass
       # contributes no name here (see {.ancestor_constant_scopes}).
       #
-      # Step 3 — the bare name (top level).
-      first_constant_hit(lexical_nesting_chain(scope), name, scope) ||
-        ancestor_constant_type(name, scope, enclosing_class_path(scope)) ||
+      # Step 2.5 (#656) — the path read SEGMENT BY SEGMENT, which is the only rung that can answer a
+      # path whose head and tail have different owners. See {.resolve_constant_path_name}. It sits
+      # BELOW the whole-path rungs so no read that resolves today moves, and ABOVE step 3 because
+      # beating the top-level whole-string answer is the point: `A::B` inside `P::Guard` with
+      # `P::A < P::Base` is `P::Base::B`, and step 3's `A::B` is a real but different class.
+      #
+      # Step 3 — the bare name (top level). It takes no `shadows`: nothing sits below it for a stop to replace.
+      first_constant_hit(lexical_nesting_chain(scope), name, scope, shadows) ||
+        ancestor_constant_type(name, scope, enclosing_class_path(scope), shadows) ||
+        constant_path_type(name, scope, shadows: shadows) ||
         constant_type_at(name, scope)
     end
+    private_class_method :lexical_constant_type
 
     # The first candidate `<entry>::<name>` any source knows, walking `entries` in order, or nil. The one
     # place a qualifying prefix is joined to a name, so every rung of the ladder consults its candidates
     # identically.
-    def first_constant_hit(entries, name, scope)
+    def first_constant_hit(entries, name, scope, shadows)
       entries.each do |entry|
-        hit = constant_type_at("#{entry}::#{name}", scope)
+        hit = constant_type_at("#{entry}::#{name}", scope, shadows)
         return hit if hit
       end
       nil
@@ -190,10 +217,10 @@ module Rigor
     private_class_method :first_constant_hit
 
     # Step 2's rung on its own: nil when there is no enclosing class path to take ancestors of.
-    def ancestor_constant_type(name, scope, prefix)
+    def ancestor_constant_type(name, scope, prefix, shadows)
       return nil if prefix.nil? || prefix.empty?
 
-      first_constant_hit(ancestor_constant_scopes(prefix, scope), name, scope)
+      first_constant_hit(ancestor_constant_scopes(prefix, scope), name, scope, shadows)
     end
     private_class_method :ancestor_constant_type
 
@@ -215,20 +242,30 @@ module Rigor
     # dependabot-core — `docs/notes/20260905-toplevel-def-cref-movable-sites.md`). Rigor reports nothing
     # about them either way, so retracting them would trade a silent wrong answer for a silent absent one at
     # no gain. Making them FIRE is a separate question with its own false-positive budget.
-    def toplevel_first_constant_type(name, scope)
-      constant_type_at(name, scope) || caller_derived_constant_type(name, scope)
+    #
+    # Issue #656's rung goes LAST here rather than second: for a top-level body Ruby's own first answer
+    # for `A::B` is the top level, and a whole-string hit there already means "`A` owns `B`". The
+    # segment-wise walk only has something to add once that misses. Its head consults the caller's
+    # ancestors, so under `caller_derived: false` it resolves the head at the top level alone.
+    #
+    # Issue #1290 — the top level is this ladder's FIRST rung, so a top-level name the project writes stops it
+    # ({.constant_type_at}) before a caller's `Plug::TOP` can answer a read Ruby gives to the top-level `TOP`.
+    def toplevel_first_constant_type(name, scope, caller_derived, shadows)
+      constant_type_at(name, scope, shadows) ||
+        (caller_derived && caller_derived_constant_type(name, scope, shadows)) ||
+        constant_path_type(name, scope, caller_derived: caller_derived, shadows: shadows)
     end
     private_class_method :toplevel_first_constant_type
 
     # The peel and its ancestors — {.resolve_constant_type}'s steps 1 and 2 as they answer for a scope with
     # no recorded chain, factored out so the top-level ladder above can consult them BELOW the top level
     # instead of above it.
-    def caller_derived_constant_type(name, scope)
+    def caller_derived_constant_type(name, scope, shadows)
       prefix = enclosing_class_path(scope)
       return nil if prefix.nil? || prefix.empty?
 
-      first_constant_hit(peeled_nesting(prefix), name, scope) ||
-        ancestor_constant_type(name, scope, prefix)
+      first_constant_hit(peeled_nesting(prefix), name, scope, shadows) ||
+        ancestor_constant_type(name, scope, prefix, shadows)
     end
     private_class_method :caller_derived_constant_type
 
@@ -236,22 +273,45 @@ module Rigor
     # `Singleton[C]`), source-discovered classes, in-source value constants, then RBS-side
     # constants. In-source values win over RBS constant decls because the user's source is
     # authoritative for its own constants. Returns nil when no source knows `candidate`.
-    def constant_type_at(candidate, scope)
+    #
+    # Issue #1290 — `shadows`, passed on every rung that has a rung below it, is the last source: a candidate
+    # no other source types answers {WRITTEN_CANDIDATE} when `shadows` holds it, and {.resolve_constant_type}
+    # settles that stop. `shadows` is `Scope#shadowing_constant_names` for the reference, whose last segment
+    # every candidate shares. Ruby's lookup stops at a constant that exists, whatever its value, and the
+    # cross-file table publishes only a frozen scalar one file writes: another file's `App::LIMIT = { n: 1 }`
+    # was missed by every source, and the ladder moved on to a published top-level `LIMIT = 5`, typing `LIMIT`
+    # inside `module App` as `5` and reporting `call.undefined-method` on correct code. The value is one the
+    # analyzer does not carry, so the stop is gradual.
+    #
+    # Only an EXACT census name stops a candidate. The census keeps a path write as written
+    # ([#690](https://github.com/rigortype/rigor/issues/690)), so a suffix match would reach the as-written
+    # `Foo::BAR` from `M::Foo::BAR`, but would also stop `Admin::UsersController::X` on a top-level
+    # `UsersController::X`, losing the answer an ordinary Rails layout gets from the namespaced controller's
+    # superclass. A name written only through `||=` does not shadow, however many files memoize it: `X ||= v`
+    # resolves `X` through this same lookup, so wherever a lower rung answers, the memo finds that constant and
+    # never creates the name. The answer moves with the project's write set for the last segment, which the
+    # `constant:` edge {.resolve_constant_type} records once per reference already covers.
+    def constant_type_at(candidate, scope, shadows = nil)
       env = scope.environment
 
       singleton = env.singleton_for_name(candidate)
       return singleton if singleton
 
+      # Issue #639 — the class-EXISTENCE edge. Without it a reference-only consumer (`Foo` with no call on
+      # it) recorded nothing, so deleting the declaring file left the warm `--incremental` run serving
+      # `singleton(Foo)` where `--no-cache` answers the honest unresolved type. Recorded ahead of the lookup
+      # rather than on the hit: every rung of the ladder spells the same last segment, which is the whole of
+      # the key, so one call covers the candidates instead of a branch around each.
+      scope.record_class_existence(candidate) if Analysis::DependencyRecorder.active?
       in_source_class = scope.discovered_classes[candidate]
       return in_source_class if in_source_class
 
-      in_source_value = scope.in_source_constants[candidate]
-      if in_source_value
+      if (in_source_value = scope.in_source_constants[candidate])
         scope.record_constant_dependency(candidate) if Analysis::DependencyRecorder.active?
         return in_source_value
       end
 
-      env.constant_for_name(candidate)
+      env.constant_for_name(candidate) || (WRITTEN_CANDIDATE if shadows&.include?(candidate))
     end
     private_class_method :constant_type_at
 
@@ -267,87 +327,6 @@ module Rigor
     end
     private_class_method :record_constant_reference
 
-    # #354 — the project classes and modules whose own constants `class_name` inherits, in Ruby's
-    # ancestor order: included / prepended modules before the superclass (Ruby places mixins nearer),
-    # transitively, breadth-first. `class_name` itself is excluded — step 1 already covered it.
-    #
-    # Only PROJECT ancestors appear. `Scope#superclass_of` / `#includes_of` carry as-written names
-    # from the discovery pre-pass, and an as-written name that resolves to no discovered class or
-    # module is dropped — so a `class Foo < ActiveRecord::Base` contributes nothing and a constant
-    # owned by an RBS-known ancestor still resolves only if the bare name reaches it at step 3. That
-    # gap is deliberate for this slice: widening to the RBS ancestor graph is a separate question
-    # with its own FP surface.
-    #
-    # 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.
-    def ancestor_constant_scopes(class_name, scope)
-      # ADR-46: `superclass_of` / `includes_of` record a cross-file class dependency per consumer
-      # file, and the memo is run-scoped rather than file-scoped — a hit would skip the recording and
-      # under-record the edge for every later file. Recording runs are rare (incremental only), so
-      # they simply bypass the memo rather than complicate its key.
-      return compute_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
-      end
-      bucket = slot[1]
-      bucket.fetch(class_name) { bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) }
-    end
-    private_class_method :ancestor_constant_scopes
-
-    def compute_ancestor_constant_scopes(class_name, scope)
-      queue = [class_name]
-      seen = { class_name => true }
-      out = []
-      until queue.empty?
-        current = queue.shift
-        # Mixins first, then the superclass — Ruby's ancestor order.
-        scope.includes_of(current).each do |raw|
-          resolved = resolve_ancestor_name(current, raw, scope)
-          next if resolved.nil? || seen[resolved]
-
-          seen[resolved] = true
-          out << resolved
-          queue << resolved
-        end
-        raw_super = scope.superclass_of(current)
-        next if raw_super.nil?
-
-        resolved_super = resolve_ancestor_name(current, raw_super, scope)
-        next if resolved_super.nil? || seen[resolved_super]
-
-        seen[resolved_super] = true
-        out << resolved_super
-        queue << resolved_super
-      end
-      out.freeze
-    end
-    private_class_method :compute_ancestor_constant_scopes
-
-    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) against the nesting in
-    # force where the subclass's header is written — `Scope#ancestor_name_candidates`, the single
-    # owner of that order, which `Scope#enqueue_ancestors` reads for method lookup and the
-    # override-visibility rule reads for its own walk. Returns nil when no candidate names a
-    # discovered project class or module.
-    def resolve_ancestor_name(subclass_qualified, raw, scope)
-      scope.ancestor_name_candidates(subclass_qualified, raw)
-           .find { |candidate| known_project_namespace?(candidate, scope) }
-    end
-    private_class_method :resolve_ancestor_name
-
-    def known_project_namespace?(name, scope)
-      scope.discovered_superclasses.key?(name) ||
-        scope.discovered_includes.key?(name) ||
-        scope.discovered_classes.key?(name)
-    end
-    private_class_method :known_project_namespace?
-
     # 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 at the top level.
     def enclosing_class_path(scope)
@@ -434,7 +413,7 @@ module Rigor
       nil
     end
 
-    # Returns the full RBS singleton-side class definition.
+    # The singleton-side twin of {#instance_definition}, nil under the same conditions.
     def singleton_definition(class_name, scope: nil, environment: nil)
       loader = rbs_loader_for(scope, environment)
       return nil if loader.nil?
@@ -465,15 +444,14 @@ module Rigor
     end
     private_class_method :rbs_loader_for
 
-    # @return [Boolean] true when the analyzed source contains a class / module declaration
+    # @return true when the analyzed source contains a class / module declaration
     #   for the given name. Does NOT consult the RBS loader (use {.class_known?} for the
     #   union).
     def discovered_class?(class_name, scope: Scope.empty)
       scope.discovered_classes.key?(class_name.to_s)
     end
 
-    # @param kind [:instance, :singleton]
-    # @return [Boolean] true when the ScopeIndexer recorded a `def` for the given method on
+    # @return true when the ScopeIndexer recorded a `def` for the given method on
     #   the given class with the matching kind.
     #
     # ADR-46 — a MISS records a negative cross-file dependency, so a consumer whose analysis
@@ -497,3 +475,8 @@ module Rigor
     end
   end
 end
+
+# Loaded last: the ancestor walk and the segment-wise path walk reopen the module above and read its
+# private candidate lookups, so the facade has to exist first.
+require_relative "reflection/constant_ancestors"
+require_relative "reflection/constant_path"

data/lib/rigor/runtime/jit.rb

@@ -70,7 +70,7 @@ module Rigor
       # call is what enabled YJIT (so the `?`-suffix predicate convention does
       # not apply; hence the Naming/PredicateMethod exemption).
       #
-      # @return [Boolean] true if this call enabled YJIT; false if it was a
+      # @return true if this call enabled YJIT; false if it was a
       #   no-op (unavailable / opted out / already enabled).
       def enable_now # rubocop:disable Naming/PredicateMethod
         return false unless available?
@@ -90,8 +90,8 @@ module Rigor
       # up front (unavailable / opted out / already enabled), so callers never
       # pay for a thread that could only no-op.
       #
-      # @param seconds [Numeric] the amortization deadline.
-      # @return [Thread, nil] the deadline thread, or nil when no-op up front.
+      # @param seconds — the amortization deadline.
+      # @return the deadline thread, or nil when no-op up front.
       def enable_after(seconds)
         return nil unless available?
         return nil if disabled?
@@ -143,7 +143,7 @@ module Rigor
       # Re-arming goes through {enable_after}, so the child records the same
       # absolute deadline it inherited and a grandchild fork carries it too.
       #
-      # @return [Thread, nil] the child's deadline thread; nil when YJIT was
+      # @return the child's deadline thread; nil when YJIT was
       #   enabled immediately, and nil when the call is a no-op up front
       #   (unavailable / opted out / already enabled — a child forked after the
       #   parent enabled inherits the enabled state and has nothing to do).
@@ -166,8 +166,6 @@ module Rigor
 
       # The resolved {enable_after} deadline: {DEADLINE_ENV} when it parses to a
       # non-negative float, else {DEFAULT_DEADLINE_SECONDS}.
-      #
-      # @return [Numeric]
       def deadline_seconds
         raw = ENV.fetch(DEADLINE_ENV, nil)
         return DEFAULT_DEADLINE_SECONDS if raw.nil? || raw.empty?
@@ -176,12 +174,12 @@ module Rigor
         value && value >= 0 ? value : DEFAULT_DEADLINE_SECONDS
       end
 
-      # @return [Boolean] whether this Ruby exposes `RubyVM::YJIT.enable`.
+      # @return whether this Ruby exposes `RubyVM::YJIT.enable`.
       def available?
         defined?(RubyVM::YJIT.enable) ? true : false
       end
 
-      # @return [Boolean] whether the opt-out env switch is set.
+      # @return whether the opt-out env switch is set.
       def disabled?
         ENV[DISABLE_ENV] == "1"
       end

data/lib/rigor/scope/discovery_index.rb

@@ -15,6 +15,7 @@ module Rigor
       :class_ivars,
       :class_cvars,
       :program_globals,
+      :program_global_seeds,
       :discovered_classes,
       :in_source_constants,
       :discovered_methods,
@@ -24,17 +25,31 @@ module Rigor
       :discovered_def_sources,
       :discovered_singleton_def_sources,
       :discovered_method_visibilities,
+      :discovered_parameter_envelopes,
       :discovered_superclasses,
+      :discovered_deferred_ranges,
+      :discovered_refinements,
+      :discovered_global_write_census,
       :discovered_header_nestings,
       :discovered_includes,
+      :discovered_prepends,
+      :discovered_extends,
       :discovered_class_sources,
       :constant_sources,
+      :constant_writers,
+      :constant_shadowers,
       :published_constant_names,
       :local_constant_names,
+      :published_constant_alias_names,
+      :published_constant_ivars,
       :data_member_layouts,
       :struct_member_layouts,
       :param_inferred_types,
-      :run_generation
+      :run_generation,
+      :patched_line_readers,
+      :clears_last_status,
+      :defines_case_equality,
+      :implicit_self_evidence
     )
 
     class DiscoveryIndex
@@ -52,6 +67,57 @@ module Rigor
       # either kind.
       METHOD_KIND_BOTH = :both
 
+      # Issue #728 — the key a `discovered_header_nestings` bucket stores its class-wide chain under, beside
+      # the per-ancestor-name entries. `nil` is used because every other key in a bucket is an ancestor name
+      # as written, and no ancestor name can be nil.
+      UNKEYED_HEADER_NESTING = nil
+
+      # Issue #986 — a bucket entry is normally ONE chain (`["Wrap"]`, innermost first). When the
+      # compact-header rename pass lands two declarations of one class on a single key and both wrote the
+      # same raw ancestor name in DIFFERENT crefs, the entry is instead the LIST of those chains —
+      # `[["Wrap"], []]` — because no union of them is Ruby's answer for either site. `Scope` resolves each
+      # alternative and declines outright when they name two different project classes: which one wins
+      # depends on the runtime load order of the two `include`s, which static analysis cannot know, so
+      # picking either is unsound. A chain's entries are Strings and an alternatives list's are Arrays, so
+      # the two shapes cannot be confused.
+      def self.ambiguous_header_nesting?(entries)
+        entries.first.is_a?(Array)
+      end
+
+      # Issue #992 — the two class-wide keys a `discovered_parameter_envelopes` bucket can carry beside its
+      # `[kind, method_name]` entries. Their PRESENCE is the fact; the value is always
+      # `Source::ParameterEnvelope::OPAQUE`, so a bucket folds under the one join every other entry does.
+      # Symbols, because every per-method key is an Array and neither can collide with the other.
+      #
+      # - {ENVELOPE_MODULE_MARK}: the name is declared with `module` (or `Const = Module.new do … end`) somewhere
+      #   in the project. An instance of it is an instance of an unknown includer.
+      # - {ENVELOPE_DYNAMIC_MARK}: the class body rewrites its method table in a way no literal argument names
+      #   (`class_eval`, a computed `define_method`, `send`, a non-constant mixin), or a constant-receiver form
+      #   of those names it from outside.
+      # - {ENVELOPE_OBJECT_EXTENDED_MARK}: some method body passes the module to `extend`, so an object of any
+      #   class may carry its instance methods ahead of that class's own.
+      # - {ENVELOPE_REFINED_MARK}: a `refine` block refines the class, which redefines its methods wherever a `using`
+      #   is in effect. Issue #1367 splits it from {ENVELOPE_DYNAMIC_MARK}, which it used to share: an implicit
+      #   conversion (`to_str`, `to_int`) ignores a refinement, so the `global.*` rules must tell the two apart.
+      #   Every reader that asks whether a surface is rewritten reads both ({.rewritten_surface?}).
+      ENVELOPE_MODULE_MARK = :"<module>"
+      ENVELOPE_DYNAMIC_MARK = :"<dynamic>"
+      ENVELOPE_OBJECT_EXTENDED_MARK = :"<object-extended>"
+      ENVELOPE_REFINED_MARK = :"<refined>"
+
+      # Whether an envelope bucket says the project rewrites the class's method table beyond its literal names: a
+      # dynamic rewrite, or a refinement.
+      def self.rewritten_surface?(bucket)
+        bucket.key?(ENVELOPE_DYNAMIC_MARK) || bucket.key?(ENVELOPE_REFINED_MARK)
+      end
+
+      # Issue #992 — the class key a WHOLE-PROJECT discovery pass adds to `discovered_parameter_envelopes`
+      # (`ScopeIndexer#finalize_def_index`), with an empty bucket. A single file's walk alone — `run_source`,
+      # the LSP `prebuilt:` scope — sees one `def` and cannot see the reopening, subclass or `class_eval` in
+      # another file that would make it opaque, so `call.wrong-arity` reads an envelope only when this key is
+      # present. Not a constant character, so no class can be named it.
+      ENVELOPE_PROJECT_WIDE = "<project-wide>"
+
       # The shared all-empty index `Scope.empty` (and every scope that never sees a seeding pass) points at — one
       # allocation per process.
       EMPTY = new(
@@ -59,6 +125,12 @@ module Rigor
         class_ivars: EMPTY_TABLE,
         class_cvars: EMPTY_TABLE,
         program_globals: EMPTY_TABLE,
+        # Issue #1362 — for each global in `program_globals` that Ruby's own signatures declare (`$VERBOSE: bool?`,
+        # `$stdout: IO`), its declared type joined with its writes in the file: what every method body and the top
+        # level start from, under the ADR-58 `:global` mark. Any other global starts from its `program_globals` entry,
+        # which keeps the writes alone for the consumers that compare against them (the mark's gates, and `$;` for
+        # `split`). Filled by `Inference::ScopeIndexer.index` from the file's own tree only.
+        program_global_seeds: EMPTY_TABLE,
         discovered_classes: EMPTY_TABLE,
         in_source_constants: EMPTY_TABLE,
         discovered_methods: EMPTY_TABLE,
@@ -79,21 +151,81 @@ module Rigor
         discovered_def_sources: EMPTY_TABLE,
         discovered_singleton_def_sources: EMPTY_TABLE,
         discovered_method_visibilities: EMPTY_TABLE,
+        # Issue #992 — `{qualified class name => {[kind, method_name] => Source::ParameterEnvelope}}`, the
+        # parameter envelope of every method the declaration walk records, plus {ENVELOPE_MODULE_MARK} /
+        # {ENVELOPE_DYNAMIC_MARK}. Written beside `discovered_methods` by one recorder, so an `alias` / `attr_*`
+        # / `define_method` name is always present here as `OPAQUE`, and folded across files and reopenings
+        # with `Source::ParameterEnvelope.merge`: one value per name, a real envelope only while every
+        # contribution agrees. Read by `call.wrong-arity` for a method no signature declares.
+        discovered_parameter_envelopes: EMPTY_TABLE,
         discovered_superclasses: EMPTY_TABLE,
+        # Issue #1097 — `{file path => [[start_offset, end_offset, name, kind, owner], ...]}`, every
+        # `def` / block / lambda body range in the file. `Scope#*_def_shadows_call?` reads it to tell
+        # an eager class-body call (orderable by offset against a same-name, same-owner def entry)
+        # from a deferred one (contained in any range — it runs at invocation time, when every
+        # class-body def exists). Def entries carry the method name, the `:instance` / `:singleton` /
+        # `:both` (module_function) kind, and the qualified owner; block / lambda rows and defs nested
+        # inside another deferred range carry nils and answer only the containment half. Plain data,
+        # so the ADR-85 seed bundle round-trips it unchanged.
+        discovered_deferred_ranges: EMPTY_TABLE,
+        # Issue #1120 — `{refined class name => {method name => [refining module names]}}`, the instance
+        # methods a `refine X do … end` block defines. They are not X's methods everywhere: Ruby activates them
+        # only lexically after a `using` of the refining module, so `call.undefined-method` reads this table
+        # together with the call site's file ({Analysis::CheckRules::LexicalMethodSites}) and never through
+        # `discovered_methods`. A refinement a `Module.new { … }` block defines has no nameable module; it is
+        # keyed by the name the walk gives the block's owner. Plain data, so the ADR-85 seed bundle
+        # round-trips it unchanged.
+        discovered_refinements: EMPTY_TABLE,
+        # Issue #1367 — the project's `Inference::GlobalWriteCensus`: the globals any `alias` names, the
+        # `write` / `to_str` / `to_int` / hatch names any file defines (inside a refinement or not), and the
+        # modules a top-level mixin names, over every file and inside method bodies too. The `global.*` write rules
+        # read it. The project pre-pass seeds the whole project's census and `Inference::ScopeIndexer.index` adds the
+        # analysed file's own. Plain data, so the ADR-85 seed bundle round-trips it unchanged.
+        discovered_global_write_census: EMPTY_NAME_SET,
         # Issue #682 — `{qualified class name => Module.nesting where its declaration HEADER is written}`,
         # innermost first and EXCLUDING the declaration's own entry. Read by `Scope#ancestor_name_candidates`,
         # which resolves a superclass / include name in that cref instead of peeling the subclass's qualified
         # name — the peel is the nested spelling's answer, and it searched an `Admin::Base` that a compact
         # `class Admin::Widget < Base` written at the top level never reaches. An absent entry means "not
         # recorded" and keeps the peel, so a scope that never saw a declaration walk is unchanged.
+        #
+        # Issue #728 — the value is keyed by the ancestor NAME the site wrote, because a class's declaration
+        # sites need not share a cref: `class Foo < Base` at the top level and `class ::Foo; include Helper`
+        # inside `module Outer` resolve `Base` and `Helper` in different ones, and a single chain per class
+        # gave `Outer` to both. {UNKEYED_HEADER_NESTING} holds the union over every ancestor-naming site, for
+        # a name no site recorded under its own key.
         discovered_header_nestings: EMPTY_TABLE,
         discovered_includes: EMPTY_TABLE,
+        # Issue #1123 — `{qualified class or module name => [module names it `prepend`s, as written]}`,
+        # stored in instance-ancestor SEARCH order (nearest prepend first), the `discovered_extends`
+        # convention. The instance-side twin `discovered_includes` holds the same names — prepends
+        # included — in that order too since #1173: prepends ahead of includes, each nearest-first. The
+        # kind still cannot be told apart there, so `Scope#user_def_through_ancestors` reads the wedge
+        # from here. An absent entry means "prepends nothing", which is the un-preprended behaviour
+        # every scope had before it existed.
+        discovered_prepends: EMPTY_TABLE,
+        # Issue #898 — the singleton-side twin of `discovered_includes`: `{qualified class or module name =>
+        # [module names it `extend`s, as written]}`, built by the same `ScopeIndexer` walk that #526 already
+        # ran to fold an extended module's instance defs onto the extending class's singleton. #526 consumed
+        # the table inside the indexer and threw it away; `Narrowing` needs it to survive onto the scope,
+        # because `Singleton[C]`'s ancestry is exactly what `extend` writes and nothing else records it.
+        discovered_extends: EMPTY_TABLE,
         discovered_class_sources: EMPTY_TABLE,
         # Issue #644 — `{qualified constant name => Set[declaring file]}`, the write attribution behind the
         # cross-file value-constant table. Read only by `Scope#record_constant_dependency` during ADR-46
         # dependency recording, so the runner seeds it only on a recording run; every other run leaves it
         # empty and the edge costs one nil check.
         constant_sources: EMPTY_TABLE,
+        # Issue #617 — the censused names that bind (any write other than a memo `||=`, or memos of the
+        # segment in two files), grouped by LAST SEGMENT, wildcard keys (`*::LIMIT`) under their segment.
+        # `Scope#bound_constant_names` reads it for a constant compound write whose plain read resolves to
+        # nothing: such a name is bound, just not to a value the analyzer carries. Seeded on every run, because
+        # the question is a typing one rather than a recording one.
+        constant_writers: EMPTY_TABLE,
+        # Issue #1290 — the censused names some write other than a memo `||=` assigns, grouped by LAST SEGMENT.
+        # `Scope#shadowing_constant_names` reads it for the lexical ladder: a candidate no source types but this
+        # table holds is where Ruby's lookup stops. Seeded on every run beside `constant_writers`.
+        constant_shadowers: EMPTY_TABLE,
         # Issue #644 — the two halves of `Scope#published_constant?`, the question
         # {Analysis::CheckRules::PublishedConstantGuard} asks. `published_constant_names` is the LAST
         # SEGMENTS of the project-wide published table (run-wide, seeded by the runner);
@@ -102,6 +234,16 @@ module Rigor
         # author cannot see. Both empty outside a runner-seeded scope, which makes the guard a no-op there.
         published_constant_names: EMPTY_NAME_SET,
         local_constant_names: EMPTY_NAME_SET,
+        # Issue #667 — the two per-file tables that carry a published constant's provenance across a COPY,
+        # which the name sets above cannot: they answer about a reference's spelling, and a copy has none.
+        # `published_constant_alias_names` is the last segments of the constants THIS FILE assigns straight
+        # from a foreign published one (`MODE2 = AppConfig::MODE`), which the local-declaration exemption
+        # would otherwise release. `published_constant_ivars` is `{class name => Set[ivar name]}` for an ivar
+        # whose class-ivar seed is such a copy (`@mode = AppConfig::MODE` in `initialize`), stamped onto the
+        # flow carrier at method entry. Both are seeded by `ScopeIndexer.index` and only when the project
+        # published something, so a project with no cross-file value constants pays no walk.
+        published_constant_alias_names: EMPTY_NAME_SET,
+        published_constant_ivars: EMPTY_TABLE,
         data_member_layouts: EMPTY_TABLE,
         struct_member_layouts: EMPTY_TABLE,
         # ADR-67 WD3 — the call-site parameter-inference table, keyed by `[class_name, method_name, kind]` (the
@@ -117,7 +259,28 @@ module Rigor
         # cross a run boundary (LSP / ADR-62 warm-loop re-runs land in a fresh bucket). Nil on scopes that
         # never see the runner seed (single-file probes, `run_source` before the seed applies): the memo
         # falls back to today's per-file `discovered_def_nodes` identity for those.
-        run_generation: nil
+        run_generation: nil,
+        # Issue #1359 — the `gets` / `readline` names this file patches in through the `define_method` family
+        # (`$stdin.define_singleton_method(:gets) { … }`, `IO.define_method(:gets)`, `alias_method :gets, :x`, or a
+        # computed name, which may be either), which `Inference::LastLine.reads_line?` declines on, as it does on a
+        # name `BlockCallTiming.project_defines_anywhere?` finds. Filled by `Inference::ScopeIndexer.index` from the
+        # file's own tree only.
+        patched_line_readers: EMPTY_NAME_SET,
+        # Issue #1360 — true when this file holds a call that may set `$?` to nil (`Inference::LastStatus.clears?`: a
+        # `wait`-family call with a flags argument, or `waitall`), which may run between any subprocess and a read of
+        # `$?`, so `Inference::LastStatus.after` binds it nowhere in the file. Filled by `Inference::ScopeIndexer.index`
+        # from the file's own tree only.
+        clears_last_status: false,
+        # Issue #1360 — true when this file holds a `define_method` or `define_singleton_method` call whose literal
+        # name is `===` (`Inference::ErrorInfo.defines_case_equality?`), which may give a class the singleton `===`
+        # `rescue` matches with; the class it lands on is not recorded, so no rescued class binds `$!` in the file.
+        # Filled by `Inference::ScopeIndexer.index` from the file's own tree only.
+        defines_case_equality: false,
+        # Issue #1415 — the file's evidence about the `self` its implicit-self `gets` / `readline` readers run with
+        # (`Inference::LastLine::SelfEvidence`, read on the first ask), which `Inference::LastLine.reads_line?` reads
+        # them by. Filled by `Inference::ScopeIndexer.index` from the file's own tree only; nil, where no file was
+        # indexed, declines every such reader.
+        implicit_self_evidence: nil
       )
     end
   end