rigortype 0.3.9 → 0.4.1

data/lib/rigor/scope.rb

@@ -3,10 +3,13 @@
 require_relative "type"
 require_relative "environment"
 require_relative "scope/discovery_index"
+require_relative "scope/resolution_chain"
+require_relative "inference/definer_resolution"
 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 +26,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, :bot_guard_classes
 
     # 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 +52,26 @@ 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). The one table that tells a `prepend` from an
+    # `include`: {ResolutionChain} reads it to put a prepended module ahead of the class.
+    # The plugin-facing view: each class's prepends once, nearest first. The discovery index itself keeps every
+    # statement (a repeated `prepend` is a no-op in Ruby, the first statement winning), and the resolution chain
+    # reads that raw list.
+    def discovered_prepends = @discovery.discovered_prepends.transform_values { |names| names.uniq.freeze }.freeze
     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 +79,30 @@ 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, and a qualified one is sliced after its last `::` rather than split into
+    # an Array of every segment ([#1502](https://github.com/rigortype/rigor/issues/1502)). The two agree on every
+    # name a parsed constant path spells. Only the `Foo::` Prism recovers from a syntax error differs, and no
+    # file with a parse error is typed.
+    def shadowing_constant_names(name)
+      separator = name.rindex("::")
+      segment = separator ? name[(separator + 2)..] : 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 +233,38 @@ 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.
+    # Issue #1446 — a class guard's narrowing of an instance variable is recorded too, keyed `[:ivar, :@name]`
+    # ({#with_guarded_ivar}), since that code may reach `self` and rebind it; a write drops it ({#without_ivar_guard}).
+    EMPTY_GUARD_RECORDS = {}.freeze
+    # Issue #1446 — the classes a class guard narrowed a receiver to where the narrowing left it `bot`, keyed like
+    # {EMPTY_GUARD_RECORDS} with `[:local, :name]` too: `return unless @cb.is_a?(Proc)` binds `@cb` to `bot` when the
+    # guard is disjoint from its binding, but the value that passes it is a `Proc` (or a subclass of one), and a call
+    # on it dispatches on that class. `Inference::GuardRebinding` reads the class a `bot` receiver runs its methods
+    # on from here ({#bot_guard_classes_for}); a `bot` no class guard produced has no entry. A write or another
+    # narrowing of the name drops its entry, and a join keeps one only both arms hold.
+    EMPTY_BOT_GUARD_CLASSES = {}.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, :EMPTY_BOT_GUARD_CLASSES
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -230,7 +305,7 @@ module Rigor
       @plugin_typed_calls.key?(node)
     end
 
-    def initialize(
+    def initialize( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- one keyword and assignment per field
       environment:, locals:,
       fact_store: Analysis::FactStore.empty,
       self_type: nil,
@@ -245,6 +320,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 +329,12 @@ 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,
+      bot_guard_classes: EMPTY_BOT_GUARD_CLASSES
     )
       @environment = environment
       @locals = locals
@@ -270,6 +351,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 +361,11 @@ 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
+      @bot_guard_classes = bot_guard_classes
       freeze
     end
 
@@ -291,19 +378,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 +429,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 +454,16 @@ 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),
+              bot_guard_classes: drop_bot_guard_class(:local, name))
     end
+    private :bind_local
 
     def with_fact(fact)
       rebuild(fact_store: fact_store.with_fact(fact))
@@ -420,6 +527,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)
@@ -450,6 +578,11 @@ module Rigor
     end
 
     def with_ivar(name, type)
+      bind_ivar(name, type, @guard_records)
+    end
+
+    # The one body behind {#with_ivar} and {#with_guarded_ivar}, which differ only in the guard records they leave.
+    def bind_ivar(name, type, guard_records)
       new_indexed_narrowings = drop_indexed_narrowings_for(:ivar, name)
       new_chain_narrowings = drop_chain_narrowings_for(:ivar, name)
       # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live: drop any declaration-sourced mark so
@@ -461,8 +594,11 @@ module Rigor
               declaration_sourced: drop_declaration_sourced_for(:ivar, name),
               published_constant_sourced: drop_published_constant_sourced_for(:ivar, name),
               ivar_origins: drop_origin(@ivar_origins, name),
-              optimistic_ivars: drop_origin(@optimistic_ivars, name))
+              optimistic_ivars: drop_origin(@optimistic_ivars, name),
+              guard_records: guard_records,
+              bot_guard_classes: drop_bot_guard_class(:ivar, name))
     end
+    private :bind_ivar
 
     # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only provenance is the class-ivar index.
     # Unlike `with_ivar` this binds the type AND records the declaration-sourced mark in one transition.
@@ -486,6 +622,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 +655,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 +700,324 @@ 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),
+                        bot_guard_classes: drop_bot_guard_class(: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,
+              bot_guard_classes: drop_bot_guard_class(:global, name))
+    end
+
+    # Issue #1446 — binds the instance variable `name` to `type` on a class guard's edge, recording `pre_guard` as
+    # {#with_guarded_global} does. The truthiness, `nil?`, `&.` and `respond_to?` guards narrow an instance variable
+    # through {#with_ivar} and record nothing.
+    def with_guarded_ivar(name, type, pre_guard)
+      name = name.to_sym
+      bind_ivar(name, type, add_guard_record([:ivar, name].freeze, pre_guard))
+    end
+
+    # Issue #1446 — this scope with no guard record for the instance variable `name`: what a write to it leaves.
+    # {#with_ivar} keeps the record, since a narrowing binds through it too.
+    def without_ivar_guard(name)
+      records = drop_guard_record(:ivar, name.to_sym)
+      records.equal?(@guard_records) ? self : rebuild(guard_records: records)
+    end
+
+    # Issue #1446 — true when a class guard's narrowing of the instance variable `name` is live.
+    def guard_narrowed_ivar?(name)
+      !@guard_records.empty? && @guard_records.key?([:ivar, name.to_sym])
+    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),
+              bot_guard_classes: drop_bot_guard_class(:constant, key))
+    end
+
+    # Issue #1446 — this scope with `class_names` recorded as the classes a class guard narrowed the receiver `[kind,
+    # name]` to, where the guard left it `bot` ({EMPTY_BOT_GUARD_CLASSES}). Call it after the narrowing, which drops
+    # any earlier entry.
+    def with_bot_guard_classes(kind, name, class_names)
+      key = [kind, kind == :constant ? name : name.to_sym].freeze
+      rebuild(bot_guard_classes: @bot_guard_classes.merge(key => class_names.dup.freeze).freeze)
+    end
+
+    # Issue #1446 — the classes a class guard narrowed the `bot` receiver `[kind, name]` to, or nil.
+    def bot_guard_classes_for(kind, name)
+      return nil if @bot_guard_classes.empty?
+
+      @bot_guard_classes[[kind, name]]
+    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) }
+      classes = @bot_guard_classes.except(*keys.map { |key| [:constant, key] }).freeze
+      rebuild(constant_narrowings: @constant_narrowings.except(*keys).freeze, guard_records: records.freeze,
+              bot_guard_classes: classes)
+    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,
+              bot_guard_classes: drop_bot_guard_class(:constant, key))
+    end
+
+    # True when a guard's narrowing of a global, constant or instance variable 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.
+    #
+    # Issue #1446 — an instance variable a class guard narrowed is restored the same way.
+    def forget_guard_narrowings
+      return self if @guard_records.empty?
+
+      tables = { global: @globals, constant: @constant_narrowings, ivar: @ivars }
+      @guard_records.each do |(kind, name), pre_guard|
+        table = tables.fetch(kind)
+        current = table[name]
+        tables[kind] = table.merge(name => Type::Combinator.union(pre_guard, current)) if current
+      end
+      globals, constants, ivars = tables.values_at(:global, :constant, :ivar).map { |t| t.frozen? ? t : t.freeze }
+      rebuild(globals: globals, constant_narrowings: constants, ivars: ivars, 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
@@ -612,6 +1064,18 @@ module Rigor
       @self_type.nil?
     end
 
+    # ADR-119 WD1 — the RAW slot of the def tables for `class_name` and `method_name`: the instance side by default,
+    # the singleton side for `kind: :singleton`. The slot is a live `Prism::DefNode` or a {Inference::DefHandle}
+    # (ADR-85 WD3), returned as stored: no dependency recording and no handle resolution. ADR-119 C1d/C2 decide how
+    # a contested slot answers here. Callers that need a node go through {#user_def_for} or {#singleton_def_for}.
+    # The `same_slot` census reads of this slot stay justified: certainty reaches them through the declaration
+    # signature the producer fingerprints (C1d-a), not through this accessor.
+    def def_node_slot(class_name, method_name, kind = :instance)
+      table = kind == :singleton ? discovered_singleton_def_nodes : discovered_def_nodes
+      per_class = table[class_name]
+      per_class && per_class[method_name]
+    end
+
     # v0.0.2 #5 — per-class table mapping `method_name (Symbol) → Prism::DefNode`. Populated by `ScopeIndexer`
     # alongside `discovered_methods` for instance-side defs only (singleton-side and `define_method`-introduced
     # methods do not contribute a static body the engine can re-type). Consumed by `ExpressionTyper` to do
@@ -699,12 +1163,15 @@ module Rigor
       same_file_top_level_def?(method_name) ? node : nil
     end
 
+    # ADR-119 WD1 errata, deliberately unchanged: this compares the recorded site's FILE with the call's file, and
+    # which file a def sits in does not depend on whether it executes. The `<toplevel>` slots are contested
+    # truthfully (ADR-119 C1d-a) but unread until C2 makes the top-level reader decline on them.
     def same_file_top_level_def?(method_name)
       key = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
       site = discovered_def_sources.dig(key, method_name.to_sym)
       return true if site.nil? || @source_path.nil?
 
-      File.expand_path(site.sub(/:\d+\z/, "")) == File.expand_path(@source_path)
+      File.absolute_path(site.sub(/:\d+\z/, "")) == File.absolute_path(@source_path)
     end
     private :same_file_top_level_def?
 
@@ -756,6 +1223,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,10 +1339,15 @@ 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] || []
@@ -829,118 +1381,130 @@ module Rigor
       names.uniq
     end
 
-    # ADR-24 slice 2 — the user-side ancestor walk: resolves `method_name` against `class_name`'s own `def`s,
-    # then breadth-first through its included / prepended modules (mixins first, as Ruby orders them) and its
-    # superclass chain. Returns `[def_node, owner]`, or `[nil, nil]` when nothing in the project defines it.
-    # RBS-known / third-party ancestors resolve to no discovered class and end that branch.
+    # ADR-24, amended for #1567 / #1568 / #1570 / #1571 — every reader below answers in Ruby's linearised
+    # ancestor order, read from {ResolutionChain} (an internal class: `Scope`'s own surface is the plugin API
+    # `spec/rigor/public_api_drift_spec.rb` pins, and the chain is not part of it). None walks `includes_of` /
+    # `superclass_of` / the extends table itself; `spec/rigor/scope/ancestry_walker_detection_spec.rb` fails on
+    # a method that does. Each keeps its signature and its return type exactly: only WHICH definer it answers
+    # moved. `name_memo:` is still accepted and no longer needed — the chain memoises name resolution itself.
+    UNUSED_NAME_MEMO = {}.freeze
+    private_constant :UNUSED_NAME_MEMO
     #
-    # It lives HERE, not in a consumer, because it reads nothing but this scope's frozen discovery index
-    # (`user_def_for` / `includes_of` / `superclass_of` / the `discovered_*` tables) — the same property that
-    # lets `ExpressionTyper` memoise its results run-wide. Two callers depend on that single answer:
-    # `ExpressionTyper#compute_user_def_with_owner`, which wraps it in the run-scoped memo for the dispatch hot
-    # path, and {Inference::MethodDispatcher::StructMaterialization}, whose `.with` guard must see a `with`
-    # contributed by an included module. They forked once — the guard resolved own-class-only while the
-    # dispatcher walked ancestors — and answered differently about the same receiver expression (#598 review).
+    # Every reader below asks {ResolutionChain#settle} whether its chain answer stands, and where it does not
+    # answers what the walk it replaced answered ({ResolutionChain::MasterOrder}) — the tables cannot say which
+    # world ran, and a disagreement is no reason to answer anything new.
+
+    # ADR-24 slice 2 — the user-side method lookup: the first project `def` of `method_name` along
+    # `class_name`'s instance chain, as `[def_node, owner]`, or `[nil, nil]` when nothing the project declares
+    # defines it. An external ancestor is passed over, as before: a caller asking "does the project define
+    # this" must not read an RBS module's declaration as absence (#1572 is the typing read that will stop
+    # there).
     #
-    # `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.
-    def user_def_through_ancestors(class_name, method_name, name_memo: {})
-      queue = [class_name.to_s]
-      seen = {}
-      visited = 0
-      until queue.empty?
-        current = queue.shift
-        next if current.nil? || seen[current]
+    # It lives HERE, not in a consumer, because it reads nothing but this scope's frozen discovery index — the
+    # property that lets `ExpressionTyper` memoise its results run-wide. `ExpressionTyper#compute_user_def_with_owner`
+    # wraps it in that memo for the dispatch hot path, and {Inference::MethodDispatcher::StructMaterialization}'s
+    # `.with` guard reads the same answer (#598 review).
+    #
+    # #1567 — the walk was breadth-first until the chain replaced it: `class C < Base; include A` with `A`
+    # including `M` answered `Base#foo` where Ruby calls `M#foo`. The prepend wedge #1123 added (a prepended
+    # module searched ahead of the class's own `def`s) and the include search order #1173 fixed are both
+    # positions on the chain now, at every class on it.
+    def user_def_through_ancestors(class_name, method_name, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :instance, :methods)
+      found = first_user_def(chain, method_name)
+      owner = found&.last
+      if chain.settle(self, owner, owner: owner) { |retro| first_user_def(retro, method_name)&.last } == :master
+        found = master_user_def(class_name.to_s, method_name)
+      end
+      return found if found
 
-        seen[current] = true
-        visited += 1
-        return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+      chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
+    end
 
-        found = user_def_for(current, method_name)
-        return [found, current] if found
+    def first_user_def(chain, method_name)
+      chain.search(self) do |entry|
+        next if entry.external?
 
-        enqueue_ancestors(current, queue, name_memo)
+        node = user_def_for(entry.name, method_name)
+        [node, entry.name] if node
       end
-      [nil, nil]
     end
 
-    # 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]`.
-    #
-    # Superclasses only, and that is the whole shape of class-method inheritance in Ruby: a subclass
-    # inherits its parent's class methods, while an `include`d module contributes INSTANCE methods and its
-    # own `def self.x` is not callable on the includer. `extend M` needs no walk either — `ScopeIndexer`
-    # folds an extend into the extender's own singleton entries before the table is frozen — so the one
-    # edge this misses is a module's singleton surface reached through some other route, which nothing
-    # resolves today.
-    def singleton_def_through_ancestors(class_name, method_name, name_memo: {})
-      queue = [class_name.to_s]
-      seen = {}
-      visited = 0
-      until queue.empty?
-        current = queue.shift
-        next if current.nil? || seen[current]
+    def master_user_def(class_name, method_name)
+      names = ResolutionChain::MasterOrder.definer_sequence(self, class_name)
+      names.each { |name| record_class_dependency(name) } if Analysis::DependencyRecorder.active?
+      names.each do |name|
+        node = user_def_for(name, method_name)
+        return [node, name] if node
+      end
+      nil
+    end
+    private :first_user_def, :master_user_def
+
+    # Issue #731 — the singleton-side twin of {#user_def_through_ancestors}: the first `def self.` /
+    # `class << self` body of `method_name` along `class_name`'s singleton chain, as `[def_node, owner]`, or
+    # `[nil, nil]` — each class object's own table, then the modules it extends in Ruby's order, then the
+    # superclass's. `ScopeIndexer` folds an extended module's own `def`s into the extender's table, so those
+    # answer at the extender; a module the extended one includes is its own entry (#1567's singleton shape:
+    # `class C < Base; extend A` with `A` including `M` is `M#foo`, not `Base.foo`). Where the chain does
+    # not stand, the answer is the class objects' alone, as the superclass-only walk this replaced gave.
+    def singleton_def_through_ancestors(class_name, method_name, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :singleton, :methods)
+      found = first_singleton_def(chain, method_name)
+      owner = found&.last
+      if chain.settle(self, owner, owner: owner) { |retro| first_singleton_def(retro, method_name)&.last } == :master
+        found = first_singleton_def(chain, method_name, :singleton)
+      end
+      return found if found
 
-        seen[current] = true
-        visited += 1
-        return ancestor_walk_gave_up if visited > ANCESTOR_WALK_LIMIT
+      chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
+    end
 
-        found = singleton_def_for(current, method_name)
-        return [found, current] if found
+    def first_singleton_def(chain, method_name, side = nil)
+      chain.search(self, side: side) do |entry|
+        next if entry.external?
 
-        enqueue_ancestors(current, queue, name_memo, mixins: false)
+        name = entry.name
+        node = entry.side == :singleton ? singleton_def_for(name, method_name) : user_def_for(name, method_name)
+        [node, entry.name] if node
       end
-      [nil, nil]
     end
+    private :first_singleton_def
 
     # 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.
+    # `< StandardError` / `< Array` superclasses and the `include Comparable` mixins, as the CANDIDATE LIST for
+    # each as-written name ({#ancestor_name_candidates}: the nesting spellings first, the bare name last), in
+    # Ruby's order along the instance chain — the order the caller that adopts the FIRST answering one (#1173)
+    # depends on. Resolving a candidate means asking the RBS environment, which this frozen-index read does
+    # not do; the caller takes the first candidate its own oracle knows. Where the chain does not stand, the
+    # groups are the depth-first ones the walk this replaced emitted.
     #
-    # 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: {})
-      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)
+    # Issue #527 slice 1 — `mixins: false` answers the superclass edge only: a consumer resolving one KIND of
+    # inheritance edge at a time (the dispatch arm lands `< Hash` before `include Enumerable`) narrows it, and
+    # records only the superclass chain it read.
+    def external_ancestor_name_candidates(class_name, name_memo: UNUSED_NAME_MEMO, mixins: true) # rubocop:disable Lint/UnusedMethodArgument
+      chain = ResolutionChain.for(self, class_name.to_s, :instance, :methods)
+      groups = external_groups(chain, mixins)
+      if chain.settle(self, groups) { |retro| external_groups(retro, mixins) } == :master
+        groups = ResolutionChain::MasterOrder.external_groups(self, class_name.to_s, mixins)
+      end
+      if Analysis::DependencyRecorder.active?
+        mixins ? chain.record(self) : chain.level_classes.each { |name| record_class_dependency(name) if name }
       end
+      # Issue #527 — the cut is a budget event, not an answer: consumers read the groups as "the ancestors
+      # this class reaches", so a short list must be visible in `--stats` beside the other walks' exhaustions.
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT) if chain.truncated?
       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
-      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)
-        else
-          groups << ancestor_name_candidates(current, raw)
-        end
-      end
+    def external_groups(chain, mixins)
+      chain.entries.filter_map { |entry| entry.candidates if entry.external? && (mixins || entry.superclass_edge) }
     end
-    private :collect_external_ancestors
+    private :external_groups
 
-    # The BFS node cap; a hierarchy past it gives up rather than walking unboundedly (ADR-41 WD4).
-    ANCESTOR_WALK_LIMIT = 100
+    # The budget {ResolutionChain::LIMIT} enforces; a hierarchy past it gives up rather than reading an answer
+    # off a cut chain (ADR-41 WD4).
+    ANCESTOR_WALK_LIMIT = ResolutionChain::LIMIT
 
     EMPTY_HEADER_NESTING = [].freeze
     private_constant :EMPTY_HEADER_NESTING
@@ -949,13 +1513,13 @@ module Rigor
       Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
       [nil, nil]
     end
+    private :ancestor_walk_gave_up
 
-    # Issue #723 — the same ancestor walk as {#user_def_through_ancestors}, asked of the DISCOVERY table
-    # rather than the def-node table: does the project define `method_name` on `class_name` or on any
-    # ancestor the project itself declares? The two tables are not interchangeable —
-    # `discovered_methods` also carries `define_method`, `attr_*` and the whole singleton side, none of
-    # which contributes a `Prism::DefNode` — and the suppression probe shared by the `call.*` check rules
-    # needs the broader one.
+    # Issue #723 — the question {#user_def_through_ancestors} asks, asked of the DISCOVERY table rather than
+    # the def-node table: does the project define `method_name` on `class_name` or on any ancestor the project
+    # itself declares? The two tables are not interchangeable — `discovered_methods` also carries
+    # `define_method`, `attr_*` and the whole singleton side, none of which contributes a `Prism::DefNode` —
+    # and the suppression probe shared by the `call.*` check rules needs the broader one.
     #
     # Why it must walk at all: `Analysis::CheckRules#source_declared_method?` asked `discovered_method?`,
     # which is keyed on the receiver's OWN name, while the typer resolves the same call through this
@@ -963,72 +1527,47 @@ module Rigor
     # `call.undefined-method` on a method `dump_type` resolved on the same line of the same run — writing
     # MORE RBS made the run worse, the incentive #653 removed for plugin-typed calls.
     #
-    # `kind: :singleton` follows the superclass chain ONLY: a class method is inherited by a subclass, but
-    # an `include`d module contributes instance methods and its own `def self.x` is not callable on the
-    # includer. `extend M` is not lost to that narrowing — `Inference::ScopeIndexer` folds an extend into
-    # the extender's own singleton entries before this table is frozen.
-    def discovered_method_through_ancestors?(class_name, method_name, kind, name_memo: {})
+    # `kind: :singleton` reads the singleton chain: the class objects' own methods (an extended module's are
+    # folded into its extender's) and the instance methods of the modules they extend and those modules'
+    # includes. Existence is a union, so the chain's two worlds, which hold the same modules, agree on it.
+    def discovered_method_through_ancestors?(class_name, method_name, kind, name_memo: UNUSED_NAME_MEMO) # rubocop:disable Lint/UnusedMethodArgument
       return false if class_name.nil?
 
-      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
-        # Budget exhaustion is uncertainty, not absence: answering "not declared" here would hand a
-        # `call.undefined-method` a fired verdict it has no evidence for. Suppress and record the hit.
-        if visited > ANCESTOR_WALK_LIMIT
-          Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
-          return true
-        end
-
-        return true if discovered_method?(current, method_name, kind)
+      chain = ResolutionChain.for(self, class_name.to_s, kind == :singleton ? :singleton : :instance, :methods)
+      found = chain.search(self) do |entry|
+        next false if entry.external?
 
-        enqueue_ancestors(current, queue, name_memo, mixins: kind != :singleton)
-      end
-      false
-    end
-
-    # Pushes `current`'s direct ancestors onto the BFS queue: included / prepended modules first (Ruby places
-    # mixins nearer than the superclass), then the superclass. Each as-written name is resolved against the
-    # nesting `current`'s declaration header is written in ({#ancestor_name_candidates}); names that resolve
-    # to no project class/module are dropped. `mixins: false` walks the superclass chain alone, for the
-    # singleton-side question where an `include` contributes nothing.
-    def enqueue_ancestors(current, queue, name_memo, mixins: true)
-      if mixins
-        includes_of(current).each do |raw|
-          resolved = resolve_ancestor_class_name(current, raw, name_memo)
-          queue.push(resolved) if resolved
-        end
+        discovered_method?(entry.name, method_name, entry.side == :singleton ? :singleton : kind_for(kind))
       end
-      raw_super = superclass_of(current)
-      return if raw_super.nil?
+      return true if found
+      # Budget exhaustion is uncertainty, not absence: answering "not declared" here would hand a
+      # `call.undefined-method` a fired verdict it has no evidence for. Suppress and record the hit.
+      return false unless chain.truncated?
 
-      resolved_super = resolve_ancestor_class_name(current, raw_super, name_memo)
-      queue.push(resolved_super) if resolved_super
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+      true
     end
 
-    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) to a project-discovered class,
-    # following Ruby's `Module.nesting` constant lookup from the subclass's declaration HEADER, innermost
-    # first, then bare. nil when no candidate names a discovered user class.
-    def resolve_ancestor_class_name(subclass_qualified, raw_ancestor, name_memo)
-      by_subclass = (name_memo[subclass_qualified] ||= {})
-      return by_subclass[raw_ancestor] if by_subclass.key?(raw_ancestor)
+    # A module entry on the singleton chain answers with its INSTANCE methods; on the instance chain, the
+    # caller's kind stands.
+    def kind_for(kind) = kind == :singleton ? :instance : kind
+    private :kind_for
 
-      by_subclass[raw_ancestor] = compute_ancestor_class_name(subclass_qualified, raw_ancestor)
+    # Pushes `current`'s direct ancestors onto a breadth-first queue: included / prepended modules first, then
+    # the superclass, each resolved against the nesting `current`'s declaration header is written in; names
+    # that resolve to no project class/module are dropped. `mixins: false` gives the superclass alone. No
+    # reader in the engine walks this way any more (they read {ResolutionChain}); it stays for the plugin
+    # surface, with the ADR-46 class edge the walk it served always filed.
+    def enqueue_ancestors(current, queue, name_memo, mixins: true) # rubocop:disable Lint/UnusedMethodArgument
+      record_class_dependency(current) if Analysis::DependencyRecorder.active?
+      queue.concat(ResolutionChain.direct_ancestors(self, current.to_s, mixins))
     end
-    private :ancestor_walk_gave_up, :resolve_ancestor_class_name
 
     # Issue #682 — the candidate names an ancestor spelled `raw_ancestor` can denote in `subclass_qualified`,
     # in Ruby's lookup order, most-qualified first and the bare name last. The single owner of the question:
-    # three walks resolved a superclass / include name apiece ({#enqueue_ancestors} for method lookup,
-    # `Reflection.resolve_ancestor_name` for the constant ladder's ancestor rung, and
-    # `Analysis::CheckRules`' override-visibility rule), and each derived the order by PEELING the
-    # subclass's qualified name one `::` segment at a time.
+    # three walks resolved a superclass / include name apiece (the method walk, the constant ladder's
+    # ancestor rung, and `Analysis::CheckRules`' override-visibility rule — all three now {ResolutionChain}),
+    # and each derived the order by PEELING the subclass's qualified name one `::` segment at a time.
     #
     # That peel is the NESTED spelling's answer, given to both spellings. Ruby evaluates a superclass
     # expression before entering the body, so the cref that governs it is the one the declaration's HEADER
@@ -1040,9 +1579,9 @@ module Rigor
     # The header nesting is a property of the DECLARATION, not of the reader, so it is read from the
     # discovery table `Inference::ScopeIndexer` records it in rather than from this scope's own
     # `#lexical_nesting`. Answering off the reader's chain would be wrong past the first hop of the ancestor
-    # BFS (the chain describes the reader's class, not the ancestor being resolved) and would silently
-    # corrupt the run-scoped ancestor memos in `Inference::ExpressionTyper#class_graph_buckets` and
-    # `Reflection.ancestor_constant_scopes`, both of which key on the class name alone because this walk is
+    # chain (the chain describes the reader's class, not the ancestor being resolved) and would silently
+    # corrupt the {ResolutionChain} memo and the ones layered on it (`Inference::ExpressionTyper#class_graph_buckets`,
+    # `Reflection.ancestor_constant_scopes`), all of which key on the class name alone because this walk is
     # a pure function of the frozen discovery tables.
     #
     # The peel survives as the FALLBACK, for a class no declaration walk recorded — a scope seeded without
@@ -1062,9 +1601,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
@@ -1088,10 +1688,6 @@ module Rigor
     end
     private :peeled_header_nesting
 
-    def compute_ancestor_class_name(subclass_qualified, raw_ancestor)
-      ancestor_name_candidates(subclass_qualified, raw_ancestor).find { |c| known_user_class?(c) }
-    end
-
     # Issue #723 — `discovered_methods` is in the list because the other three miss a class whose only
     # project-side content is CLASS methods: `class Base; def self.build = :built; end` records no instance
     # def node, no superclass and no include, so the ancestor-name resolver did not recognise `Base` as a
@@ -1106,13 +1702,13 @@ module Rigor
     # narrower predicate (`discovered_classes` alone) would read a project class as having left the project
     # and attribute its root name to a same-named locked gem — a WRONG provenance label, which is the one
     # direction ADR-82 forbids.
-    private :ancestor_walk_gave_up, :compute_ancestor_class_name
 
     # Records, for a resolved cross-class ancestry read, every file that declares `class_name` (its declaration /
-    # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated only by
-    # the cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}) and only when
-    # dependency recording is active. No-op when the class is not a project class (core / stdlib / gem names
-    # never appear in the source map). Gated by the caller on the recorder being active.
+    # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated by the
+    # cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}); a scope built
+    # without one holds none, and the read then files nothing. No-op when the class is not a project class
+    # (core / stdlib / gem names never appear in the source map). Gated by the caller on the recorder being
+    # active.
     def record_class_dependency(class_name)
       sites = @discovery.discovered_class_sources[class_name.to_s]
       return if sites.nil?
@@ -1132,8 +1728,7 @@ module Rigor
     # so a bare referent is re-checked when the class appears or disappears and at no other time. A file edge
     # would have re-checked every bare referent of every class the file declares on any edit to it.
     def record_class_existence(class_name)
-      segment = class_name.to_s.delete_prefix("::").split("::").last
-      Analysis::DependencyRecorder.read_name(:class, segment) if segment
+      Analysis::DependencyRecorder.read_last_segment(:class, class_name.to_s)
     end
 
     # Issue #644 — the positive ADR-46 edge for a cross-file VALUE constant. `Reflection.constant_type_at`
@@ -1152,6 +1747,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 +1878,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), and an instance variable both arms bind (#1446). 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.
+    # `joined` maps each record kind to the joined scope's table of that kind.
+    def join_guard_records(other, joined)
+      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 { |(kind, name), _| joined.fetch(kind).key?(name) }
+      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 +1920,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 +1930,19 @@ 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 &&
+        @bot_guard_classes == other.bot_guard_classes
+    end
+
     def rebuild(
       locals: @locals, fact_store: @fact_store, self_type: @self_type,
       ivars: @ivars, cvars: @cvars, globals: @globals,
@@ -1309,6 +1954,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 +1963,12 @@ 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,
+      bot_guard_classes: @bot_guard_classes
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -1331,6 +1982,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 +1991,12 @@ 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,
+        bot_guard_classes: bot_guard_classes
       )
     end
 
@@ -1359,7 +2016,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 +2036,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 +2062,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 +2077,55 @@ 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, and of instance
+        # variables (#1446).
+        **join_guard_narrowings(other, joined_globals, joined_ivars)
       )
     end
 
+    def join_guard_narrowings(other, joined_globals, joined_ivars)
+      joined_constants = join_constant_narrowings(other)
+      joined = { global: joined_globals, ivar: joined_ivars, constant: joined_constants }
+      { constant_narrowings: joined_constants, guard_records: join_guard_records(other, joined),
+        bot_guard_classes: join_bot_guard_classes(other) }
+    end
+
+    # Issue #1446 — an entry both arms hold, with the classes of either: the joined receiver reads `bot` only where
+    # both arms do. One only an arm holds is dropped, so a call on the joined `bot` reads as on an unknown one.
+    def join_bot_guard_classes(other)
+      mine = @bot_guard_classes
+      theirs = other.bot_guard_classes
+      return mine if mine.equal?(theirs)
+      return EMPTY_BOT_GUARD_CLASSES if mine.empty? || theirs.empty?
+
+      joined = mine.each_with_object({}) do |(key, names), acc|
+        other_names = theirs[key]
+        acc[key] = (names | other_names).freeze if other_names
+      end
+      joined.empty? ? EMPTY_BOT_GUARD_CLASSES : joined.freeze
+    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 +2153,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 +2180,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 +2197,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 +2280,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 +2307,38 @@ 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_bot_guard_class(kind, name)
+      return @bot_guard_classes if @bot_guard_classes.empty?
+
+      key = [kind, kind == :constant ? name : name.to_sym]
+      @bot_guard_classes.key?(key) ? @bot_guard_classes.except(key).freeze : @bot_guard_classes
+    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?