rigortype 0.3.9 → 0.4.0

data/lib/rigor/scope.rb

@@ -7,6 +7,7 @@ require_relative "analysis/fact_store"
 require_relative "analysis/dependency_recorder"
 require_relative "inference/expression_typer"
 require_relative "inference/flow_tracer"
+require_relative "inference/optimistic_origin"
 require_relative "inference/statement_evaluator"
 require_relative "inference/def_node_resolver"
 
@@ -23,10 +24,12 @@ module Rigor
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced, :published_constant_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
-                :opaque_block_self, :lexical_nesting,
+                :opaque_block_self, :singleton_class_body, :lexical_nesting,
                 :dynamic_origins, :local_origins, :ivar_origins,
                 :void_origins, :plugin_typed_calls,
-                :optimistic_origins, :optimistic_locals, :optimistic_ivars
+                :optimistic_origins, :optimistic_locals, :optimistic_ivars,
+                :repeated_or_writes, :match_frame,
+                :constant_narrowings, :guard_records
 
     # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
     # reference; the per-table readers stay on Scope so engine call sites and plugins are unaffected by the
@@ -47,8 +50,23 @@ module Rigor
     def discovered_def_sources = @discovery.discovered_def_sources
     def discovered_singleton_def_sources = @discovery.discovered_singleton_def_sources
     def discovered_method_visibilities = @discovery.discovered_method_visibilities
+    def discovered_parameter_envelopes = @discovery.discovered_parameter_envelopes
     def discovered_superclasses = @discovery.discovered_superclasses
+
+    # Issue #1097 — `{file path => [[start_offset, end_offset, name, kind, owner], ...]}`, the def /
+    # block / lambda body ranges {singleton_def_shadows_call?} / {instance_def_shadows_call?} order a
+    # project-defined override against.
+    def discovered_deferred_ranges = @discovery.discovered_deferred_ranges
+    # Issue #1120 — `{refined class name => {method name => [refining module names]}}`: what each
+    # `refine X do … end` block defines, visible only where a `using` of its module is in effect.
+    def discovered_refinements = @discovery.discovered_refinements
+    # Issue #1367 — the project's `Inference::GlobalWriteCensus`, a `Set` of frozen entries.
+    def discovered_global_write_census = @discovery.discovered_global_write_census
     def discovered_includes = @discovery.discovered_includes
+    # Issue #1123 — `{qualified class or module name => [module names it `prepend`s, as written]}`, in
+    # instance-ancestor search order (nearest prepend first). Feeds {#prepends_of}, the one table that tells
+    # a `prepend` from an `include` at `def`-priority level.
+    def discovered_prepends = @discovery.discovered_prepends
     def discovered_extends = @discovery.discovered_extends
     def discovered_class_sources = @discovery.discovered_class_sources
     # Issue #644 — `{qualified constant name => Set[declaring file]}`; seeded only on an ADR-46 recording run.
@@ -56,6 +74,26 @@ module Rigor
     def published_constant_names = @discovery.published_constant_names
     def local_constant_names = @discovery.local_constant_names
 
+    # Issue #617 — the census names sharing `name`'s last segment that bind, spelled as the census spells
+    # them (a `*::LIMIT` wildcard included), so the caller still decides which of them a reference resolves
+    # to. A `||=`-only name is left out while no other file memoizes its segment: the memoization idiom's
+    # own write, however often one file repeats it, is not what binds it.
+    def bound_constant_names(name)
+      @discovery.constant_writers[name.split("::").last] || EMPTY_BOUND_CONSTANT_NAMES
+    end
+
+    # Issue #1290 — the census names sharing `name`'s last segment that some write other than a memo `||=`
+    # assigns: the ones that shadow an outer constant of the name, so the lexical ladder stops at them
+    # (`Reflection.resolve_constant_type`). That asks once per constant reference, so a bare name is looked up
+    # as it stands rather than split.
+    def shadowing_constant_names(name)
+      segment = name.include?("::") ? name.split("::").last : name
+      @discovery.constant_shadowers[segment] || EMPTY_BOUND_CONSTANT_NAMES
+    end
+
+    EMPTY_BOUND_CONSTANT_NAMES = [].freeze
+    private_constant :EMPTY_BOUND_CONSTANT_NAMES
+
     # Issue #667 — the instance-variable names of `class_name` whose class-ivar seed comes from a foreign
     # published constant (`@mode = AppConfig::MODE` in `initialize`, read in a sibling method).
     # `StatementEvaluator#seed_instance_ivars` stamps the flow mark for these at method-body entry, the way
@@ -186,10 +224,29 @@ module Rigor
     # Issue #667 — the empty answer of {#published_constant_ivars_for}, so a class with no such ivar (every
     # class in a project that publishes nothing) allocates none.
     EMPTY_PUBLISHED_CONSTANT_IVARS = Set.new.freeze
+    # The index `||=` sites of a repeating block body whose slot an earlier run of the body may have filled,
+    # keyed by node identity and laid by a block-return pass at the body's entry
+    # ({#with_repeated_or_writes}; `Inference::RepeatedOrWrites` decides which). The memoizing `||=` reading
+    # (`StatementEvaluator#index_compound_write_value`) is withheld at such a site. The mark belongs to the
+    # site, so no rebind or narrowing of a variable drops it, and a join keeps a site either arm holds: the
+    # mark only ever withholds that reading, whose answer is the narrower one.
+    EMPTY_REPEATED_OR_WRITES = {}.compare_by_identity.freeze
+    # Issue #1429 — the narrowing a guard leaves on a constant reference (`STDOUT.is_a?(StringIO)`, `if CONFIG`),
+    # keyed by the reference's spelling ({Inference::Narrowing.constant_key}: `"STDOUT"`, `"::Foo::BAR"`). A constant
+    # has no binding of its own in the scope, so the table is what a read in the guarded edge answers
+    # (`ExpressionTyper#type_of_constant_read`); a spelling it does not hold resolves as before.
+    EMPTY_CONSTANT_NARROWINGS = {}.freeze
+    # Issue #1429 — what each global and constant a guard narrowed was bound to before the guard, keyed
+    # `[:global, :$name]` / `[:constant, key]`. Ruby may rebind a global (or `const_set` a constant) whenever code the
+    # analysis cannot see runs, so a call or block that may run project or unresolved code restores each recorded
+    # binding to the union of this pre-guard type and its narrowed one ({#forget_guard_narrowings}). A write drops
+    # the record ({#with_global}), and a name the frame-local special-variable machinery owns is never recorded.
+    EMPTY_GUARD_RECORDS = {}.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
                      :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED,
                      :EMPTY_FOLD_SAFE, :EMPTY_ORIGINS, :EMPTY_PUBLISHED_CONSTANT_SOURCED,
-                     :EMPTY_PUBLISHED_CONSTANT_IVARS
+                     :EMPTY_PUBLISHED_CONSTANT_IVARS, :EMPTY_REPEATED_OR_WRITES,
+                     :EMPTY_CONSTANT_NARROWINGS, :EMPTY_GUARD_RECORDS
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -245,6 +302,7 @@ module Rigor
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
       opaque_block_self: false,
+      singleton_class_body: false,
       lexical_nesting: nil,
       dynamic_origins: {}.compare_by_identity,
       local_origins: EMPTY_ORIGINS,
@@ -253,7 +311,11 @@ module Rigor
       plugin_typed_calls: {}.compare_by_identity,
       optimistic_origins: {}.compare_by_identity,
       optimistic_locals: EMPTY_ORIGINS,
-      optimistic_ivars: EMPTY_ORIGINS
+      optimistic_ivars: EMPTY_ORIGINS,
+      repeated_or_writes: EMPTY_REPEATED_OR_WRITES,
+      match_frame: nil,
+      constant_narrowings: EMPTY_CONSTANT_NARROWINGS,
+      guard_records: EMPTY_GUARD_RECORDS
     )
       @environment = environment
       @locals = locals
@@ -270,6 +332,7 @@ module Rigor
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @opaque_block_self = opaque_block_self
+      @singleton_class_body = singleton_class_body
       @lexical_nesting = lexical_nesting
       @dynamic_origins = dynamic_origins
       @local_origins = local_origins
@@ -279,6 +342,10 @@ module Rigor
       @optimistic_origins = optimistic_origins
       @optimistic_locals = optimistic_locals
       @optimistic_ivars = optimistic_ivars
+      @repeated_or_writes = repeated_or_writes
+      @match_frame = match_frame
+      @constant_narrowings = constant_narrowings
+      @guard_records = guard_records
       freeze
     end
 
@@ -291,19 +358,30 @@ module Rigor
       self
     end
 
-    def optimistic_local(name) = @optimistic_locals[name.to_sym]
-    def optimistic_ivar(name) = @optimistic_ivars[name.to_sym]
+    def optimistic_local(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_locals[name.to_sym])
+    def optimistic_ivar(name) = Inference::OptimisticOrigin.bound_cause(@optimistic_ivars[name.to_sym])
+
+    # Issue #1302 — what the value a marked local / ivar is bound to answers on a miss, as its binding recorded
+    # it beside the mark, or {Inference::OptimisticOrigin::UNKNOWN_MISS}. The answer lives in the mark's own
+    # table entry ({Inference::OptimisticOrigin::BoundMark}), so every transition that keeps or drops the mark
+    # keeps or drops the answer with it.
+    def optimistic_local_miss(name) = Inference::OptimisticOrigin.bound_miss(@optimistic_locals[name.to_sym])
+    def optimistic_ivar_miss(name) = Inference::OptimisticOrigin.bound_miss(@optimistic_ivars[name.to_sym])
 
-    def with_optimistic_local(name, cause)
+    # `miss` is what the bound value answers when the bet fails ({Inference::OptimisticOrigin.miss_answer}); the
+    # default records none, so a read through the binding widens as an untold miss does.
+    def with_optimistic_local(name, cause, miss: Inference::OptimisticOrigin::UNKNOWN_MISS)
       return self if cause.nil?
 
-      rebuild(optimistic_locals: @optimistic_locals.merge(name.to_sym => cause).freeze)
+      mark = Inference::OptimisticOrigin.bound_mark(cause, miss)
+      rebuild(optimistic_locals: @optimistic_locals.merge(name.to_sym => mark).freeze)
     end
 
-    def with_optimistic_ivar(name, cause)
+    def with_optimistic_ivar(name, cause, miss: Inference::OptimisticOrigin::UNKNOWN_MISS)
       return self if cause.nil?
 
-      rebuild(optimistic_ivars: @optimistic_ivars.merge(name.to_sym => cause).freeze)
+      mark = Inference::OptimisticOrigin.bound_mark(cause, miss)
+      rebuild(optimistic_ivars: @optimistic_ivars.merge(name.to_sym => mark).freeze)
     end
 
     # ADR-82 WD1 — the propagated origin of the `Dynamic` value currently bound to a local / instance
@@ -331,6 +409,13 @@ module Rigor
     end
 
     def with_local(name, type)
+      bind_local(name, type, keep_marks: false)
+    end
+
+    # The one body behind {#with_local} and {#with_mutated_local}, which differ only in whether the two marks a
+    # write drops survive. Passing the kept sets through unchanged, rather than dropping and re-adding them, keeps
+    # a mutation's rebind to the one `rebuild` a write costs.
+    def bind_local(name, type, keep_marks:)
       # `rigor trace` — the moment a local enters the scope.
       Inference::FlowTracer.bind(name, type) if Inference::FlowTracer.active?
       new_locals = @locals.merge(name.to_sym => type).freeze
@@ -349,14 +434,15 @@ module Rigor
       rebuild(locals: new_locals, fact_store: new_fact_store,
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
-              declaration_sourced: drop_declaration_sourced_for(:local, name),
+              declaration_sourced: keep_marks ? @declaration_sourced : drop_local_declaration_marks(name),
               # Issue #667 — rebinding is flow-live for the published-constant mark too: the new value need
               # not be a copy of anything. `with_published_constant_mark` re-stamps afterward when the write's
               # rvalue is one.
               published_constant_sourced: drop_published_constant_sourced_for(:local, name),
               local_origins: drop_origin(@local_origins, name),
-              optimistic_locals: drop_origin(@optimistic_locals, name))
+              optimistic_locals: keep_marks ? @optimistic_locals : drop_origin(@optimistic_locals, name))
     end
+    private :bind_local
 
     def with_fact(fact)
       rebuild(fact_store: fact_store.with_fact(fact))
@@ -420,6 +506,27 @@ module Rigor
     # True when this scope sits inside a block whose `self` is unmodelled ({#entering_opaque_block}).
     def opaque_block_self? = @opaque_block_self
 
+    # Issue #963 — marks the body of a `class << ...` as such. Inside it `self` is the SINGLETON class, which
+    # Rigor models with the same `Singleton[X]` carrier a `class X` body gets, so the carrier alone cannot say
+    # which of the two a scope came from. The distinction decides what `define_method` does: in a `class << self`
+    # body it defines a CLASS method (`self` there is the singleton class), while in every other body reached
+    # with a `Singleton[X]` self — a `class X` body, `def self.x`, a `def` inside `class << self` — `self` is the
+    # class object and the same call defines an INSTANCE method.
+    #
+    # The mark is stamped at singleton-class-body entry and inherited by every scope derived inside it, blocks
+    # included; a `def` body starts from a fresh scope and therefore clears it by construction, which is exactly
+    # the boundary the distinction needs. A meta-class body (`Class.new do ... end`) clears it explicitly: that
+    # block is a class body of its own, whatever encloses it.
+    def with_singleton_class_body(flag)
+      return self if @singleton_class_body == flag
+
+      rebuild(singleton_class_body: flag)
+    end
+
+    # True when this scope IS a `class << ...` body (not merely inside one lexically — a `def` reached from it
+    # answers false).
+    def singleton_class_body? = @singleton_class_body
+
     # True when `name`'s `Struct` member reads are fold-safe in this body (the local is provably never mutated /
     # aliased / escaped).
     def struct_fold_safe?(name)
@@ -486,6 +593,20 @@ module Rigor
       rebuild(declaration_sourced: add_declaration_sourced(:local, name))
     end
 
+    # Issue #1287 — rebinds `name` for an in-place mutation of the object it already holds: a mutator's widening
+    # (`r << x`), a content floor after a closure or callee mutated it, an element or member write through it. The
+    # binding still names the same object, so this is not a flow-live write, and the marks `with_local` drops stay:
+    # ADR-58's declaration-sourced mark and issue #286's optimistic nil-freeness mark, with the miss answer issue
+    # #1302 records in it. A source-level write keeps going through `with_local`, which drops both.
+    #
+    # Two other per-local tables are deliberately still dropped. An ADR-82 `local_origins` cause explains the
+    # `Dynamic` the ASSIGNMENT bound, and a floor's `Dynamic[top]` has a different cause. Issue #667's
+    # published-constant mark can never be live here: only a frozen scalar publishes, and a frozen value is not
+    # mutated in place.
+    def with_mutated_local(name, type)
+      bind_local(name, type, keep_marks: true)
+    end
+
     # Issue #667 — record that `name` is currently bound to a value copied out of a foreign published
     # constant. Always applied AFTER the `with_local` / `with_ivar` that binds the value (both drop the mark
     # unconditionally), exactly as {#with_local_declaration_mark} is.
@@ -505,6 +626,8 @@ module Rigor
     # ADR-58 WD1 — true when `(kind, name)`'s binding optionality is purely declaration-sourced (no flow-live
     # write/narrowing has touched it).
     def declaration_sourced?(kind, name)
+      return false if @declaration_sourced.empty?
+
       @declaration_sourced.include?([kind.to_sym, name.to_sym])
     end
 
@@ -548,24 +671,287 @@ module Rigor
       rebuild(cvars: @cvars.merge(name.to_sym => type).freeze)
     end
 
+    # Issue #1362 — a write or narrowing of a global is flow-live, so it drops the ADR-58 `:global` mark
+    # {#seed_declaration_sourced_global} stamped on the program-global seed.
+    #
+    # Issue #1429 — `$stdout` and `$>` are one variable, so a write to either also restores a guard's narrowing of the
+    # other ({#forget_guard_narrowing_of}).
     def with_global(name, type)
-      rebuild(globals: @globals.merge(name.to_sym => type).freeze)
+      name = name.to_sym
+      written = rebuild(globals: @globals.merge(name => type).freeze,
+                        declaration_sourced: drop_declaration_sourced_for(:global, name),
+                        guard_records: drop_guard_record(:global, name))
+      alias_name = STDOUT_ALIASES[name]
+      alias_name ? written.forget_guard_narrowing_of(:global, alias_name) : written
+    end
+
+    STDOUT_ALIASES = { :$stdout => :$>, :$> => :$stdout }.freeze
+    private_constant :STDOUT_ALIASES
+
+    # Issue #1429 — {#forget_guard_narrowings} for the one name `[kind, name]`.
+    def forget_guard_narrowing_of(kind, name)
+      key = [kind, name]
+      pre_guard = @guard_records[key]
+      return self if pre_guard.nil?
+
+      if kind == :global
+        current = @globals[name]
+        globals = current ? @globals.merge(name => Type::Combinator.union(pre_guard, current)).freeze : @globals
+        rebuild(globals: globals, guard_records: @guard_records.except(key).freeze)
+      else
+        current = @constant_narrowings[name]
+        constants = if current
+                      @constant_narrowings.merge(name => Type::Combinator.union(pre_guard, current)).freeze
+                    else
+                      @constant_narrowings
+                    end
+        rebuild(constant_narrowings: constants, guard_records: @guard_records.except(key).freeze)
+      end
+    end
+
+    # Issue #1429 — binds the global `name` to `type` on a guard's edge, recording `pre_guard`, the binding the guard
+    # narrowed, unless an earlier guard already recorded one ({EMPTY_GUARD_RECORDS}). `record: false` is the
+    # frame-local specials' form, which binds without a record: their own machinery forgets them.
+    def with_guarded_global(name, type, pre_guard, record: true)
+      name = name.to_sym
+      records = record ? add_guard_record([:global, name].freeze, pre_guard) : drop_guard_record(:global, name)
+      rebuild(globals: @globals.merge(name => type).freeze,
+              declaration_sourced: drop_declaration_sourced_for(:global, name),
+              guard_records: records)
+    end
+
+    # Issue #1429 — the type a guard narrowed the constant reference `key` to, or nil.
+    def constant_narrowing(key)
+      return nil if @constant_narrowings.empty?
+
+      @constant_narrowings[key]
+    end
+
+    # Issue #1429 — the constant reference `key` read as `type` on a guard's edge, recording `pre_guard` as
+    # {#with_guarded_global} does.
+    def with_constant_narrowing(key, type, pre_guard)
+      rebuild(constant_narrowings: @constant_narrowings.merge(key => type).freeze,
+              guard_records: add_guard_record([:constant, key].freeze, pre_guard))
+    end
+
+    # Issue #1429 — every constant reference whose last segment is `name` with no narrowing: what a write to a constant
+    # named `name` leaves, since `Foo::BAR` and `BAR` may name the one it wrote.
+    def without_constant_narrowings_named(name)
+      keys = @constant_narrowings.keys.select { |key| key.split("::").last == name }
+      return self if keys.empty?
+
+      records = @guard_records.reject { |(kind, key), _| kind == :constant && keys.include?(key) }
+      rebuild(constant_narrowings: @constant_narrowings.except(*keys).freeze, guard_records: records.freeze)
+    end
+
+    # Issue #1429 — the constant reference `key` with no narrowing.
+    def without_constant_narrowing(key)
+      return self unless @constant_narrowings.key?(key)
+
+      rebuild(constant_narrowings: @constant_narrowings.except(key).freeze,
+              guard_records: @guard_records.except([:constant, key]).freeze)
+    end
+
+    # True when a guard's narrowing of a global or constant is live, the state {#forget_guard_narrowings} drops and
+    # so the gate on every scan that decides whether to.
+    def guard_narrowed?
+      !@guard_records.empty?
+    end
+
+    # Issue #1429 — this scope past code that may rebind a global or a constant: each one a guard narrowed reads
+    # the union of its narrowed type and the binding the guard narrowed, and no record is left. The union, not the
+    # pre-guard binding alone, because the code may leave the value as it was: `$stdout.is_a?(StringIO)`, then a
+    # helper, reads `IO | StringIO`, which keeps `$stdout.string` quiet as the guard intended.
+    def forget_guard_narrowings
+      return self if @guard_records.empty?
+
+      globals = @globals
+      constants = @constant_narrowings
+      @guard_records.each do |(kind, name), pre_guard|
+        if kind == :global
+          current = globals[name]
+          globals = globals.merge(name => Type::Combinator.union(pre_guard, current)) if current
+        else
+          current = constants[name]
+          constants = constants.merge(name => Type::Combinator.union(pre_guard, current)) if current
+        end
+      end
+      rebuild(globals: globals.frozen? ? globals : globals.freeze,
+              constant_narrowings: constants.frozen? ? constants : constants.freeze,
+              guard_records: EMPTY_GUARD_RECORDS)
+    end
+
+    # Issue #1362 (ADR-58 parity, ADR-117 Decision point 2) — used by the method-entry and top-level seeds to bind a
+    # global Ruby's own signatures declare to its declared type joined with the file's writes, and to record that the
+    # binding is still that seed. The declared members are real type information but not diagnostic fuel
+    # ({Analysis::CheckRules::DeclarationSourcedGuard}); a write or narrowing drops the mark ({#with_global}).
+    def seed_declaration_sourced_global(name, type)
+      rebuild(globals: @globals.merge(name.to_sym => type).freeze,
+              declaration_sourced: add_declaration_sourced(:global, name))
+    end
+
+    # Issue #1362 — a local written from a read of a marked global (`sep = $/`) carries ADR-58's `:local` mark, and
+    # this records the globals it may copy, so a consumer can compare against the file's writes to them
+    # ({#declaration_sourced_global_copies}). Applied after {#with_declaration_sourced_local}; the local's next
+    # rebinding drops both ({#bind_local}), and a join of two copies keeps both branches' globals.
+    def with_global_copy_marks(name, globals)
+      name = name.to_sym
+      added = globals.map { |global| [:global_copy, name, global.to_sym].freeze }
+                     .reject { |ref| @declaration_sourced.include?(ref) }
+      return self if added.empty?
+
+      rebuild(declaration_sourced: @declaration_sourced.dup.merge(added).freeze)
+    end
+
+    # Issue #1362 — this scope with the local `name`'s ADR-58 mark and copy record dropped and its binding kept: a
+    # retried pass that re-enters with a binding the accumulated one accepts, but from another source.
+    def without_local_declaration_marks(name)
+      dropped = drop_local_declaration_marks(name)
+      dropped.equal?(@declaration_sourced) ? self : rebuild(declaration_sourced: dropped)
+    end
+
+    # The globals the local `name` is a marked copy of ({#with_global_copy_marks}), empty for a local that copies
+    # no marked global.
+    def declaration_sourced_global_copies(name)
+      return EMPTY_GLOBAL_COPIES unless declaration_sourced?(:local, name)
+
+      name = name.to_sym
+      @declaration_sourced.filter_map { |ref| ref[2] if ref[0] == :global_copy && ref[1] == name }
+    end
+    EMPTY_GLOBAL_COPIES = [].freeze
+    private_constant :EMPTY_GLOBAL_COPIES
+
+    # Mark `nodes`, index `||=` sites, as ones whose slot an earlier run of a repeating block body may have
+    # filled ({EMPTY_REPEATED_OR_WRITES}).
+    def with_repeated_or_writes(nodes)
+      return self if nodes.all? { |node| @repeated_or_writes.key?(node) }
+
+      marked = @repeated_or_writes.dup
+      nodes.each { |node| marked[node] = true }
+      rebuild(repeated_or_writes: marked.freeze)
+    end
+
+    # True when {#with_repeated_or_writes} marked the index `||=` node `node` (by identity).
+    def repeated_or_write?(node)
+      return false if @repeated_or_writes.empty?
+
+      @repeated_or_writes.key?(node)
     end
 
     # Regex match-data globals (`$~`, `$&`, `$1..$9`, the pre/post-match and last-paren back-references). Narrowed
-    # on a successful-`=~` / `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`); any
-    # subsequent method call could run another match and rebind every one of them, so `eval_call` forgets the
-    # narrowed facts here. Always safe — only drops facts, so a subsequent read falls back to the default
-    # `String | nil`. Program-level `$GLOBAL = ...` seeds use other names and are untouched.
+    # on a successful-`=~` / `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`). They live in
+    # the method frame's special-variable slot, which the method's blocks and closures share (issue #1358), so a
+    # later call that may run a match in this frame — a match-capable call, a block that may match, a call once
+    # the frame has made a closure that may — rebinds every one of them, and `eval_call` forgets the narrowed
+    # facts here. Always safe — only drops facts, so a subsequent read falls back to the default `String | nil`.
+    # Program-level `$GLOBAL = ...` seeds use other names and are untouched.
     MATCH_DATA_GLOBALS = %i[$~ $& $` $' $+ $1 $2 $3 $4 $5 $6 $7 $8 $9].freeze
     private_constant :MATCH_DATA_GLOBALS
 
     def forget_match_globals
-      return self unless @globals.keys.any? { |k| MATCH_DATA_GLOBALS.include?(k) }
+      return self unless match_globals_bound?
 
       rebuild(globals: @globals.except(*MATCH_DATA_GLOBALS).freeze)
     end
 
+    # Issue #1361 — this scope with every bound match-data global rebound to `Dynamic[top]`, and an unbound one left
+    # unbound: the view a `define_method` / `define_singleton_method` body enters with
+    # ({Inference::FreshFrameBlocks.entry}). The body reads the defining frame's slot whenever the method is called,
+    # which the narrowing where it is written neither proves nor refutes, so it is neither narrowed nor flagged.
+    def untyped_match_globals
+      return self unless match_globals_bound?
+
+      untyped = Type::Combinator.untyped
+      rebound = MATCH_DATA_GLOBALS.each_with_object({}) { |name, acc| acc[name] = untyped if @globals.key?(name) }
+      rebuild(globals: @globals.merge(rebound).freeze)
+    end
+
+    # True when any match-data global holds a binding, which a match edge or {#untyped_match_globals} makes: the only
+    # state {#forget_match_globals} can drop, and so the gate on every scan that decides whether to.
+    def match_globals_bound?
+      !@globals.empty? && MATCH_DATA_GLOBALS.any? { |name| @globals.key?(name) }
+    end
+
+    # Issue #1359 — the last line read, `$_`, lives in the same frame slot as the match globals, and so on the same
+    # terms: a `gets`-family call, a write, or a block or closure of the frame that may run either rebinds it
+    # ({Inference::LastLine}). It is bound only where a condition on a reader narrows it, or where code writes it.
+    LAST_LINE = :$_
+    private_constant :LAST_LINE
+
+    def forget_last_line
+      return self unless last_line_bound?
+
+      rebuild(globals: @globals.except(LAST_LINE).freeze)
+    end
+
+    # The `$_` half of {#untyped_match_globals}: a bound `$_` rebound to `Dynamic[top]`, an unbound one left alone.
+    def untyped_last_line
+      return self unless last_line_bound?
+
+      rebuild(globals: @globals.merge(LAST_LINE => Type::Combinator.untyped).freeze)
+    end
+
+    # The gate on every scan that decides whether to forget `$_`, as {#match_globals_bound?} is for the match globals.
+    def last_line_bound?
+      !@globals.empty? && @globals.key?(LAST_LINE)
+    end
+
+    # Issue #1360 — the exception being rescued, `$!`, and its backtrace, `$@`. Ruby finds them through the nearest
+    # rescue frame of the running execution context, not through the method frame, so they are bound only inside a
+    # `rescue` clause or a rescue modifier's fallback and read their earlier binding again once it exits
+    # ({Inference::ErrorInfo}). `$?`, the status of the last child process, is thread-local, and is bound after a
+    # subprocess call ({Inference::LastStatus}).
+    ERROR_INFO_GLOBALS = %i[$! $@].freeze
+    LAST_STATUS_GLOBALS = %i[$?].freeze
+    private_constant :ERROR_INFO_GLOBALS, :LAST_STATUS_GLOBALS
+
+    # This scope with `$!` and `$@` unbound: the view of a body that runs outside the rescue clause it is written in.
+    def forget_error_info = forget_globals(ERROR_INFO_GLOBALS)
+
+    # This scope with a bound `$!` or `$@` rebound to `Dynamic[top]`, and an unbound one left unbound, as
+    # {#untyped_match_globals} gives a `define_method` body.
+    def untyped_error_info = untyped_globals(ERROR_INFO_GLOBALS)
+
+    # This scope with `$?` unbound: the view of a body that may run on another thread.
+    def forget_last_status = forget_globals(LAST_STATUS_GLOBALS)
+
+    # The `$?` half of {#untyped_error_info}.
+    def untyped_last_status = untyped_globals(LAST_STATUS_GLOBALS)
+
+    def forget_globals(names)
+      return self if @globals.empty? || names.none? { |name| @globals.key?(name) }
+
+      rebuild(globals: @globals.except(*names).freeze)
+    end
+
+    def untyped_globals(names)
+      return self if @globals.empty? || names.none? { |name| @globals.key?(name) }
+
+      untyped = Type::Combinator.untyped
+      rebound = names.each_with_object({}) { |name, acc| acc[name] = untyped if @globals.key?(name) }
+      rebuild(globals: @globals.merge(rebound).freeze)
+    end
+    private :forget_globals, :untyped_globals
+
+    # Issue #1358 — stamps the frame `body` runs in ({Inference::MatchRebinding::Frame}) on a method, class or
+    # file body's entry scope; a method passes its `parameters` too, whose defaults run in the same frame. Every
+    # scope derived from it, a block's included, runs in that frame.
+    def with_match_frame(body, parameters = nil)
+      rebuild(match_frame: Inference::MatchRebinding::Frame.new(body, parameters))
+    end
+
+    # True when this scope's frame makes a closure that may rebind its match globals whenever it is invoked
+    # ({Inference::MatchRebinding.matching_closure?}). False where no body stamped a frame.
+    def match_rebinding_closure?
+      !@match_frame.nil? && @match_frame.matching_closure?(self)
+    end
+
+    # True when this scope's frame makes a closure that may set its `$_` whenever it is invoked
+    # ({Inference::LastLine.closure?}). False where no body stamped a frame.
+    def last_line_closure?
+      !@match_frame.nil? && @match_frame.last_line_closure?(self)
+    end
+
     # Slice 7 phase 2 — class-level ivar accumulator. Keyed by the qualified class name (e.g. `"Rigor::Scope"`);
     # the value is a `Hash[Symbol, Type::t]` of every ivar that appears as a write target inside any def body of
     # that class. `StatementEvaluator#build_method_entry_scope` seeds the method body's `ivars` map from this
@@ -756,6 +1142,86 @@ module Rigor
       site
     end
 
+    # Issue #1097 — whether `class_name`'s own singleton `def method_name` has RUN by the time `call_node`
+    # executes. Such a def precedes every `extend` in the singleton ancestry, so once it exists it owns the
+    # call — but `sig { ... }` written BEFORE `def self.sig` in the same body still resolves through the
+    # already-extended module, because `def` takes effect at execution. The site table stores
+    # `"path:line"`: ordering applies only to calls executed eagerly in the same file's class body — a
+    # call inside a def body runs at invocation time, and a def in another file can never be ordered
+    # against the call site, so both conservatively count as shadowing. A nil `call_node`
+    # (position-less dispatch probes) does the same.
+    def singleton_def_shadows_call?(class_name, method_name, call_node)
+      def_shadows_call?(user_singleton_def_site_for(class_name, method_name), class_name, method_name,
+                        :singleton, call_node)
+    end
+
+    # The instance-side twin of {#singleton_def_shadows_call?}: whether `class_name`'s `def method_name`
+    # has run by call time — for `extend M` edges, where M's instance surface is what answers.
+    def instance_def_shadows_call?(class_name, method_name, call_node)
+      def_shadows_call?(user_def_site_for(class_name, method_name), class_name, method_name, :instance,
+                        call_node)
+    end
+
+    # Shared ordering half of the two `*_def_shadows_call?` predicates, over this file's
+    # `discovered_deferred_ranges` (issue #1097). `exists` — a recorded `"path:line"` site or the
+    # method-existence table — says a def of `method_name`/`kind` on `class_name` is known at all; a
+    # discovered def with no site (an `attr_*` sibling, a bundle seed that predates the table) counts
+    # through `discovered_method?`. The ranges then answer the timing questions, and can supply defs
+    # the site table missed (a `module_function`-installed `sig` never enters the singleton-def
+    # table). A foreign-file site cannot be ordered against the call — shadowing. A nil `call_node`
+    # (position-less dispatch probes) or a file the index never saw falls back to `exists`.
+    def def_shadows_call?(site, class_name, method_name, kind, call_node)
+      exists = !site.nil? || discovered_method?(class_name, method_name, kind)
+      return exists if call_node.nil?
+
+      path = source_path
+      return exists unless path
+
+      if site
+        site_path, = site.rpartition(":")
+        return true unless site_path == path
+      end
+
+      ranges = @discovery.discovered_deferred_ranges[path]
+      return exists if ranges.nil?
+
+      deferred_ranges_shadow_call?(ranges, method_name.to_sym, kind, class_name.to_s,
+                                   call_node.location, exists)
+    end
+    private :def_shadows_call?
+
+    # The range scan behind {#def_shadows_call?}. A call CONTAINED in any def / block / lambda /
+    # `END` range is deferred — it runs at invocation time — so it is shadowed iff a matching def is
+    # known (`exists`, or a row the site table missed). An EAGER call is shadowed iff the earliest
+    # same-name, same-kind (`:both` matches either), same-OWNER row starts before it: owner scoping
+    # keeps `class A`'s defs from ordering `class F`'s calls, and earliest-of keeps
+    # `def self.sig; sig {}; def self.sig` honest where the def-node table is later-wins. With no
+    # matching row the answer is `exists` — "a def exists but cannot be ordered" stays conservative,
+    # "no def at all" stays permissive.
+    def deferred_ranges_shadow_call?(ranges, method_name, kind, class_name, call_loc, exists)
+      contained = false
+      matching = false
+      earliest = nil
+      ranges.each do |(start, finish, name, def_kind, owner)|
+        contained ||= start <= call_loc.start_offset && call_loc.end_offset <= finish
+        next unless deferred_row_orders_call?(name, def_kind, owner, method_name, kind, class_name)
+
+        matching = true
+        earliest = start if earliest.nil? || start < earliest
+      end
+      return exists || matching if contained
+
+      earliest.nil? ? exists : earliest <= call_loc.start_offset
+    end
+    private :deferred_ranges_shadow_call?
+
+    # Whether a range row can order the call: same method name, same qualified owner, and a def kind
+    # that answers this predicate's side (`:both` — `module_function` — matches either).
+    def deferred_row_orders_call?(name, def_kind, owner, method_name, kind, class_name)
+      name == method_name && owner == class_name && (def_kind == kind || def_kind == :both)
+    end
+    private :deferred_row_orders_call?
+
     # ADR-24 slice 2 — per-class table mapping a fully qualified user-class name to its superclass name AS WRITTEN
     # at the `class Foo < Bar` declaration (`"Bar"`, possibly a qualified `"A::B"`). Populated by `ScopeIndexer` —
     # per-file plus the cross-file project pre-pass — and consumed by
@@ -792,15 +1258,46 @@ module Rigor
     end
 
     # ADR-24 slice 2 — per-class/module table mapping a fully qualified user class or module to the list of
-    # module names it `include`s / `prepend`s, AS WRITTEN at the mixin call. Populated by `ScopeIndexer` (per-file
+    # module names it `include`s / `prepend`s, in instance-ancestor SEARCH order: prepended modules first
+    # (Ruby inserts them ahead of the class itself), then included modules nearest-first — `include A;
+    # include B` searches B before A, while `include A, B` keeps `["A", "B"]` (each statement's argument
+    # list lands as one unit, ahead of the earlier statements'). Populated by `ScopeIndexer` (per-file
     # plus the cross-file pre-pass) and consumed by `ExpressionTyper#resolve_user_def_through_ancestors` so an
-    # implicit-self call resolves against an included module's `def`s, not just the superclass chain. As-written
-    # names are resolved to qualified classes at walk time.
+    # implicit-self call resolves against an included module's `def`s, not just the superclass chain.
+    # As-written names are resolved to qualified classes at walk time. Issue #1173 — the list was call
+    # order until then, a divergence from Ruby's later-include-wins the order-sensitive consumers (the
+    # BFS mixin step, the external-ancestor walk, override visibility) silently absorbed.
     def includes_of(class_name)
       record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
+    # Issue #1123 — the modules `class_name` `prepend`s, in instance-ancestor SEARCH order: the nearest
+    # prepend first, so `prepend A; prepend B` answers `["B", "A"]` and `prepend A, B` keeps `["A", "B"]`
+    # (each Ruby statement's argument list lands as one unit, ahead of the earlier statements'). Read by
+    # {#user_def_through_ancestors}'s prepend wedge — Ruby inserts a prepended module, and its own ancestry,
+    # IMMEDIATELY BEFORE the class that prepends it, so these names are searched ahead of the class's own
+    # `def`s. Empty for a class the project never prepends, which is the behaviour every class had before
+    # `prepend` was ordered at all.
+    #
+    # The same names ALSO appear in {#includes_of} — that table answers "which modules does this class
+    # carry", which is what the arity, visibility, reflection and constant-scope consumers ask, and a
+    # prepended module does contribute instance methods. This table adds the ORDER and the KIND; it never
+    # removes a name from the other one.
+    #
+    # The class dependency is recorded only on a HIT, as {#data_member_layout} does: the wedge asks this
+    # for every class the walk visits, so recording on a miss would give a caller file an ancestry edge on
+    # a class that prepends nothing — an edge where ADR-46 slice 4 keeps method-body reads at
+    # symbol granularity.
+    def prepends_of(class_name)
+      names = @discovery.discovered_prepends[class_name.to_s]
+      return EMPTY_MIXIN_NAMES if names.nil?
+
+      record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
+      names
+    end
+    private :prepends_of
+
     # Issue #898 — the module names `extend`ed onto `class_name`'s SINGLETON, as written, gathered up the
     # as-written superclass chain because a singleton class inherits its superclass's singleton class
     # (`class Base; extend Comparable; end; class Widget < Base; end` leaves `Widget.is_a?(Comparable)`
@@ -845,6 +1342,15 @@ module Rigor
     # `name_memo` is a CACHE, not semantics: the per-edge as-written-name resolutions, so a caller resolving
     # many methods against one class pays each ancestor edge once. Omit it and the walk is identical, just
     # uncached.
+    #
+    # Issue #1123 — a prepended module is searched through {#prepends_of} AHEAD of the class's own `def`s
+    # ({#prepend_wedge_names}), because Ruby inserts it, and its own ancestry, immediately before the class
+    # that prepends it: `class Base; def speak = "base"; end; Base.prepend(Loud)` answers `Loud#speak`, and
+    # the `super` in that body then reaches `Base#speak`. An included module still
+    # sits AFTER the class in this walk, but — since #1173 — `includes_of` feeds the mixin step in
+    # instance-ancestor search order, so `include A; include B` searches B first the way CRuby does. The
+    # wedge is searched at EVERY node, not just the entry class: a prepend on an ancestor (`class Sub <
+    # Base` where `Base` prepends a module) wins for the subclass too, exactly as Ruby dispatches it.
     def user_def_through_ancestors(class_name, method_name, name_memo: {})
       queue = [class_name.to_s]
       seen = {}
@@ -857,6 +1363,9 @@ module Rigor
         visited += 1
         return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
 
+        wedge_hit = search_prepend_wedge(current, method_name, name_memo, seen)
+        return wedge_hit if wedge_hit
+
         found = user_def_for(current, method_name)
         return [found, current] if found
 
@@ -865,6 +1374,63 @@ module Rigor
       [nil, nil]
     end
 
+    # Issue #1123 — the `[def_node, owner]` pair a class's prepend wedge answers `method_name` with, or nil
+    # when nothing in the wedge defines it and the walk should ask the class's own `def`s next.
+    #
+    # Every name the wedge takes is marked on `seen`, the SAME set the walk's breadth-first step uses: a
+    # prepended module also sits in `includes_of`, so the mixin step would otherwise re-ask a name the wedge
+    # already answered — and, more importantly, marking it there keeps a `prepend` graph that loops back on
+    # the walk (a prepended module reached again from somewhere else) from being expanded twice.
+    def search_prepend_wedge(class_name, method_name, name_memo, seen)
+      prepend_wedge_names(class_name, name_memo).each do |name|
+        next if seen[name]
+
+        seen[name] = true
+        found = user_def_for(name, method_name)
+        return [found, name] if found
+      end
+      nil
+    end
+
+    # Issue #1123 — the qualified names the instance MRO searches ahead of `class_name`'s own definitions,
+    # in the order it searches them: for each of `class_name`'s prepends, nearest first, that module's own
+    # prepend wedge, then the module itself, then its includes and superclass.
+    #
+    # A prepended module's own ancestry is part of the wedge because Ruby inserts the whole sub-chain with
+    # it — `module Loud; include Loud::Prefix; end` prepended into `Base` puts `Loud::Prefix` ahead of
+    # `Base`, so the wedge has to reach it. `seen` is shared across one wedge computation and guards a cyclic
+    # `prepend`/`include` graph (and the overlap with `includes_of`, which carries the prepend names too);
+    # the walk's own set is applied by {#search_prepend_wedge}, and each name is expanded at most once.
+    def prepend_wedge_names(class_name, name_memo, seen = {})
+      out = []
+      prepends_of(class_name).each do |raw|
+        resolved = resolve_ancestor_class_name(class_name, raw, name_memo)
+        next if resolved.nil? || seen[resolved]
+
+        seen[resolved] = true
+        out.concat(subchain_names(resolved, name_memo, seen))
+      end
+      out
+    end
+
+    # Issue #1123 — appends `node`'s own instance search order to `out`: its prepend wedge, the node
+    # itself, then its includes and superclass, each expanded the same way. Since #1173 the include
+    # half is `includes_of`'s search order — the ORDER inside a prepended module's own include list is
+    # not re-derived here, only read.
+    def subchain_names(node, name_memo, seen)
+      out = prepend_wedge_names(node, name_memo, seen)
+      out << node
+      (includes_of(node) + [superclass_of(node)].compact).each do |raw|
+        resolved = resolve_ancestor_class_name(node, raw, name_memo)
+        next if resolved.nil? || seen[resolved]
+
+        seen[resolved] = true
+        out.concat(subchain_names(resolved, name_memo, seen))
+      end
+      out
+    end
+    private :search_prepend_wedge, :prepend_wedge_names, :subchain_names
+
     # Issue #731 — the singleton-side twin of {#user_def_through_ancestors}: resolves `method_name` against
     # `class_name`'s own `def self.` / `class << self` bodies, then up the SUPERCLASS chain. Returns
     # `[def_node, owner]`, or `[nil, nil]`.
@@ -897,41 +1463,57 @@ module Rigor
 
     # Issue #633 — the ancestors a project class reaches that the project itself does NOT declare: the
     # `< StandardError` / `< Array` superclasses and the `include Comparable` mixins the two walks above
-    # deliberately drop, gathered breadth-first over the project ancestry so an inherited edge counts too.
+    # deliberately drop, gathered depth-first over the project ancestry (an included module's own
+    # sub-chain precedes the includer's superclass edge) so an inherited edge counts too — and, since
+    # #1173, so the groups arrive in instance-ancestor search order for the caller that adopts the
+    # FIRST answering one.
     #
     # Each entry is the CANDIDATE LIST for one as-written name ({#ancestor_name_candidates}: the nesting
     # spellings first, the bare name last), not a resolved class — resolving it means asking the RBS
     # environment, which this frozen-index walk does not read. The caller takes the first candidate its own
     # oracle knows and ignores the rest, the same "most-qualified first" order the project-side resolution
     # uses.
-    def external_ancestor_name_candidates(class_name, name_memo: {})
+    # Issue #527 slice 1 — `mixins: false` follows the SUPERCLASS chain only. Ruby reaches an included
+    # module's methods too, so the default answers the whole ancestry; a consumer resolving one KIND of
+    # inheritance edge at a time (the dispatch arm lands `< Hash` before `include Enumerable`) narrows
+    # it, the same way {#singleton_def_through_ancestors} narrows {#enqueue_ancestors}.
+    def external_ancestor_name_candidates(class_name, name_memo: {}, mixins: true)
       groups = []
-      queue = [class_name.to_s]
-      seen = {}
-      visited = 0
-      until queue.empty?
-        current = queue.shift
-        next if current.nil? || seen[current]
-
-        seen[current] = true
-        visited += 1
-        break if visited > ANCESTOR_WALK_LIMIT
-
-        collect_external_ancestors(current, queue, groups, name_memo)
-      end
+      collect_external_ancestors(class_name.to_s, groups, name_memo, mixins, {}, [0])
       groups
     end
 
     # One node of {#external_ancestor_name_candidates}: the project-declared ancestors continue the walk,
     # everything else is reported as a candidate list.
-    def collect_external_ancestors(current, queue, groups, name_memo)
-      raw_names = includes_of(current).dup
+    #
+    # Issue #1173 — the walk is depth-first pre-order, not breadth-first: a resolved ancestor's own
+    # edges are followed BEFORE the next sibling edge, because Ruby inserts an included module's whole
+    # sub-chain ahead of the includer's superclass (`class C < Hash; include M` where `M` itself
+    # includes `Widen` chains `C → M → Widen → Hash`; BFS would report `Hash` ahead of `Widen`). Each
+    # node's edges still go includes-then-superclass, and `includes_of` is already search order, so the
+    # emitted groups arrive in MRO order — which the #1173 include arm depends on when two ancestors
+    # both declare the name.
+    def collect_external_ancestors(current, groups, name_memo, mixins, seen, visited)
+      return if current.nil? || seen[current]
+
+      seen[current] = true
+      visited[0] += 1
+      if visited[0] > ANCESTOR_WALK_LIMIT
+        # Issue #527 — the give-up is a budget event, not an answer. Consumers read the groups as
+        # "the ancestors this class reaches", so a truncated list must be visible in `--stats`
+        # alongside the other walks' exhaustions rather than silently short. Hit once: every node
+        # visited past the limit returns here too, and only the first should count.
+        Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT) if visited[0] == ANCESTOR_WALK_LIMIT + 1
+        return
+      end
+
+      raw_names = mixins ? includes_of(current).dup : []
       raw_super = superclass_of(current)
       raw_names << raw_super if raw_super
       raw_names.each do |raw|
         resolved = resolve_ancestor_class_name(current, raw, name_memo)
         if resolved
-          queue.push(resolved)
+          collect_external_ancestors(resolved, groups, name_memo, mixins, seen, visited)
         else
           groups << ancestor_name_candidates(current, raw)
         end
@@ -945,6 +1527,12 @@ module Rigor
     EMPTY_HEADER_NESTING = [].freeze
     private_constant :EMPTY_HEADER_NESTING
 
+    # The answer for a class that prepends nothing — the common case, so the wedge does not allocate a
+    # fresh empty list per visited node. Shared and frozen, and never handed to a caller that could
+    # mutate it ({#prepends_of} is private to this walk).
+    EMPTY_MIXIN_NAMES = [].freeze
+    private_constant :EMPTY_MIXIN_NAMES
+
     def ancestor_walk_gave_up
       Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
       [nil, nil]
@@ -1062,9 +1650,70 @@ module Rigor
 
       recorded = @discovery.discovered_header_nestings[subclass_qualified.to_s]
       entries = recorded ? recorded_header_nesting(recorded, raw) : peeled_header_nesting(subclass_qualified)
+      if !entries.empty? && DiscoveryIndex.ambiguous_header_nesting?(entries)
+        return ambiguous_ancestor_candidates(entries, raw_ancestor)
+      end
+
+      entries.map { |entry| "#{entry}::#{raw_ancestor}" } << raw_ancestor.to_s
+    end
+
+    # Issue #986 — the candidate list for a raw name two declaration sites of ONE class wrote in different
+    # crefs (the compact-header rename pass landed both on this key). Each alternative chain gets its own
+    # candidate list, in the order this walk would have used for that site alone.
+    #
+    # When two of them resolve to two DIFFERENT project classes there is no candidate list to return: at
+    # runtime both `include`s run, and which of the two same-named modules ends up nearer in the MRO is the
+    # load order of the two files, which this walk cannot know. Answering with either is a WRONG ANCESTOR,
+    # and a wrong ancestor is a false-positive source rather than a missed one — two same-named modules can
+    # declare the same method at different arities, and `call.wrong-arity` then fires on a correct program.
+    # The empty list declines instead: the name resolves to no project class, the receiver's methods stay
+    # `Dynamic`, and every rule reading this walk goes quiet.
+    #
+    # Where the alternatives AGREE, or only one of them resolves at all, there is nothing to adjudicate: the
+    # answer is the union of their chains, most-qualified first — the same list a class whose sites needed
+    # no rename gets — so an unambiguous collision is unchanged, and an EXTERNAL ancestor keeps the full
+    # candidate list `#external_ancestor_name_candidates` hands the gem / RBS probe.
+    def ambiguous_ancestor_candidates(alternatives, raw_ancestor)
+      return [] if ambiguous_ancestor_resolutions_of(alternatives, raw_ancestor).size > 1
+
+      entries = alternatives.reduce([], :|).sort_by { |entry| [-entry.split("::").size, entry] }
       entries.map { |entry| "#{entry}::#{raw_ancestor}" } << raw_ancestor.to_s
     end
 
+    def ambiguous_ancestor_resolutions_of(alternatives, raw_ancestor)
+      alternatives.filter_map do |chain|
+        (chain.map { |entry| "#{entry}::#{raw_ancestor}" } << raw_ancestor.to_s)
+          .find { |candidate| known_user_class?(candidate) }
+      end.uniq
+    end
+    private :ambiguous_ancestor_candidates, :ambiguous_ancestor_resolutions_of
+
+    # Issue #986 — the several project classes an ancestor name resolves to when the compact-header rename
+    # collision left it ambiguous, and `EMPTY_HEADER_NESTING` for every other name. {#ancestor_name_candidates}
+    # declines such a name because no ONE class is its answer; a caller that also knows which METHOD it is
+    # looking up can do better than that decline, and a rule that reports on a method must, because the
+    # decline otherwise silences it for the whole receiver — its own `def`s and its unambiguous ancestors
+    # included.
+    #
+    # Both of these classes are ancestors at runtime: both `include`s run, and only their MRO ORDER is the
+    # load order this walk cannot see. So a method only one of them declares is answered by that one
+    # whatever the order, and only a method they BOTH declare is unanswerable.
+    # `Analysis::CheckRules::SourceArity` reads this for exactly that: it takes both as mixin levels and
+    # declines on the disagreement its own envelope join already knows how to spot.
+    def ambiguous_ancestor_resolutions(subclass_qualified, raw_ancestor)
+      raw = raw_ancestor.to_s
+      return EMPTY_HEADER_NESTING if raw.start_with?("::")
+
+      recorded = @discovery.discovered_header_nestings[subclass_qualified.to_s]
+      return EMPTY_HEADER_NESTING if recorded.nil?
+
+      entries = recorded_header_nesting(recorded, raw)
+      return EMPTY_HEADER_NESTING if entries.empty? || !DiscoveryIndex.ambiguous_header_nesting?(entries)
+
+      resolved = ambiguous_ancestor_resolutions_of(entries, raw_ancestor)
+      resolved.size > 1 ? resolved : EMPTY_HEADER_NESTING
+    end
+
     # Issue #728 — the chain of the declaration site that WROTE `raw`, which is the cref Ruby resolves that
     # one name in. A class's sites need not agree: `class Foo < Base` at the top level and a rooted
     # `class ::Foo; include Helper; end` inside `module Outer` are two sites of `Foo`, and the union of
@@ -1152,6 +1801,17 @@ module Rigor
       sites.each { |site| Analysis::DependencyRecorder.read_site(site) }
     end
 
+    # Issue #992 — one class's `discovered_parameter_envelopes` bucket (`{[kind, method_name] => envelope}` plus
+    # the class-wide marks), or an empty Hash. Records the ADR-46 class edge first: a verdict read off the
+    # bucket depends on every file that declares the class, and a `memoize :f` added to one of them moves it.
+    def parameter_envelopes_of(class_name)
+      record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
+      @discovery.discovered_parameter_envelopes[class_name.to_s] || EMPTY_PARAMETER_ENVELOPES
+    end
+
+    EMPTY_PARAMETER_ENVELOPES = {}.freeze
+    private_constant :EMPTY_PARAMETER_ENVELOPES
+
     # v0.1.2 — per-class table mapping `method_name (Symbol) → :public | :private | :protected`. Populated by
     # `ScopeIndexer` for every `def` it sees inside a class body, with the visibility taken from the surrounding
     # `private` / `protected` / `public` modifier state plus any post-hoc `private :name, ...` named-argument
@@ -1272,10 +1932,37 @@ module Rigor
       joined_locals = join_bindings(locals, other.locals)
       joined_ivars = join_bindings(ivars, other.ivars)
       joined_cvars = join_bindings(cvars, other.cvars)
-      joined_globals = join_bindings(globals, other.globals)
+      joined_globals = unbind_split_last_line(join_bindings(globals, other.globals), other)
       build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
     end
 
+    # Issue #1429 — a join keeps a guard record while the joined scope still narrows its name: a global both arms
+    # bind, a constant both arms narrow (one an arm does not narrow reads its resolved type after the join, so its
+    # narrowing is gone). An arm without a record contributes nothing to the restore target, whose union with the
+    # joined binding {#forget_guard_narrowings} takes, so it still covers that arm's binding.
+    def join_guard_records(other, joined_globals, joined_constants)
+      mine = @guard_records
+      theirs = other.guard_records
+      return EMPTY_GUARD_RECORDS if mine.empty? && theirs.empty?
+
+      merged = mine.merge(theirs) { |_key, left, right| Type::Combinator.union(left, right) }
+      kept = merged.select do |(kind, name), _|
+        kind == :global ? joined_globals.key?(name) : joined_constants.key?(name)
+      end
+      kept.empty? ? EMPTY_GUARD_RECORDS : kept.freeze
+    end
+    private :join_guard_records
+
+    # Issue #1359 — arms that bind `$_` apart join with it unbound rather than to their union. The arms of a reader
+    # condition bind `String` and `nil`, and `String?` after `if gets … end` would report correct code that proves the
+    # line some other way (`ok = gets ? true : false; return unless ok; line = $_; line.chomp`).
+    def unbind_split_last_line(joined, other)
+      return joined unless joined.key?(LAST_LINE) && @globals[LAST_LINE] != other.globals[LAST_LINE]
+
+      joined.except(LAST_LINE).freeze
+    end
+    private :unbind_split_last_line
+
     def ==(other)
       other.is_a?(Scope) &&
         environment.equal?(other.environment) &&
@@ -1287,8 +1974,7 @@ module Rigor
         @globals == other.globals &&
         @indexed_narrowings == other.indexed_narrowings &&
         @method_chain_narrowings == other.method_chain_narrowings &&
-        @declaration_sourced == other.declaration_sourced &&
-        @published_constant_sourced == other.published_constant_sourced
+        same_marks?(other)
     end
     alias eql? ==
 
@@ -1298,6 +1984,18 @@ module Rigor
 
     private
 
+    # The marks {#==} compares: ADR-58's, issue #667's and the repeated `||=` sites, and #1429's guard state.
+    def same_marks?(other)
+      @declaration_sourced == other.declaration_sourced &&
+        @published_constant_sourced == other.published_constant_sourced &&
+        @repeated_or_writes == other.repeated_or_writes &&
+        same_guard_state?(other)
+    end
+
+    def same_guard_state?(other)
+      @constant_narrowings == other.constant_narrowings && @guard_records == other.guard_records
+    end
+
     def rebuild(
       locals: @locals, fact_store: @fact_store, self_type: @self_type,
       ivars: @ivars, cvars: @cvars, globals: @globals,
@@ -1309,6 +2007,7 @@ module Rigor
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
       opaque_block_self: @opaque_block_self,
+      singleton_class_body: @singleton_class_body,
       lexical_nesting: @lexical_nesting,
       dynamic_origins: @dynamic_origins,
       local_origins: @local_origins,
@@ -1317,7 +2016,11 @@ module Rigor
       plugin_typed_calls: @plugin_typed_calls,
       optimistic_origins: @optimistic_origins,
       optimistic_locals: @optimistic_locals,
-      optimistic_ivars: @optimistic_ivars
+      optimistic_ivars: @optimistic_ivars,
+      repeated_or_writes: @repeated_or_writes,
+      match_frame: @match_frame,
+      constant_narrowings: @constant_narrowings,
+      guard_records: @guard_records
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -1331,6 +2034,7 @@ module Rigor
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
         opaque_block_self: opaque_block_self,
+        singleton_class_body: singleton_class_body,
         lexical_nesting: lexical_nesting,
         dynamic_origins: dynamic_origins,
         local_origins: local_origins,
@@ -1339,7 +2043,11 @@ module Rigor
         plugin_typed_calls: plugin_typed_calls,
         optimistic_origins: optimistic_origins,
         optimistic_locals: optimistic_locals,
-        optimistic_ivars: optimistic_ivars
+        optimistic_ivars: optimistic_ivars,
+        repeated_or_writes: repeated_or_writes,
+        match_frame: match_frame,
+        constant_narrowings: constant_narrowings,
+        guard_records: guard_records
       )
     end
 
@@ -1359,7 +2067,7 @@ module Rigor
 
     def build_joined_scope(joined_locals, joined_ivars, joined_cvars, joined_globals, other)
       self.class.new(
-        environment: environment,
+        environment: @environment,
         locals: joined_locals.freeze,
         fact_store: fact_store.join(other.fact_store),
         self_type: self_type == other.self_type ? self_type : nil,
@@ -1379,7 +2087,7 @@ module Rigor
         # end; m == :x` must not warn because one arm's copy is invisible to the reader's author. ADR-67
         # WD6b's `:inferred_param` taint takes the same direction for the same reason.
         published_constant_sourced: join_published_constant_sourced(other),
-        source_path: source_path,
+        source_path: @source_path,
         # Issue #589 — the fold-safe set MUST survive a merge. It was simply absent from this constructor
         # call, so it fell back to the empty default and every `if` / `while` in a method silently revoked
         # struct member folding for the whole body after it: `s = S.new("r"); while c; i += 1; end; s.raw`
@@ -1405,6 +2113,10 @@ module Rigor
         # block entry by `entering_opaque_block` and inherited through `rebuild`), so both arms usually carry
         # the same value and the `||` is that value.
         opaque_block_self: @opaque_block_self || other.opaque_block_self,
+        # Issue #963 — a body property like the two above, so both arms of an in-body merge carry the identical
+        # value and the `||` is that value. `||` is also the safe direction on its own terms: keeping the mark
+        # declines the `define_method` narrowing, which is the pre-#963 answer.
+        singleton_class_body: @singleton_class_body || other.singleton_class_body,
         # Issue #652 — the recorded `Module.nesting`, stamped once at body entry and threaded by `rebuild`
         # exactly as the fold-safe set is. A join is a control-flow merge INSIDE one body, so both arms
         # always carry the identical chain; taking this scope's is that chain. Dropping it would silently
@@ -1416,11 +2128,38 @@ module Rigor
         void_origins: @void_origins,
         plugin_typed_calls: @plugin_typed_calls,
         optimistic_origins: @optimistic_origins,
-        optimistic_locals: join_origins(@optimistic_locals, other.optimistic_locals),
-        optimistic_ivars: join_origins(@optimistic_ivars, other.optimistic_ivars)
+        optimistic_locals: join_optimistic_marks(@optimistic_locals, other.optimistic_locals),
+        optimistic_ivars: join_optimistic_marks(@optimistic_ivars, other.optimistic_ivars),
+        # UNION, the published-constant mark's direction: the mark only withholds the memoizing `||=`
+        # reading, so keeping a site either arm holds is the wider answer.
+        repeated_or_writes: join_repeated_or_writes(other),
+        # Issue #1358 — the frame the body runs in, stamped at its entry like the nesting above, so both arms
+        # of a merge inside one body carry the same one; `||` keeps it should either arm lack it, since dropping
+        # it only loses the frame's resets.
+        match_frame: @match_frame || other.match_frame,
+        # Issue #1429 — the guard narrowings of globals and constants and their pre-guard records.
+        **join_guard_narrowings(other, joined_globals)
       )
     end
 
+    def join_guard_narrowings(other, joined_globals)
+      joined_constants = join_constant_narrowings(other)
+      { constant_narrowings: joined_constants,
+        guard_records: join_guard_records(other, joined_globals, joined_constants) }
+    end
+
+    # Issue #1429 — a constant reference both arms narrow reads the union; one only an arm narrows reads its resolved
+    # type again, which the other arm reads too.
+    def join_constant_narrowings(other)
+      mine = @constant_narrowings
+      theirs = other.constant_narrowings
+      return mine if mine.equal?(theirs)
+      return EMPTY_CONSTANT_NARROWINGS if mine.empty? || theirs.empty?
+
+      joined = join_bindings(mine, theirs)
+      joined.empty? ? EMPTY_CONSTANT_NARROWINGS : joined
+    end
+
     # Issue #589 — intersect the struct fold-safe grants. Zero-alloc on the common path, where both arms
     # carry the same frozen set the body scan stamped.
     # A `nil` on EITHER side yields no grants. The field is keyword-defaulted to `EMPTY_FOLD_SAFE` and
@@ -1448,6 +2187,17 @@ module Rigor
       theirs.merge(mine).freeze
     end
 
+    # Issue #286's mark tables join as {#join_origins} does, except for the miss answer a mark may carry (issue
+    # #1302): a name both arms mark keeps its answer only when the arms agree on it. A name one arm marks keeps
+    # that arm's answer, since a miss runs through that arm only.
+    def join_optimistic_marks(mine, theirs)
+      return mine if mine.equal?(theirs) || theirs.empty?
+      return theirs if mine.empty?
+
+      theirs.merge(mine) { |_name, their_mark, my_mark| Inference::OptimisticOrigin.join_bound_marks(my_mark, their_mark) }
+            .freeze
+    end
+
     # ADR-82 WD1 — rebinding drops any propagated origin for the name (the new value's provenance is set
     # afterward by `with_local_origin` when it is a `Dynamic` with a recorded cause). Zero-alloc when the name
     # carries no origin — the overwhelming common case, so this stays off the with_local hot-path budget.
@@ -1464,6 +2214,11 @@ module Rigor
     #   value on the branch where it derives from an inferred parameter, so if EITHER branch taints it, a
     #   downstream use could observe the lower-bound value and firing on it is an FP (`x = param else x = 5;
     #   x.foo`). Intersecting would lose the taint at the merge and re-surface the false positive.
+    #
+    # Issue #1362 — a local both branches mark as copies of global seeds keeps its mark with the union of the globals
+    # the two record, so a consumer compares against the writes to every one of them. A `(:local, name)` mark only
+    # one branch backs with a record is dropped with it: that branch copies a global and the other an ivar, so no
+    # comparison answers for the merge and it is flow-live.
     def join_declaration_sourced(other)
       mine = @declaration_sourced
       theirs = other.declaration_sourced
@@ -1476,12 +2231,33 @@ module Rigor
         if mine.empty? || theirs.empty?
           EMPTY_DECLARATION_SOURCED
         else
-          mine.select { |ref| ref[0] != :inferred_param && theirs.include?(ref) }
+          join_copy_records(mine.select { |ref| ref[0] != :inferred_param && theirs.include?(ref) }, mine, theirs)
         end
       merged = inferred.merge(intersected)
       merged.empty? ? EMPTY_DECLARATION_SOURCED : merged.freeze
     end
 
+    # `kept`, the refs both branches carry, with the `[:global_copy, …]` records rejoined ({#join_declaration_sourced}).
+    def join_copy_records(kept, mine, theirs)
+      mine_copies = global_copy_records(mine)
+      theirs_copies = global_copy_records(theirs)
+      return kept if mine_copies.empty? && theirs_copies.empty?
+
+      joined = kept.reject { |ref| ref[0] == :global_copy }
+      (mine_copies.keys | theirs_copies.keys).each do |name|
+        if mine_copies.key?(name) && theirs_copies.key?(name) && joined.include?([:local, name])
+          joined.concat(mine_copies[name] | theirs_copies[name])
+        else
+          joined.delete([:local, name])
+        end
+      end
+      joined
+    end
+
+    def global_copy_records(refs)
+      refs.each_with_object({}) { |ref, acc| (acc[ref[1]] ||= []) << ref if ref[0] == :global_copy }
+    end
+
     def indexed_key(receiver_kind, receiver_name, key)
       IndexedKey.new(
         receiver_kind: receiver_kind.to_sym,
@@ -1538,6 +2314,15 @@ module Rigor
       (mine | theirs).freeze
     end
 
+    def join_repeated_or_writes(other)
+      mine = @repeated_or_writes
+      theirs = other.repeated_or_writes
+      return mine if mine.equal?(theirs) || theirs.empty?
+      return theirs if mine.empty?
+
+      mine.merge(theirs).freeze
+    end
+
     def add_declaration_sourced(kind, name)
       ref = [kind.to_sym, name.to_sym]
       return @declaration_sourced if @declaration_sourced.include?(ref)
@@ -1556,6 +2341,31 @@ module Rigor
       dropped.freeze
     end
 
+    # The `(:local, name)` mark and, when it was there, the `[:global_copy, name, global]` records that only ever sit
+    # beside it ({#with_global_copy_marks}).
+    def drop_local_declaration_marks(name)
+      dropped = drop_declaration_sourced_for(:local, name)
+      return dropped if dropped.equal?(@declaration_sourced)
+
+      name = name.to_sym
+      return dropped unless dropped.any? { |ref| ref[0] == :global_copy && ref[1] == name }
+
+      dropped.dup.delete_if { |ref| ref[0] == :global_copy && ref[1] == name }.freeze
+    end
+
+    def add_guard_record(key, pre_guard)
+      return @guard_records if @guard_records.key?(key)
+
+      @guard_records.merge(key => pre_guard).freeze
+    end
+
+    def drop_guard_record(kind, name)
+      return @guard_records if @guard_records.empty?
+
+      key = [kind, name]
+      @guard_records.key?(key) ? @guard_records.except(key).freeze : @guard_records
+    end
+
     def drop_chain_narrowings_for(receiver_kind, receiver_name)
       return @method_chain_narrowings if @method_chain_narrowings.empty?