rigortype 0.4.6 → 0.4.8

data/lib/rigor/scope.rb

@@ -3,6 +3,8 @@
 require_relative "type"
 require_relative "environment"
 require_relative "scope/discovery_index"
+require_relative "typing_state"
+require_relative "memo_audit"
 require_relative "scope/resolution_chain"
 require_relative "inference/definer_resolution"
 require_relative "inference/in_effect_refinements"
@@ -13,6 +15,10 @@ require_relative "inference/flow_tracer"
 require_relative "inference/optimistic_origin"
 require_relative "inference/statement_evaluator"
 require_relative "inference/def_node_resolver"
+# Issue #2608 — read by `MutationWidening` at a remover call, which only an analysis makes; loaded with the engine
+# so the engine-free value layer that requires `MutationWidening` stays as small as it was.
+require_relative "inference/remover_narrowing"
+require_relative "inference/alias_mutation_floor"
 
 module Rigor
   # Immutable analyzer scope: holds local-variable bindings and a reference to the surrounding Environment. State
@@ -30,7 +36,7 @@ module Rigor
                 :opaque_block_self, :block_self_unknown, :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, :construction_facts,
                 :repeated_or_writes, :match_frame,
                 :constant_narrowings, :guard_records, :bot_guard_classes, :declared_refinements
 
@@ -89,7 +95,7 @@ module Rigor
     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.
+    # Issue #644 — `{qualified constant name => declaring files}`; seeded only on an ADR-46 recording run.
     def constant_sources = @discovery.constant_sources
     def published_constant_names = @discovery.published_constant_names
     def local_constant_names = @discovery.local_constant_names
@@ -153,7 +159,13 @@ module Rigor
     # renames the foreign declaration. `published_constant_alias_names` holds the last segments of exactly
     # those aliases, and matching on the last segment over-answers in the WITHHOLDING direction, which is the
     # safe one.
+    #
+    # Issue #3199 — the answer turns on another file's publication of the last segment, so the question records
+    # the ADR-46 `constant:<segment>` name edge itself, whatever it answers. The guard asks it about spellings no
+    # typing step reads (a `defined?(B::X)` probe, a callee body the one hop scans), and an edge left to the read
+    # would let an `--incremental` run keep a verdict the moved publication no longer earns.
     def published_constant?(name)
+      Analysis::DependencyRecorder.read_last_segment(:constant, name) if Analysis::DependencyRecorder.active?
       names = @discovery.published_constant_names
       return true if published_constant_alias?(name)
       return false if names.empty?
@@ -202,9 +214,9 @@ module Rigor
     #   `:const` allowed; its entry marks presence only.
     IndexedKey = Data.define(:receiver_kind, :receiver_name, :key)
 
-    # Narrowing key for a no-arg / no-block method-call chain `receiver.method_name` (a "single-hop" chain per A1
-    # from the ROADMAP § Future cycles slice). The value of the map at this key is the narrowed type the next read
-    # of the same chain MUST observe — typically the post-`is_a?(C)` narrowing established on a predicate edge.
+    # Narrowing key for a no-arg / no-block method-call chain `receiver.method_name` (a "single-hop" chain).
+    # The value of the map at this key is the narrowed type the next read of the same chain MUST observe —
+    # typically the post-`is_a?(C)` narrowing established on a predicate edge.
     #
     # - `receiver_kind` ∈ `{:local, :ivar}` — the analyzer only tracks chains rooted at a local or instance
     #   variable today (Law-of-Demeter-style single-hop).
@@ -232,7 +244,7 @@ module Rigor
     # through flow transitions and ignored by `==` / `hash`.
     EMPTY_FOLD_SAFE = Set.new.freeze
     # ADR-82 WD1 — provenance propagation across the receiver-node lookup. `local_origins` / `ivar_origins`
-    # map a `name` (Symbol) to the {Inference::DynamicOrigin} cause of the `Dynamic` value currently bound to
+    # map a `name` to the {Inference::DynamicOrigin} cause of the `Dynamic` value currently bound to
     # it, so a downstream dispatch whose receiver is a bare `x` / `@x` read resolves to why that value is
     # dynamic (the cause was recorded on the *assignment*'s rhs node, which the receiver-read node is not).
     # Advisory metadata like {#dynamic_origins}: ignored by `==` / `hash` (never varies a flow decision) and
@@ -283,6 +295,32 @@ module Rigor
                      :EMPTY_PUBLISHED_CONSTANT_IVARS, :EMPTY_REPEATED_OR_WRITES,
                      :EMPTY_CONSTANT_NARROWINGS, :EMPTY_GUARD_RECORDS, :EMPTY_BOT_GUARD_CLASSES
 
+    # ADR-129 WD1 — the four advisory tables are bound Tables: each is an identity Hash one file's scopes share by
+    # reference (a fresh body scope may start its own; {#with_isolated_side_tables} copies them), so a journal record
+    # names the store beside the node. Every entry read and write goes through the methods below, which log it while a
+    # capture is open; handing a store to a new Scope is not an entry read.
+    DYNAMIC_ORIGINS = TypingState.table(
+      :dynamic_origins,
+      bound: true,
+      reason: "node => DynamicOrigin cause; typing records it and reads it back for receiver provenance"
+    )
+    VOID_ORIGINS = TypingState.table(
+      :void_origins, bound: true, reason: "node => VoidOrigin site; recorded by dispatch, read by the value-use rule"
+    )
+    PLUGIN_TYPED_CALLS = TypingState.table(
+      :plugin_typed_calls, bound: true, reason: "node => true where a plugin's dynamic_return answered the call"
+    )
+    OPTIMISTIC_ORIGINS = TypingState.table(
+      :optimistic_origins,
+      bound: true,
+      reason: "node => OptimisticOrigin cause; typing records it and reads it back to keep a value nil-free"
+    )
+    private_constant :DYNAMIC_ORIGINS, :VOID_ORIGINS, :PLUGIN_TYPED_CALLS, :OPTIMISTIC_ORIGINS
+    TypingState.store_field(self, :@dynamic_origins, DYNAMIC_ORIGINS)
+    TypingState.store_field(self, :@void_origins, VOID_ORIGINS)
+    TypingState.store_field(self, :@plugin_typed_calls, PLUGIN_TYPED_CALLS)
+    TypingState.store_field(self, :@optimistic_origins, OPTIMISTIC_ORIGINS)
+
     class << self
       def empty(environment: Environment.default, source_path: nil)
         new(environment: environment, locals: {}.freeze,
@@ -291,16 +329,33 @@ module Rigor
     end
 
     def record_dynamic_origin(node, cause)
+      TypingState.current.log_bound_write(DYNAMIC_ORIGINS, @dynamic_origins, node, cause)
       @dynamic_origins[node] = cause
       self
     end
 
+    # The {Inference::DynamicOrigin} cause recorded at `node`, or nil (ADR-129: a logged Table read).
+    def dynamic_origin(node)
+      log_advisory_read(DYNAMIC_ORIGINS, @dynamic_origins, node)
+    end
+
+    # The {Inference::VoidOrigin} recorded at `node`, or nil (ADR-129: a logged Table read).
+    def void_origin(node)
+      log_advisory_read(VOID_ORIGINS, @void_origins, node)
+    end
+
+    # The {Inference::OptimisticOrigin} cause recorded at `node`, or nil (ADR-129: a logged Table read).
+    def optimistic_origin(node)
+      log_advisory_read(OPTIMISTIC_ORIGINS, @optimistic_origins, node)
+    end
+
     # ADR-100 WD3 — records that the value introduced at `node` (a call node) is a `top` recovered from an
     # author-declared `-> void` return, keyed by the origin site (`origin`, an {Inference::VoidOrigin}). The
     # value-context check rule `static.value-use.void` consumes this table. Mirrors {#record_dynamic_origin}
     # exactly: identity-keyed advisory metadata, mutated in place on the shared table (threaded by reference
     # through `#join` / `#rebuild`), excluded from `==` / `hash`, so it never forks a flow-dedup or cache key.
     def record_void_origin(node, origin)
+      TypingState.current.log_bound_write(VOID_ORIGINS, @void_origins, node, origin)
       @void_origins[node] = origin
       self
     end
@@ -313,15 +368,22 @@ module Rigor
     # identity-keyed advisory metadata on a table threaded by reference through `#join` / `#rebuild`,
     # excluded from `==` / `hash`, so it never forks a flow-dedup or cache key.
     def record_plugin_typed_call(node)
+      TypingState.current.log_bound_write(PLUGIN_TYPED_CALLS, @plugin_typed_calls, node, true)
       @plugin_typed_calls[node] = true
       self
     end
 
     # Issue #653 — whether a plugin answered the return type for `node` on this run.
     def plugin_typed_call?(node)
-      @plugin_typed_calls.key?(node)
+      !log_advisory_read(PLUGIN_TYPED_CALLS, @plugin_typed_calls, node).nil?
     end
 
+    # Every keyword past the 31st (`opaque_block_self`, `block_self_unknown`) must keep a literal default. A keyword at
+    # that index with a non-literal default makes a call that omits it allocate CRuby's unspecified-keywords record
+    # during argument setup, and on CRuby 4.0 a GC started by that allocation frees the values already moved into the
+    # keyword locals (ruby/ruby Bug #22500, issue #2850): `Scope.new` stored a freed `match_frame`.
+    # `spec/rigor/keyword_gc_safety_spec.rb` holds every method under `lib/` and `plugins/*/lib` to this. See the note
+    # at {#rebuild} before adding a field.
     def initialize( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- one keyword and assignment per field
       environment:, locals:,
       fact_store: Analysis::FactStore.empty,
@@ -336,8 +398,6 @@ module Rigor
       published_constant_sourced: EMPTY_PUBLISHED_CONSTANT_SOURCED,
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
-      opaque_block_self: false,
-      block_self_unknown: false,
       singleton_class_body: false,
       lexical_nesting: nil,
       dynamic_origins: {}.compare_by_identity,
@@ -348,12 +408,16 @@ module Rigor
       optimistic_origins: {}.compare_by_identity,
       optimistic_locals: EMPTY_ORIGINS,
       optimistic_ivars: EMPTY_ORIGINS,
+      construction_facts: 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,
-      declared_refinements: Inference::InEffectRefinements::EMPTY
+      declared_refinements: Inference::InEffectRefinements::EMPTY,
+      # Literal defaults only from here on; see the note above.
+      opaque_block_self: false,
+      block_self_unknown: false
     )
       @environment = environment
       @locals = locals
@@ -381,6 +445,7 @@ module Rigor
       @optimistic_origins = optimistic_origins
       @optimistic_locals = optimistic_locals
       @optimistic_ivars = optimistic_ivars
+      @construction_facts = construction_facts
       @repeated_or_writes = repeated_or_writes
       @match_frame = match_frame
       @constant_narrowings = constant_narrowings
@@ -395,10 +460,20 @@ module Rigor
     # nil-freeness is a property of its class. Mirrors {#dynamic_origins} / {#void_origins}: advisory
     # metadata, ignored by `==` / `hash`, and never varying a flow decision on its own.
     def record_optimistic_origin(node, cause)
+      TypingState.current.log_bound_write(OPTIMISTIC_ORIGINS, @optimistic_origins, node, cause)
       @optimistic_origins[node] = cause
       self
     end
 
+    # The entry of the advisory table `store` (the bound Table `slot`'s) at `node`, or nil, logged as a Table read: a
+    # key the store does not hold logs {TypingState::ABSENT}, so a recorded nil and a miss differ.
+    def log_advisory_read(slot, store, node)
+      value = store.fetch(node, TypingState::ABSENT)
+      TypingState.current.log_bound_read(slot, store, node, value)
+      TypingState::ABSENT.equal?(value) ? nil : value
+    end
+    private :log_advisory_read
+
     # Issue #1703 — this scope with private copies of the identity-keyed side tables (dynamic, void and optimistic
     # origins, plugin-typed calls), so a second walk from it — the `key?`-guarded re-walk — records into its own
     # tables and never into the ones the file's analysis reads.
@@ -433,6 +508,41 @@ module Rigor
       rebuild(optimistic_ivars: @optimistic_ivars.merge(name.to_sym => mark).freeze)
     end
 
+    # Issue #2555 L3 — the construction facts a LOCAL's binding carries: what the engine knows about how the object
+    # bound to it was made, as opposed to what its type says about its contents. `:synthesised` means the engine
+    # built the object itself (a collection literal, or an `Array.new` / `Hash.new` / `Set.new` / `X[...]`
+    # constructor on the core class), so its element types are this engine's own inference and no declaration's
+    # claim: the mutation seams may re-grow such a carrier precisely, where a declared one (a parameter, an RBS
+    # return) keeps the issue #561 boundary. The table is `{ name => frozen Set[Symbol] }`, so a second fact joins
+    # an existing entry without reshaping it.
+    #
+    # Locals only. An instance variable's binding is seeded across methods from the class-ivar index, whose
+    # construction no single body witnesses, so an ivar never carries a fact. Like {#optimistic_locals} the facts
+    # are kept by {#with_mutated_local} (the binding still names the same object), dropped by {#with_local} (a
+    # source-level rebind names a new one), intersected at a merge, and reset with the locals at a method body's
+    # entry. No fact is copied by an alias write (`b = a`): the type is shared, the provenance is not tracked
+    # through a second name (issue #2335), and a local that may escape anywhere in its body is never stamped
+    # ({Inference::ConstructionEscape}). Within an entry `:synthesised` intersects at a merge and `:grown` (a store
+    # has grown the carrier since construction) unions.
+    CONSTRUCTION_FACT_SETS = Ractor.make_shareable({ synthesised: Set[:synthesised] })
+    NO_CONSTRUCTION_FACTS = Set.new.freeze
+    private_constant :CONSTRUCTION_FACT_SETS, :NO_CONSTRUCTION_FACTS
+
+    def construction_fact?(name, fact = :synthesised)
+      @construction_facts.fetch(name.to_sym, NO_CONSTRUCTION_FACTS).include?(fact)
+    end
+
+    # Records `fact` on the local `name`. Applied AFTER the {#with_local} that binds the value, which drops any
+    # fact the old binding held.
+    def with_construction_fact(name, fact)
+      key = name.to_sym
+      existing = @construction_facts[key]
+      return self if existing&.include?(fact)
+
+      facts = existing ? (existing | [fact]).freeze : (CONSTRUCTION_FACT_SETS[fact] || Set[fact].freeze)
+      rebuild(@construction_facts.merge(key => facts).freeze)
+    end
+
     # ADR-82 WD1 — the propagated origin of the `Dynamic` value currently bound to a local / instance
     # variable, or `nil` when none is tracked. Consulted by `Inference::ProtectionScanner` when a dispatch's
     # receiver is a bare `x` / `@x` read whose own node carries no origin.
@@ -487,7 +597,8 @@ module Rigor
       # longer holds (the new value may carry a method-local nil). `with_declaration_sourced_local` re-establishes
       # the mark afterward when the RHS is a pure copy of a declaration-sourced ivar read; the default is to drop
       # it.
-      rebuild(locals: new_locals, fact_store: new_fact_store,
+      rebuild(keep_marks ? @construction_facts : drop_origin(@construction_facts, name),
+              locals: new_locals, fact_store: new_fact_store,
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
               declaration_sourced: keep_marks ? @declaration_sourced : drop_local_declaration_marks(name),
@@ -595,9 +706,36 @@ module Rigor
       rebuild(opaque_block_self: true, block_self_unknown: true)
     end
 
+    # Issue #2861 — the {#block_self_unknown?} value a block whose yielding call provably runs it under the
+    # caller's own `self` ({Inference::SelfPreservingBlock}) is entered with, when the caller's `self` is not
+    # already unmodelled. It reads as unknown everywhere `true` does, so issue #1717's explicit-`self` exemption is
+    # unchanged; what it withholds is the #316 opaque mark, and it tells a block nested beneath it that it does
+    # not sit under an index walk ({#walked_block_self_unknown?}).
+    PRESERVED_BLOCK_SELF = :preserved
+
+    # Issue #2861 — the entry for a block {Inference::SelfPreservingBlock} proves runs under the caller's `self`
+    # (`rows.map { … }`, `5.times { … }`). Ruby gives the block the `self` the call site has, so the block is as
+    # opaque as the scope around it and no more: it keeps whatever #316 mark the caller's scope carries and adds
+    # none, so a cross-file top-level `def` binds there exactly where it binds beside the call
+    # ({#bindable_top_level_def_for}). A caller's unknown-`self` mark of `true` or {PRESERVED_BLOCK_SELF} is kept as
+    # it is (no rebuild); a {REFINEMENT_BLOCK_SELF} one is not, since the block's `self` is not the refinement module
+    # the mark describes.
+    def entering_self_preserving_block
+      return self if @block_self_unknown == true || @block_self_unknown == PRESERVED_BLOCK_SELF
+
+      rebuild(block_self_unknown: PRESERVED_BLOCK_SELF)
+    end
+
     # True when this scope sits inside a block whose `self` is unmodelled ({#entering_opaque_block}).
     def opaque_block_self? = @opaque_block_self
 
+    # Issue #2861 — true where the unknown-`self` mark came from the index walk or a value-position block
+    # ({#with_block_self_unknown}) rather than a block entry: the mark is set, the #316 one is not, and it is not
+    # a {PRESERVED_BLOCK_SELF} entry's. A block nested in such a scope keeps the #316 mark off (issue #1717).
+    def walked_block_self_unknown?
+      !!@block_self_unknown && !@opaque_block_self && @block_self_unknown != PRESERVED_BLOCK_SELF
+    end
+
     # Issue #1717 — true when this scope sits in a block whose `self` the engine does not know, so an explicit
     # `self.m` there is no evidence `m` is missing: the yielding method may `instance_exec` the block on another
     # object. Read ONLY by `call.undefined-method`'s explicit-`self` exemption, and kept apart from
@@ -681,9 +819,8 @@ module Rigor
 
     # Slice 7 phase 1 — instance/class/global variable bindings. `ivar(name)` / `cvar(name)` / `global(name)`
     # return the type currently bound for the named variable, or `nil` when the variable has not been written in
-    # the analyzed slice of the program. The first cut tracks bindings only within a single method body (each
-    # `def` enters with a fresh binding map), so reads in other methods of the same class fall through to
-    # `Dynamic[Top]`. Cross-method ivar/cvar inference is a follow-up slice.
+    # the analyzed slice of the program. Each `def` enters with a fresh binding map seeded from the class-level
+    # accumulators ({#class_ivars_for}, {#class_cvars_for}).
     def ivar(name)
       @ivars[name.to_sym]
     end
@@ -854,6 +991,56 @@ module Rigor
       @declaration_sourced.include?([:inferred_param, name.to_sym])
     end
 
+    # Issue #2656 — stamp the gradual-narrowing mark on the local `name`: a class guard narrowed it from a `Dynamic`
+    # value, so its `Nominal` reading is the guard's, not a contract the value was checked against. Rides the ADR-58
+    # side-mark machinery under a distinct `:gradual_narrowing` kind, as `:inferred_param` does: the displayed type
+    # stays the narrowed `Nominal` (dispatch, `call.undefined-method` and `call.wrong-arity` read it), and only
+    # `call.argument-type-mismatch` consults the mark ({Analysis::CheckRules::DeclarationSourcedGuard.gradual_narrowed?}).
+    # Like the `:local` mark it is dropped by `with_local` and intersected by `join`. Applied after the binding.
+    def with_gradual_narrowing_mark(name)
+      marks = add_declaration_sourced(:gradual_narrowing, name)
+      return self if marks.equal?(@declaration_sourced)
+
+      marks = (marks.dup << GRADUAL_HINT).freeze unless marks.include?(GRADUAL_HINT)
+      rebuild(declaration_sourced: marks)
+    end
+
+    # Issue #2656 — a ref stamped beside every gradual-narrowing mark, so {#gradual_narrowing_names} can answer "none"
+    # with one hash lookup instead of a walk of the set, which the ADR-67 marks keep non-empty in most bodies. It is a
+    # hint: a drop leaves it, and the walk then finds no mark; a join keeps it only where both arms carry it.
+    GRADUAL_HINT = [:gradual_narrowing_hint].freeze
+    private_constant :GRADUAL_HINT
+
+    # Issue #2656 — this scope without the gradual-narrowing mark of every local `block_node` writes: a block may run
+    # again after its own write (`loop do mode(x); x = "zz".dup; end`), and its entry does not see that back edge, so
+    # a mark from before the block must not reach a read the write may precede. Zero-alloc when no local is marked.
+    def entering_block_without_gradual_marks(block_node)
+      names = gradual_narrowing_names
+      return self if names.empty?
+
+      written = Inference::OperandEffects.written_variables(block_node).map(&:to_sym)
+      dropped = names.reduce(@declaration_sourced) do |marks, name|
+        written.include?(name) ? drop_gradual_narrowing_mark(marks, name) : marks
+      end
+      dropped.equal?(@declaration_sourced) ? self : rebuild(declaration_sourced: dropped)
+    end
+
+    # Issue #2656 — the locals carrying the gradual-narrowing mark, empty when none does.
+    def gradual_narrowing_names
+      return EMPTY_GRADUAL_NAMES unless @declaration_sourced.include?(GRADUAL_HINT)
+
+      @declaration_sourced.filter_map { |ref| ref[1] if ref[0] == :gradual_narrowing }
+    end
+    EMPTY_GRADUAL_NAMES = [].freeze
+    private_constant :EMPTY_GRADUAL_NAMES
+
+    # Issue #2656 — true when the local `name`'s binding is a class guard's narrowing of a `Dynamic` value.
+    def gradual_narrowing?(name)
+      return false if @declaration_sourced.empty?
+
+      @declaration_sourced.include?([:gradual_narrowing, name.to_sym])
+    end
+
     def with_cvar(name, type)
       rebuild(cvars: @cvars.merge(name.to_sym => type).freeze)
     end
@@ -1186,8 +1373,8 @@ module Rigor
     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
+    # the value maps every ivar that appears as a write target inside any def body of that class to its type.
+    # `StatementEvaluator#build_method_entry_scope` seeds the method body's `ivars` map from this
     # table so a `def get; @x; end` reads the type written in a sibling `def init; @x = 1; end`.
     #
     # `ScopeIndexer` populates the table once at index time through a separate pre-pass over the program. The map
@@ -1207,7 +1394,7 @@ module Rigor
       @discovery.class_cvars[class_name.to_s] || EMPTY_VAR_BINDINGS
     end
 
-    # Slice 7 phase 12 — in-source method discovery. Maps a qualified class name to a `Hash[Symbol, Symbol]` of
+    # Slice 7 phase 12 — in-source method discovery. Maps a qualified class name to a table of
     # `method_name => :instance | :singleton`. Populated by `ScopeIndexer` from every `Prism::DefNode` and
     # recognised `define_method` invocation inside class/module bodies. The `rigor check` undefined-method and
     # wrong-arity rules consult this map to suppress diagnostics for methods the user has defined dynamically,
@@ -1230,6 +1417,58 @@ module Rigor
       true
     end
 
+    # Issue #2555 — whether the project defines a method named `method_name` anywhere: on any class or module,
+    # instance or singleton side (the def-node tables, which hold a plain cross-file `def` on an RBS-declared class
+    # that `discovered_methods` withholds, and `discovered_methods`), or in a `refine` block. The name set is built
+    # once per discovery index. The answer depends on every file, so an incremental run records the name either way:
+    # a file that starts or stops defining it re-analyses the reader (issue #1459's `defines:` edge).
+    def project_method_name?(method_name)
+      Analysis::DependencyRecorder.read_name(:defines, method_name) if Analysis::DependencyRecorder.active?
+      return true if project_method_names.include?(method_name.to_sym)
+
+      false
+    end
+
+    # The name set {#project_method_name?} reads, held per discovery index. ADR-129 G2: a hit is checked against a
+    # fresh collection under `RIGOR_MEMO_AUDIT=1`, and an audit recomputation bypasses the table.
+    def project_method_names
+      return collect_project_method_names if memo_audit_bypass?
+
+      table = TypingState.current.weak_key_map(PROJECT_METHOD_NAMES)
+      names = table[@discovery]
+      if names.nil?
+        return table[@discovery] = Inference::MemoAudit.key_audit("project method names") do
+          collect_project_method_names
+        end
+      end
+
+      Inference::MemoAudit.check("project method names", names, :discovery) { collect_project_method_names }
+    end
+    private :project_method_names
+
+    # ADR-129 G2 — true while a MemoAudit recomputation runs: the memos wired here are then bypassed, neither read
+    # nor written. One boolean check when the audit is off.
+    def memo_audit_bypass? = Inference::MemoAudit.enabled? && Inference::MemoAudit.suspended?
+    private :memo_audit_bypass?
+
+    def collect_project_method_names
+      names = Set.new
+      [@discovery.discovered_methods, @discovery.discovered_def_nodes, @discovery.discovered_singleton_def_nodes,
+       @discovery.discovered_refinements].each do |by_owner|
+        by_owner.each_value { |methods| methods.each_key { |method_name| names << method_name.to_sym } }
+      end
+      names.freeze
+    end
+    private :collect_project_method_names
+
+    # ADR-129 WD1 — a run-scoped Memo ({TypingState}): emptied when a run ends, so an edited project is read afresh.
+    PROJECT_METHOD_NAMES = TypingState.memo(
+      :project_method_names,
+      run_scoped: true, audit: "project method names",
+      reason: "a WeakKeyMap keyed on the discovery index; the name set reads only its tables"
+    )
+    private_constant :PROJECT_METHOD_NAMES
+
     def record_discovered_method(class_name, method_name)
       record_class_dependency(class_name)
       Analysis::DependencyRecorder.read_name(:defines, method_name)
@@ -1258,7 +1497,7 @@ module Rigor
       per_class && per_class[method_name]
     end
 
-    # v0.0.2 #5 — per-class table mapping `method_name (Symbol) → Prism::DefNode`. Populated by `ScopeIndexer`
+    # v0.0.2 #5 — per-class table mapping `method_name → 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
     # inter-procedural return-type inference when the receiver class is user-defined and has no RBS sig.
@@ -1272,6 +1511,89 @@ module Rigor
       Inference::DefNodeResolver.resolve(entry)
     end
 
+    # Issue #2515 — `[class_name, open]` for each class or module whose instance def table holds `method_name`, in
+    # table order (frozen; empty when no user def has the name). The callee floor's hand-off on a receiver it cannot
+    # type reads every def of the name, so the answer depends on the whole project's defs of that name: a recorder
+    # files the `defines:<name>` name edge, which fires when a file starts or stops defining it. `open` is true when
+    # the real receiver may not be the class the def sits on: the owner is a module (an includer's methods are
+    # called from it), or a project class names it as its superclass (a subclass may override what the def calls).
+    # A recorder files `subclass_of:<owner>` for the second.
+    def user_instance_def_owners(method_name)
+      Analysis::DependencyRecorder.read_name(:defines, method_name) if Analysis::DependencyRecorder.active?
+      name = method_name.to_sym
+      # `each` with a lazily built array, not `filter_map`: this runs once per call on every discovered class, and
+      # `Hash#filter_map` allocates a `[key, value]` pair per entry (#2895 cost 3.35% of the release gate's
+      # allocations that way).
+      owners = nil
+      @discovery.discovered_def_nodes.each do |class_name, defs|
+        next unless defs.key?(name) && class_name != Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
+
+        (owners ||= []) << [class_name, open_to_override?(class_name)].freeze
+      end
+      owners.nil? ? EMPTY_OWNERS : owners.freeze
+    end
+
+    EMPTY_OWNERS = [].freeze
+    private_constant :EMPTY_OWNERS
+
+    # Issue #2515 — `[opaque, keys]`: whether the project holds a subclass relation the superclass table does not
+    # spell as `class X < Name`, so that no owner can be called free of an override. It holds when a class takes
+    # `Class.new(Parent)` ({DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK}), when a class's superclass expression is
+    # unreadable (`nil` in the table), or when a written superclass is not a declared class and some file assigns a
+    # constant of that name (`H2 = Helper; class Sub < H2`; the writer census {#bound_constant_names} or this file's
+    # constant table).
+    # `keys` are the frozen ADR-46 name keys a recorder files for the answer; the caller files them, since the answer
+    # is memoised per discovery.
+    def subclassing_opacity
+      keys = OPACITY_KEYS.dup
+      opaque = @discovery.discovered_parameter_envelopes.each_value.any? do |bucket|
+        bucket.key?(DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK)
+      end
+      segments = {}
+      @discovery.discovered_superclasses.each_value do |parent|
+        opaque = true if parent.nil? || alias_superclass?(parent, segments, keys)
+      end
+      [opaque ? true : false, keys.each(&:freeze).freeze].freeze
+    end
+
+    # True when `parent`, a written superclass that is no declared class, names a constant some file assigns. Files
+    # the `constant:<segment>` key for it once per segment.
+    def alias_superclass?(parent, segments, keys)
+      return false if @discovery.discovered_classes.key?(parent)
+
+      cut = parent.rindex("::")
+      segment = cut ? parent.byteslice(cut + 2, parent.bytesize - cut - 2) : parent
+      return false if segments.key?(segment)
+
+      segments[segment] = true
+      keys << "constant:#{segment}"
+      @discovery.constant_writers.key?(segment) || @discovery.in_source_constants.key?(parent)
+    end
+    private :alias_superclass?
+
+    OPACITY_KEYS = %w[subclass_of:* mark:*].freeze
+    private_constant :OPACITY_KEYS
+
+    def open_to_override?(class_name)
+      Analysis::DependencyRecorder.read_last_segment(:subclass_of, class_name) if Analysis::DependencyRecorder.active?
+      return true if @discovery.discovered_parameter_envelopes[class_name]&.key?(DiscoveryIndex::ENVELOPE_MODULE_MARK)
+
+      @discovery.discovered_superclasses.any? do |child, parent|
+        child != class_name && parent && names_class?(parent, class_name)
+      end
+    end
+    private :open_to_override?
+
+    # True when a superclass written as `written` (`Helper`, `A::Helper`, `::Helper`) may name `qualified`.
+    def names_class?(written, qualified)
+      written = written[2..] if written.start_with?("::")
+      return true if written == qualified
+      return false unless qualified.end_with?(written)
+
+      qualified.getbyte(qualified.bytesize - written.bytesize - 1) == 58
+    end
+    private :names_class?
+
     # Module-singleton call resolution (ADR-57 follow-up) — companion of {#user_def_for} for SINGLETON-side defs
     # (`def self.x`, `def Foo.x`, `class << self` bodies, and `module_function` defs). Returns the
     # `Prism::DefNode` for `class_name.method_name` invoked on the module/class constant itself, or nil. The
@@ -1317,6 +1639,199 @@ module Rigor
       Inference::DefNodeResolver.resolve(entry)
     end
 
+    # Issue #2515 — why the `<toplevel>` table's def for `method_name` may not be the method a receiverless call of that
+    # name runs, or nil when the project's own tables show nothing else that could be. The table keeps one def per name
+    # (the last writer's) and also files the defs of an anonymous `Class.new` body, so:
+    #
+    # - `:contested` — a def in a block or under a condition wrote the slot last;
+    # - `:several` — the project holds more than one ownerless definition row of the name: two top-level defs (across
+    #   files, or redefined), a def in a block or in another def, `define_method` or `alias_method` of the name;
+    # - `:main_singleton` — a `def self.name` (or a `class << self` def) at the top level defines it on `main`;
+    # - `:aliased` — an `alias` statement or `alias_method` call names it as the new name;
+    # - `:anonymous` — an anonymous class body defines it;
+    # - `:object` — `Object` itself defines it (`class Object; def name`, `define_method`) or has a module prepended,
+    #   which Ruby searches ahead of the top-level def. A module included at the top level is searched after `Object`'s
+    #   own methods, so it is no reason.
+    #
+    # A name with no row at all (a scope built without the project pre-pass) is not `:several`: the rows say nothing.
+    # The answer depends on every file, so an incremental run records the `defines:<name>` edge and the census edge of
+    # an alias either way. The two project-wide scans are built once per table, not per call.
+    def toplevel_def_ambiguity(method_name)
+      name = method_name.to_sym
+      record_toplevel_ambiguity_reads(name) if Analysis::DependencyRecorder.active?
+      key = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
+      return :contested if @discovery.contested_discovered_def_nodes.include?([key, name])
+
+      rows = toplevel_definition_rows[name]
+      return :main_singleton if rows == MAIN_SINGLETON_ROWS
+      return :several if rows > 1
+      return :aliased if method_alias_names.include?(name)
+
+      return :anonymous if @discovery.discovered_def_nodes.any? do |class_name, defs|
+        defs.key?(name) && class_name.start_with?(Type::AnonymousClassName::PREFIX)
+      end
+
+      :object if object_answers_first?(name)
+    end
+
+    # True when `Object` defines `name` itself or has a module prepended (see {#toplevel_def_ambiguity}).
+    def object_answers_first?(name)
+      !user_def_for("Object", name).nil? || discovered_method?("Object", name, :instance) ||
+        !(@discovery.discovered_prepends["Object"] || EMPTY_PREPENDS).empty?
+    end
+    private :object_answers_first?
+
+    EMPTY_PREPENDS = [].freeze
+    private_constant :EMPTY_PREPENDS
+
+    # True for a class or module the project declares, even one with no method of its own.
+    def declared_class?(class_name) = @discovery.discovered_classes.key?(class_name.to_s)
+
+    def record_toplevel_ambiguity_reads(name)
+      Analysis::DependencyRecorder.read_name(:defines, name)
+      Analysis::DependencyRecorder.read_name(:global_census, "method_alias:#{name}")
+      Analysis::DependencyRecorder.read_last_segment(:class, "Object")
+      record_class_dependency("Object")
+    end
+    private :record_toplevel_ambiguity_reads
+
+    # Issue #2336 — whether the project gives `method_name` a body through an ownerless definition row
+    # ({#toplevel_definition_rows}): a `define_method` / `define_singleton_method` / `alias_method` call with that
+    # literal name on any receiver, a def in a block, or (with `top_level:`) a def outside every class body. The
+    # callee mutation floor reads a call no def table answers as one such body may run. The answer depends on every
+    # file, so an incremental run records the `defines:<name>` edge either way.
+    def ownerless_definition?(method_name, top_level: true)
+      Analysis::DependencyRecorder.read_name(:defines, method_name) if Analysis::DependencyRecorder.active?
+      name = method_name.to_sym
+      return true if top_level ? toplevel_definition_rows.key?(name) : deferred_definition_names.include?(name)
+
+      false
+    end
+
+    # The names of the ownerless rows that claim no side ({#ownerless_definition?} without `top_level:`): a definer
+    # call's literal name and a def in a block. Held by the table's identity, as {#toplevel_definition_rows} is.
+    def deferred_definition_names
+      ranges = @discovery.discovered_deferred_ranges
+      return collect_deferred_definition_names(ranges) if memo_audit_bypass?
+
+      state = TypingState.current
+      slots = (state[DEFERRED_NAMES] ||= [])
+      slot = slots.find { |entry| entry[0].equal?(ranges) }
+      if slot
+        return Inference::MemoAudit.check("deferred definition names", slot[1], :ranges) do
+          collect_deferred_definition_names(ranges)
+        end
+      end
+
+      names = Inference::MemoAudit.key_audit("deferred definition names") { collect_deferred_definition_names(ranges) }
+      slots.unshift([ranges, names]).slice!(2..)
+      names
+    end
+    private :deferred_definition_names
+
+    def collect_deferred_definition_names(ranges)
+      names = Set.new
+      ranges.each_value do |entries|
+        entries.each { |(_start, _finish, name, kind, owner)| names << name if name && kind.nil? && owner.nil? }
+      end
+      names.freeze
+    end
+    private :collect_deferred_definition_names
+
+    # Issue #2336 — {#module_function_def?}'s `:both` reading for a def in any file: whether `def_node`, an instance
+    # def of `owner`, is a module function by a deferred-range row over it (`module_function def x`, or a bare
+    # `module_function` before it), which the singleton def table does not mirror for the argument form.
+    def module_function_row_def?(def_node, owner)
+      start = def_node.location.start_offset
+      name = def_node.name
+      owner = owner.to_s
+      discovered_deferred_ranges.each_value.any? do |entries|
+        entries.any? do |(row_start, _finish, row_name, kind, row_owner)|
+          row_start == start && kind == :both && row_name == name && row_owner == owner
+        end
+      end
+    end
+
+    # `{ name => ownerless definition rows }` over `discovered_deferred_ranges`, {MAIN_SINGLETON_ROWS} for a name with
+    # a singleton row. Held by the table's identity (a file's merged copy and the seed), released with the run.
+    def toplevel_definition_rows
+      ranges = @discovery.discovered_deferred_ranges
+      return collect_toplevel_definition_rows(ranges) if memo_audit_bypass?
+
+      state = TypingState.current
+      slots = (state[TOPLEVEL_ROWS] ||= [])
+      slot = slots.find { |entry| entry[0].equal?(ranges) }
+      if slot
+        return Inference::MemoAudit.check("toplevel definition rows", slot[1], :ranges) do
+          collect_toplevel_definition_rows(ranges)
+        end
+      end
+
+      rows = Inference::MemoAudit.key_audit("toplevel definition rows") { collect_toplevel_definition_rows(ranges) }
+      slots.unshift([ranges, rows]).slice!(2..)
+      rows
+    end
+    private :toplevel_definition_rows
+
+    def collect_toplevel_definition_rows(ranges)
+      rows = Hash.new(0)
+      ranges.each_value do |entries|
+        entries.each do |(_start, _finish, name, kind, owner)|
+          next if name.nil? || !owner.nil?
+
+          rows[name] = kind == :singleton || rows[name] == MAIN_SINGLETON_ROWS ? MAIN_SINGLETON_ROWS : rows[name] + 1
+        end
+      end
+      rows.freeze
+    end
+    private :collect_toplevel_definition_rows
+
+    # The names an `alias` statement or `alias_method` call introduces, from the global write census; held by the
+    # census's identity as {#toplevel_definition_rows} is.
+    def method_alias_names
+      census = @discovery.discovered_global_write_census
+      return collect_method_alias_names(census) if memo_audit_bypass?
+
+      state = TypingState.current
+      slots = (state[METHOD_ALIASES] ||= [])
+      slot = slots.find { |entry| entry[0].equal?(census) }
+      if slot
+        return Inference::MemoAudit.check("method alias names", slot[1], :census) { collect_method_alias_names(census) }
+      end
+
+      names = Inference::MemoAudit.key_audit("method alias names") { collect_method_alias_names(census) }
+      slots.unshift([census, names]).slice!(2..)
+      names
+    end
+    private :method_alias_names
+
+    def collect_method_alias_names(census)
+      census.each_with_object(Set.new) { |entry, acc| acc << entry[1] if entry[0] == :method_alias }.freeze
+    end
+    private :collect_method_alias_names
+
+    MAIN_SINGLETON_ROWS = -1
+    # ADR-129 WD1 — three run-scoped Memos, each a two-entry list of `[table, derived]` held by the identity of the
+    # table the derived value reads (the deferred ranges, or the global write census).
+    TOPLEVEL_ROWS = TypingState.memo(
+      :toplevel_definition_rows,
+      run_scoped: true, audit: "toplevel definition rows",
+      reason: "[deferred ranges, rows] entries keyed on the identity of the ranges table, the only input the rows read"
+    )
+    METHOD_ALIASES = TypingState.memo(
+      :method_alias_names,
+      run_scoped: true, audit: "method alias names",
+      reason: "[census, names] entries keyed on the identity of the global write census, the only input the names " \
+              "read"
+    )
+    DEFERRED_NAMES = TypingState.memo(
+      :deferred_definition_names,
+      run_scoped: true, audit: "deferred definition names",
+      reason: "[deferred ranges, names] entries keyed on the identity of the ranges table, the only input the names " \
+              "read"
+    )
+    private_constant :MAIN_SINGLETON_ROWS, :TOPLEVEL_ROWS, :METHOD_ALIASES, :DEFERRED_NAMES
+
     # Issue #316 — the CONFIDENCE-GATED companion of {#top_level_def_for}, and the only accessor the type
     # inference may bind through. {#top_level_def_for} stays unrestricted because it also serves the
     # *suppression* side (`call.unresolved-toplevel`, `call.undefined-method`): a name the project defines at
@@ -1556,6 +2071,14 @@ module Rigor
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
+    # Issue #2986 — the modules `class_name` prepends, as written, in search order: the prepended part of
+    # {#includes_of}, which lists them ahead of the included ones. An ActiveSupport::Concern's `prepended do … end`
+    # block runs for a prepend edge only, and its `included do … end` block for an include edge only.
+    def prepends_of(class_name)
+      record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
+      @discovery.discovered_prepends[class_name.to_s] || EMPTY_PREPENDS
+    end
+
     # Issue #898 — the module names `extend`ed onto `class_name`'s SINGLETON, as written, gathered up the
     # as-written superclass chain because a singleton class inherits its superclass's singleton class
     # (`class Base; extend Comparable; end; class Widget < Base; end` leaves `Widget.is_a?(Comparable)`
@@ -1622,6 +2145,7 @@ module Rigor
       end
       return found if found
 
+      chain.record_external_absence
       chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
     end
 
@@ -1661,6 +2185,7 @@ module Rigor
       end
       return found if found
 
+      chain.record_external_absence
       chain.truncated? ? ancestor_walk_gave_up : [nil, nil]
     end
 
@@ -1744,6 +2269,8 @@ module Rigor
         discovered_method?(entry.name, method_name, entry.side == :singleton ? :singleton : kind_for(kind))
       end
       return true if found
+
+      record_discovered_miss(chain, method_name) if Analysis::DependencyRecorder.active?
       # 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?
@@ -1752,6 +2279,28 @@ module Rigor
       true
     end
 
+    # Issue #2689 — the ADR-46 negative edges of a discovery-walk miss: the answer is "no project entry on the chain
+    # defines it", so a later edit that defines it on any of them, or a new file that reopens one of them (and may
+    # change the chain, `include` a module that defines it), turns it. Each project entry files the `method:` key
+    # `Incremental.appeared_symbols` emits for that definition (`Name.method` for a class object's own side,
+    # `Name#method` for an instance-chain entry and for a module on the singleton chain, which answers with its
+    # instance methods) and the `class:` key a declaring file appearing fires — the edges the def walk files for the
+    # same miss (`#user_def_for` per entry, `ResolutionChain#settle` for the classes). A hit files none: existence is
+    # a union, so no other entry gaining the method can turn a found answer.
+    # An external entry (an ancestor declared with no methods, or not yet) files its `class:` key
+    # ({ResolutionChain#record_external_absence}), as the def walks do on a miss.
+    def record_discovered_miss(chain, method_name)
+      chain.record_external_absence
+      chain.entries.each do |entry|
+        next if entry.external?
+
+        separator = entry.side == :singleton ? "." : "#"
+        Analysis::DependencyRecorder.read_missing(:method, "#{entry.name}#{separator}#{method_name}")
+        Analysis::DependencyRecorder.read_missing(:class, entry.last_segment)
+      end
+    end
+    private :record_discovered_miss
+
     # 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
@@ -1970,7 +2519,7 @@ module Rigor
     EMPTY_PARAMETER_ENVELOPES = {}.freeze
     private_constant :EMPTY_PARAMETER_ENVELOPES
 
-    # v0.1.2 — per-class table mapping `method_name (Symbol) → :public | :private | :protected`. Populated by
+    # v0.1.2 — per-class table mapping `method_name → :public | :private | :protected`. Populated by
     # `ScopeIndexer` for every `def` and `attr_*` member it sees inside a class body, with the visibility taken from
     # a wrapping `private def` / `private attr_reader` call, else the surrounding `private` / `protected` / `public`
     # modifier state, plus any post-hoc `private :name, ...` named-argument calls. Consumed by the
@@ -1989,13 +2538,14 @@ module Rigor
       table[singleton ? [:singleton, method_name.to_sym] : method_name.to_sym]
     end
 
-    # Closes the "`params[:f] ||= []; params[:f] << x`" precision gap (ROADMAP § Type-language / engine —
-    # indexed-collection narrowing through `Hash[k] ||= default`). After `receiver[key] ||= default`, the next
+    # Closes the "`params[:f] ||= []; params[:f] << x`" precision gap. After `receiver[key] ||= default`, the next
     # read at `receiver[key]` is known non-nil; recording the post-`||=` type keyed on
     # `(receiver_kind, receiver_name, literal_key)` lets the ExpressionTyper's `[]` dispatch hand back the
     # narrowed type. Receiver-rebind and `[]=`/mutator invalidation rules are documented at the call sites in
     # `Inference::StatementEvaluator`.
     def indexed_narrowing(receiver_kind, receiver_name, key)
+      return nil if @indexed_narrowings.empty?
+
       @indexed_narrowings[indexed_key(receiver_kind, receiver_name, key)]
     end
 
@@ -2007,6 +2557,8 @@ module Rigor
     end
 
     def without_indexed_narrowing(receiver_kind, receiver_name, key)
+      return self if @indexed_narrowings.empty?
+
       lookup = indexed_key(receiver_kind, receiver_name, key)
       return self unless @indexed_narrowings.key?(lookup)
 
@@ -2021,14 +2573,15 @@ module Rigor
       rebuild(indexed_narrowings: new_table)
     end
 
-    # Closes the "stable receiver method-chain narrowing" gap (ROADMAP § Future cycles / Type-language / engine —
-    # "Method-call receiver narrowing across stable receivers"; 2026-05-28 Redmine survey). After
+    # Closes the "stable receiver method-chain narrowing" gap (2026-05-28 Redmine survey). After
     # `if x.last.is_a?(Array)` the dominated body's `x.last` reads MUST observe the truthy-narrowed type; the same
     # chain reaching the falsey edge observes the negative narrowing.
     #
     # Address shape mirrors {.indexed_narrowing}: stable root variable + no-arg single-hop method name. See
     # {ChainKey} for the precise contract.
     def method_chain_narrowing(receiver_kind, receiver_name, method_name)
+      return nil if @method_chain_narrowings.empty?
+
       @method_chain_narrowings[chain_key(receiver_kind, receiver_name, method_name)]
     end
 
@@ -2040,6 +2593,8 @@ module Rigor
     end
 
     def without_method_chain_narrowing(receiver_kind, receiver_name, method_name)
+      return self if @method_chain_narrowings.empty?
+
       lookup = chain_key(receiver_kind, receiver_name, method_name)
       return self unless @method_chain_narrowings.key?(lookup)
 
@@ -2070,8 +2625,9 @@ module Rigor
     # against THIS scope's discovery index (so cross-file dispatches in the body resolve). The incremental
     # session re-drives a declaration-stable changed callee at each previously-observed call key to prove its
     # return is unchanged before skipping its symbol dependents.
-    def user_method_return(def_node, receiver, arg_types)
-      Inference::ExpressionTyper.new(scope: self).return_type_for(def_node, receiver, arg_types)
+    def user_method_return(def_node, receiver, arg_types, positionals_unknown: false)
+      typer = Inference::ExpressionTyper.new(scope: self)
+      typer.return_type_for(def_node, receiver, arg_types, positionals_unknown: positionals_unknown)
     end
 
     # Statement-level evaluation: returns the pair `[type, scope']` where `type` is what the node produces and
@@ -2149,11 +2705,13 @@ module Rigor
 
     private
 
-    # The marks {#==} compares: ADR-58's, issue #667's and the repeated `||=` sites, and #1429's guard state.
+    # The marks {#==} compares: ADR-58's, issue #667's, the repeated `||=` sites, #2555's construction facts (they
+    # change what a mutation seam answers), 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 &&
+        @construction_facts == other.construction_facts &&
         same_guard_state?(other)
     end
 
@@ -2162,7 +2720,16 @@ module Rigor
         @bot_guard_classes == other.bot_guard_classes
     end
 
+    # `construction_facts` is the one positional parameter. CRuby records which keywords a call left out in a bit
+    # field indexed by each keyword's position among ALL the method's keywords, required and optional
+    # (`VM_KW_SPECIFIED_BITS_MAX`, 31); a keyword past that index whose default is not a literal makes every call that
+    # omits it allocate the record instead. A 32nd keyword here did that on every scope transition, about 1% of an
+    # analysis's allocations (issue #2555). On CRuby 4.0 that allocation is also unsafe: a GC it starts frees the
+    # values already moved into the keyword locals (ruby/ruby Bug #22500, issue #2850). `#initialize` is past the index
+    # and keeps literal defaults there for that reason. The next Scope field crosses it in this method again, so it
+    # needs a positional slot or a restructuring, not a 32nd keyword.
     def rebuild(
+      construction_facts = @construction_facts,
       locals: @locals, fact_store: @fact_store, self_type: @self_type,
       ivars: @ivars, cvars: @cvars, globals: @globals,
       discovery: @discovery,
@@ -2213,7 +2780,7 @@ module Rigor
         plugin_typed_calls: plugin_typed_calls,
         optimistic_origins: optimistic_origins,
         optimistic_locals: optimistic_locals,
-        optimistic_ivars: optimistic_ivars,
+        optimistic_ivars: optimistic_ivars, construction_facts: construction_facts,
         repeated_or_writes: repeated_or_writes,
         match_frame: match_frame,
         constant_narrowings: constant_narrowings,
@@ -2223,11 +2790,18 @@ module Rigor
       )
     end
 
+    # A join with an empty side has no key in common (usually both are empty, the common case at a branch merge), so
+    # its answer is this one frozen hash rather than a fresh one.
+    EMPTY_BINDINGS = {}.freeze
+    private_constant :EMPTY_BINDINGS
+
     def join_bindings(left, right)
       # Keys present in both, unioned. Iterating `left` and probing `right.key?` yields the same keys in the same
       # order as the prior `(left.keys & right.keys)` while avoiding the two key arrays and the intersection
       # array — this is the control-flow join, run at every branch merge, and was a top allocation site (~75% of
       # `Hash#keys`).
+      return EMPTY_BINDINGS if left.empty? || right.empty?
+
       result = {}
       left.each do |name, ltype|
         next unless right.key?(name)
@@ -2306,6 +2880,8 @@ module Rigor
         optimistic_origins: @optimistic_origins,
         optimistic_locals: join_optimistic_marks(@optimistic_locals, other.optimistic_locals),
         optimistic_ivars: join_optimistic_marks(@optimistic_ivars, other.optimistic_ivars),
+        # Issue #2555 L3 — INTERSECTION: a construction fact holds after a merge only when both arms established it.
+        construction_facts: join_construction_facts(@construction_facts, other.construction_facts),
         # 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),
@@ -2403,6 +2979,31 @@ module Rigor
             .freeze
     end
 
+    # Issue #2555 L3 — a fact survives a merge only for a name both arms hold it for, and only the facts both agree
+    # on. Zero-alloc when either side is empty or both are the same table.
+    def join_construction_facts(mine, theirs)
+      return mine if mine.equal?(theirs)
+      return EMPTY_ORIGINS if mine.empty? || theirs.empty?
+
+      joined = {}
+      mine.each do |name, facts|
+        their_facts = theirs[name]
+        next if their_facts.nil?
+
+        common = facts == their_facts ? facts : join_fact_sets(facts, their_facts)
+        joined[name] = common unless common.empty?
+      end
+      joined.empty? ? EMPTY_ORIGINS : joined.freeze
+    end
+
+    # `:grown` joins by UNION among the names both arms keep: a store on either arm may reach the carrier, and the
+    # fact only ever floors it ({Inference::MutationRejoin.floors_grown_carrier?}). Every other fact intersects.
+    def join_fact_sets(facts, their_facts)
+      common = facts & their_facts
+      common << :grown if facts.include?(:grown) || their_facts.include?(:grown)
+      common.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.
@@ -2464,19 +3065,12 @@ module Rigor
     end
 
     def indexed_key(receiver_kind, receiver_name, key)
-      IndexedKey.new(
-        receiver_kind: receiver_kind.to_sym,
-        receiver_name: receiver_name.to_sym,
-        key: key
-      )
+      # Positional `new` (field-definition order) skips the keyword hash a keyword `new` allocates.
+      IndexedKey.new(receiver_kind.to_sym, receiver_name.to_sym, key)
     end
 
     def chain_key(receiver_kind, receiver_name, method_name)
-      ChainKey.new(
-        receiver_kind: receiver_kind.to_sym,
-        receiver_name: receiver_name.to_sym,
-        method_name: method_name.to_sym
-      )
+      ChainKey.new(receiver_kind.to_sym, receiver_name.to_sym, method_name.to_sym)
     end
 
     def drop_indexed_narrowings_for(receiver_kind, receiver_name)
@@ -2558,6 +3152,7 @@ module Rigor
     # beside it ({#with_global_copy_marks}).
     def drop_local_declaration_marks(name)
       dropped = drop_declaration_sourced_for(:local, name)
+      dropped = drop_gradual_narrowing_mark(dropped, name)
       return dropped if dropped.equal?(@declaration_sourced)
 
       name = name.to_sym
@@ -2566,6 +3161,18 @@ module Rigor
       dropped.dup.delete_if { |ref| ref[0] == :global_copy && ref[1] == name }.freeze
     end
 
+    # `marks` without the local `name`'s `:gradual_narrowing` mark (issue #2656); `marks` itself when it has none.
+    def drop_gradual_narrowing_mark(marks, name)
+      return marks if marks.empty?
+
+      ref = [:gradual_narrowing, name.to_sym]
+      return marks unless marks.include?(ref)
+
+      dropped = marks.dup
+      dropped.delete(ref)
+      dropped.freeze
+    end
+
     def add_guard_record(key, pre_guard)
       return @guard_records if @guard_records.key?(key)