rigortype 0.4.5 → 0.4.7

data/lib/rigor/inference/scope_indexer/declared_ivar_types.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../../reflection"
+require_relative "../rbs_type_translator"
+
+module Rigor
+  module Inference
+    module ScopeIndexer
+      # Issue #1406 — an ivar the class's RBS declares, as `@x: T` or through an `attr_reader x: T` /
+      # `attr_writer` / `attr_accessor` member (in `sig/`, or inline `attr_reader :x #: T`), reads the declared type
+      # in place of the census's join of the writes. The declaration is the author's contract for the field, so it
+      # wins over every write the census saw, #541's untyped `attr_writer` write included; whether the writes
+      # honour it is ADR-112 WD5's question (#1075), not this one's. It serves
+      # checking only: `rigor sig-gen` indexes with `declared_ivar_types: false` and keeps the census's answer.
+      #
+      # Only an ivar the census already holds is replaced, so a declaration adds no entry the file's writes did not.
+      # A declaration is not taken when it is `untyped` (what rbs-inline supplies for a bare `attr_reader :x`, which
+      # the type specification reads as a placeholder) or mentions a type variable (`@x: T` in `class Box[T]` is
+      # unsolved at a read), and the census entry stands.
+      module DeclaredIvarTypes
+        module_function
+
+        def apply!(accumulator, scope)
+          environment = scope&.environment
+          return if environment.nil?
+
+          accumulator.each do |class_name, entries|
+            next unless class_name.is_a?(String) # a guard: the side-table keys are deleted before this runs
+
+            declared = declared_ivars(class_name, environment)
+            next if declared.empty?
+
+            accumulator[class_name] = entries.to_h do |ivar, type|
+              [ivar, declared.fetch(ivar, type)]
+            end
+          end
+        end
+
+        # `{ivar name => Rigor::Type}` for the ivars `class_name`'s RBS instance definition declares with a usable
+        # type, or `{}`.
+        def declared_ivars(class_name, environment)
+          definition = Reflection.instance_definition(class_name, environment: environment)
+          return {} if definition.nil?
+
+          instance = Type::Combinator.nominal_of(class_name)
+          definition.instance_variables.each_with_object({}) do |(name, variable), acc|
+            type = translate(variable.type, instance, environment)
+            acc[name] = type if type
+          end
+        rescue StandardError # a guard: a definition that fails to build declares nothing
+          {}
+        end
+
+        def translate(rbs_type, instance, environment)
+          return nil unless rbs_type.free_variables.empty?
+
+          type = RbsTypeTranslator.translate(rbs_type, self_type: instance, instance_type: instance,
+                                                       alias_expander: environment.rbs_loader)
+          type.is_a?(Type::Dynamic) ? nil : type
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/scope_indexer/declared_param_writes.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../reflection"
+require_relative "../method_parameter_binder"
+require_relative "../global_write_census"
+require_relative "unseen_ivar_writers"
+require_relative "derived_param_value"
+
+module Rigor
+  module Inference
+    module ScopeIndexer
+      # Issue #1154 — the class-ivar census types an `@x = x` write whose right-hand side reads a parameter of the
+      # enclosing instance `def` as that parameter's DECLARED type: the method's RBS signature, from `sig/` or from
+      # an rbs-inline `# @rbs` / `#:` annotation, read through {MethodParameterBinder}, the binder the method body's
+      # own entry scope uses. Without it the census typed the rvalue with no local bindings, so a constructor field
+      # read `Dynamic[top]` in every sibling method even where `sig/` declared `initialize: (String x) -> void`.
+      #
+      # The census is flow-free, so a write is credited only where the parameter can hold nothing but its
+      # argument. {.collect} answers `{write node => declared type}` (an identity Hash) for the writes that pass
+      # every gate, and {EMPTY} otherwise; an absent write keeps the census's ordinary rvalue typing, so a declined
+      # case reads exactly what it read before:
+      #
+      # - the write's value reads at least one parameter, and every local it reads is a parameter with a declared type.
+      #   A bare read (`@x = x`) records that type; an expression over parameters (`@x = x.dup.freeze`,
+      #   `@x = Array(x)`, `@x = f ? x : y`, issue #2321) records the value typed with each parameter it reads bound to
+      #   its declared type, unless {DerivedParamValue} declines it (a parameter that holds `untyped` at any depth or
+      #   has a default outside its declared type, or a call argument whose type may match a narrower overload). A
+      #   value that holds a block, a lambda or a nested `def` is not credited: their own parameters are locals the
+      #   scan does not bind;
+      # - the write is not inside a block or a lambda, so a block parameter of the same name and a block that runs
+      #   under another `self` (`instance_eval`, `Class.new`, `define_method`) never borrow the method's parameter;
+      # - the method body never writes the parameter, in any form and at any depth (`x = Integer(x)`, `x ||= …`,
+      #   a `rescue => x` or pattern target);
+      # - the owner is a class, not a module (a module's ivar belongs to whichever object includes it), and its
+      #   RBS declares the method itself (`defined_in`), so an inherited signature never types a redefinition;
+      # - the signature has exactly one overload, whose parameter lists are typed (`(?)` declines) and mention no
+      #   type variable (a class `Box[T]` or a method `[T]` variable is unsolved at the write);
+      # - the class's primary RBS declaration is the project's (`sig/` or rbs-inline), not core, stdlib or a gem's:
+      #   a project reopening of a library class (`Thread::SizedQueue#initialize`) would otherwise borrow the
+      #   library's parameter type for its own `def`;
+      # - the body neither calls `binding` nor passes code as an argument to an `eval`-family call
+      #   (`OPAQUE_EVAL_CALLS`), any of which can rewrite the parameter unseen;
+      # - nothing outside the class's own census may write the ivar ({UnseenIvarWriters}): no project ancestor, and
+      #   no other object's code (`o.instance_variable_set(:@x, v)`);
+      # - the declared type is not `untyped`, which is what the write already records.
+      module DeclaredParamWrites
+        EMPTY = {}.compare_by_identity.freeze
+
+        SCOPE_BARRIERS = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+        private_constant :SCOPE_BARRIERS
+
+        BLOCK_NODES = [Prism::BlockNode, Prism::LambdaNode].freeze
+        private_constant :BLOCK_NODES
+
+        OPAQUE_EVAL_CALLS = %i[eval instance_eval class_eval module_eval instance_exec class_exec
+                               module_exec].to_set.freeze
+        private_constant :OPAQUE_EVAL_CALLS
+
+        WRITER_SCOPE_KEY = :__rigor_declared_param_writer_scope__
+        private_constant :WRITER_SCOPE_KEY
+
+        module_function
+
+        # Runs the block with `scope` as the one whose project tables the unseen-writer and single-file gates read, in
+        # place of the census's own scope. `rigor sig-gen` indexes each file over the project tables less the member
+        # layouts; this scope carries all of them, so another file's writer, ancestor or reopening is seen.
+        def with_writer_scope(scope)
+          return yield if scope.nil?
+
+          previous = Thread.current[WRITER_SCOPE_KEY]
+          Thread.current[WRITER_SCOPE_KEY] = scope
+          begin
+            yield
+          ensure
+            Thread.current[WRITER_SCOPE_KEY] = previous
+          end
+        end
+
+        def writer_scope(scope) = Thread.current[WRITER_SCOPE_KEY] || scope
+
+        # `{InstanceVariableWriteNode => Rigor::Type}` for `def_node`'s creditable writes, or {EMPTY}. The caller
+        # passes only an instance `def`: a singleton body's `@x` is the class object's.
+        def collect(def_node, class_name, scope)
+          return EMPTY if def_node.body.nil? || def_node.parameters.nil?
+
+          written = Set.new
+          writes = []
+          return EMPTY if scan(def_node.body, written, writes, in_block: false) == :opaque
+
+          reads = unwritten_reads(writes, written)
+          return EMPTY if reads.empty?
+
+          types = declared_types(def_node, class_name, scope)
+          writers = writer_scope(scope)
+          credited = reads.each_with_object({}.compare_by_identity) do |(write, names), acc|
+            next unless names.all? { |name| types.key?(name) }
+
+            type = value_type(write.value, names, types, def_node, scope)
+            acc[write] = type if type && !UnseenIvarWriters.possible?(writers, class_name, write.name)
+          end
+          credited.empty? ? EMPTY : credited
+        rescue StandardError
+          EMPTY
+        end
+
+        # `{write => names of the locals its value reads}` for each write whose value reads at least one local and no
+        # local the body writes.
+        def unwritten_reads(writes, written)
+          writes.each_with_object({}.compare_by_identity) do |write, acc|
+            names = parameter_reads(write.value)
+            next if names.nil? || names.empty? || names.any? { |name| written.include?(name) }
+
+            acc[write] = names
+          end
+        end
+
+        # The names of the locals `value` reads, or nil when it holds a block, a lambda or a scope barrier.
+        def parameter_reads(value, names = Set.new)
+          return names unless value.is_a?(Prism::Node)
+          return nil if BLOCK_NODES.any? { |klass| value.is_a?(klass) }
+          return nil if SCOPE_BARRIERS.any? { |klass| value.is_a?(klass) }
+
+          names << value.name if value.is_a?(Prism::LocalVariableReadNode)
+          value.rigor_each_child do |child|
+            return nil if parameter_reads(child, names).nil?
+          end
+          names
+        end
+
+        # A bare read takes the declared type itself; an expression over the parameters is typed with each bound to
+        # its declared type, unless {DerivedParamValue} declines it.
+        def value_type(value, names, types, def_node, scope)
+          return types[value.name] if value.is_a?(Prism::LocalVariableReadNode)
+          return nil if DerivedParamValue.declined?(names, types, def_node, scope)
+
+          bound = names.reduce(scope) { |acc, name| acc.with_local(name, types[name]) }
+          return nil if DerivedParamValue.overload_sensitive_argument?(value, bound)
+
+          bound.type_of(value)
+        rescue StandardError
+          nil
+        end
+
+        # Collects the `@x = …` writes outside every block, and the name of every local the body writes in
+        # any form at any depth. A read at depth zero outside a block names the method's own local, which is the
+        # parameter when the body never writes the name.
+        #
+        # Answers `:opaque` when the body can rewrite a local through code the scan cannot read: a `binding` call, or
+        # an `eval`-family call given an argument ({OPAQUE_EVAL_CALLS}).
+        def scan(node, written, writes, in_block:)
+          return unless node.is_a?(Prism::Node)
+          return if SCOPE_BARRIERS.any? { |klass| node.is_a?(klass) }
+
+          case node
+          when Prism::LocalVariableWriteNode, Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+               Prism::LocalVariableOperatorWriteNode, Prism::LocalVariableTargetNode
+            written << node.name
+          when Prism::CallNode
+            return :opaque if opaque_call?(node)
+          end
+          writes << node if !in_block && node.is_a?(Prism::InstanceVariableWriteNode)
+          inner = in_block || BLOCK_NODES.any? { |klass| node.is_a?(klass) }
+          node.rigor_each_child do |child|
+            return :opaque if scan(child, written, writes, in_block: inner) == :opaque
+          end
+          nil
+        end
+
+        # `binding` hands the frame's locals to code that may write them (`binding.eval("x = 's'")`,
+        # `Helper.rw(binding)`); a string passed to an `eval`-family call is code the scan cannot read.
+        def opaque_call?(node)
+          return true if node.name == :binding
+
+          OPAQUE_EVAL_CALLS.include?(node.name) && !(node.arguments&.arguments || []).empty?
+        end
+
+        # The declared, non-`untyped` type of each parameter, or `{}` when a gate declines the method.
+        def declared_types(def_node, class_name, scope)
+          environment = scope&.environment
+          return {} if environment.nil?
+          return {} if environment.rbs_module?(class_name)
+          return {} unless Reflection.project_declared_class?(class_name, environment: environment)
+
+          rbs_method = Reflection.instance_method_definition(class_name, def_node.name, environment: environment)
+          return {} unless sole_typed_overload?(rbs_method, class_name)
+
+          binder = MethodParameterBinder.new(environment: environment, class_path: class_name, singleton: false)
+          binder.bind(def_node).reject { |_name, type| type.is_a?(Type::Dynamic) }
+        end
+
+        def sole_typed_overload?(rbs_method, class_name)
+          return false if rbs_method.nil? || rbs_method.defined_in.to_s.delete_prefix("::") != class_name
+
+          method_types = rbs_method.method_types
+          return false unless method_types.size == 1
+
+          function = method_types.first.type
+          function.respond_to?(:required_positionals) && function.free_variables.empty?
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/scope_indexer/derived_param_value.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../acceptance"
+
+module Rigor
+  module Inference
+    module ScopeIndexer
+      # Issue #2321 — the declines {DeclaredParamWrites} applies to a write whose value is an expression over declared
+      # parameters, beyond the ones a bare read (`@x = x`) shares. Each says the expression's type, evaluated with the
+      # parameters bound to their declared types, may not be the type the ivar holds at runtime:
+      #
+      # - a parameter whose declared type holds `untyped` at any depth (`Array[untyped]`, #2325): the answer is built
+      #   on the part the author left untyped;
+      # - an optional parameter whose default value's type is not within its declared type
+      #   (`def initialize(x = nil)` under `(?Integer x)`): the value may run on the default, which the binding does not
+      #   carry;
+      # - an argument of any call in the value (`a + b`, `a + (b > 0 ? b : 0.5)`, `a[i]`, `Array(x)`, `super(…)`,
+      #   `yield(…)`), typed under the parameter bindings, whose type is anything but a literal or an instance of a
+      #   class no RBS class names as its superclass: the engine picks the first overload such an argument matches
+      #   (`Integer#+` given `Integer | Float` answers `Integer`), not the join of every overload it may reach. A
+      #   receiver dispatches per member and is not declined. A splat or keyword argument types as neither, so it
+      #   declines too.
+      module DerivedParamValue
+        module_function
+
+        # Whether a write over the parameters `names`, declared `types`, is not credited for a parameter it reads.
+        def declined?(names, types, def_node, scope)
+          names.any? do |name|
+            carries_dynamic?(types[name]) || default_outside?(def_node, name, types[name], scope)
+          end
+        end
+
+        # Whether a call in `value` takes an argument whose type, under the parameter bindings of `bound`, may match an
+        # overload narrower than itself.
+        def overload_sensitive_argument?(value, bound)
+          return false unless value.is_a?(Prism::Node)
+
+          if value.is_a?(Prism::CallNode) || value.is_a?(Prism::SuperNode) || value.is_a?(Prism::YieldNode)
+            arguments = value.arguments&.arguments || []
+            return true if arguments.any? { |argument| overload_sensitive?(bound.type_of(argument), bound) }
+          end
+          value.rigor_each_child { |child| return true if overload_sensitive_argument?(child, bound) }
+          false
+        end
+
+        def carries_dynamic?(type)
+          case type
+          when Type::Dynamic then true
+          when Type::Union, Type::Intersection then type.members.any? { |member| carries_dynamic?(member) }
+          when Type::Nominal then type.type_args.any? { |arg| carries_dynamic?(arg) }
+          when Type::Tuple then type.elements.any? { |element| carries_dynamic?(element) }
+          when Type::HashShape then type.pairs.each_value.any? { |pair_value| carries_dynamic?(pair_value) }
+          # No RBS parameter spelling yields a refinement over `untyped`; the arm keeps the walk total.
+          when Type::Difference, Type::Refined then carries_dynamic?(type.base)
+          else false
+          end
+        end
+
+        # Whether an argument of this declared type may match an overload narrower than itself.
+        def overload_sensitive?(type, scope)
+          case type
+          when Type::Constant then false
+          when Type::Nominal then !leaf_class?(type.class_name, scope&.environment)
+          else true
+          end
+        end
+
+        def leaf_class?(class_name, environment)
+          return false if environment.nil? || environment.rbs_module?(class_name)
+          # A guard: a validated RBS signature names no unknown class, so this answers only for a broken environment.
+          return false unless environment.class_known?(class_name)
+
+          superclasses = environment.rbs_loader&.superclass_names
+          return false if superclasses.nil? || superclasses.empty?
+
+          !superclasses.include?(class_name.delete_prefix("::"))
+        end
+
+        # Whether `name` is an optional parameter of `def_node` whose default value's type is not within `declared`.
+        def default_outside?(def_node, name, declared, scope)
+          default = default_value(def_node.parameters, name)
+          return false if default.nil?
+
+          default_type = scope.type_of(default)
+          return true if carries_dynamic?(default_type)
+
+          !Acceptance.accepts(declared, default_type).yes? && !empty_collection_within?(declared, default_type)
+        end
+
+        # An empty `[]` or `{}` default is within any `Array[T]` or `Hash[K, V]` the declaration names, which the
+        # acceptance check answers only `maybe` (the empty literal has no element type to compare).
+        def empty_collection_within?(declared, default_type)
+          collection =
+            if default_type.is_a?(Type::Tuple) && default_type.elements.empty? then "Array"
+            elsif default_type.is_a?(Type::HashShape) && default_type.pairs.empty? then "Hash"
+            end
+          return false if collection.nil?
+
+          members = declared.is_a?(Type::Union) ? declared.members : [declared]
+          members.any? { |member| member.is_a?(Type::Nominal) && member.class_name == collection }
+        end
+
+        def default_value(parameters, name)
+          candidates = parameters.optionals + parameters.keywords
+          candidates.find { |param| param.respond_to?(:value) && param.name == name }&.value
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/scope_indexer/empty_seed.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module ScopeIndexer
+      # Issue #2499 — the accumulator idiom: a heap slot (an instance, class or global variable, or a constant)
+      # seeded with an empty literal and filled later, often from a method, a subclass, a mixin or another file
+      # the census cannot see. The seed is never proof that the slot is still empty, so the census records it
+      # without its emptiness: `""` and `+""` as `String`, `[]` as `Array[untyped]`, `{}` as
+      # `Hash[untyped, untyped]`. `String.new`, `Array.new` and `Hash.new` already type as their nominal.
+      #
+      # Only the empty spellings count. A non-empty literal (`@order = "asc"`, `MODES = %w[a b]`,
+      # `@opts = { a: 1 }`) keeps its exact type: such slots are modes and config tables, and an RBS parameter
+      # typed `"asc" | "desc"` must still accept them. A local keeps its flow precision; this applies only where
+      # the census seeds a heap slot.
+      module EmptySeed
+        module_function
+
+        # `type` with its emptiness dropped when `node` is an empty seed literal, otherwise `type` itself.
+        def erase(node, type)
+          return type unless empty_seed?(node)
+
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          Type::Combinator.union(*members.map { |member| unpinned(member) })
+        end
+
+        # `{ name => value node }` for each leading target of a multiple assignment whose right-hand side is a literal
+        # list (`@a, @b = {}, []`), so each slot is erased from its own element. Empty for any other right-hand side.
+        def multi_write_values(node)
+          value = node.value
+          return EMPTY_VALUES unless value.is_a?(Prism::ArrayNode)
+
+          elements = value.elements
+          node.lefts.each_with_index.with_object({}) do |(target, index), values|
+            break values if index >= elements.size || elements[index].is_a?(Prism::SplatNode)
+            next unless target.respond_to?(:name)
+
+            values[target.name] = elements[index]
+          end
+        end
+
+        EMPTY_VALUES = {}.freeze
+        private_constant :EMPTY_VALUES
+
+        # A chained write (`@a = @b = ""`) stores the inner write's value in the outer slot too, so it is followed.
+        def empty_seed?(node)
+          case node
+          when Prism::StringNode then node.unescaped.empty?
+          when Prism::ArrayNode, Prism::HashNode then node.elements.empty?
+          when Prism::CallNode then copied_empty_seed?(node)
+          when *CHAINED_WRITES then empty_seed?(node.value)
+          else false
+          end
+        end
+
+        CHAINED_WRITES = [
+          Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode, Prism::ClassVariableWriteNode,
+          Prism::GlobalVariableWriteNode, Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
+        ].freeze
+        private_constant :CHAINED_WRITES
+
+        # `+""`, the unfrozen empty String the accumulator idiom spells under `# frozen_string_literal: true`, and a
+        # `.dup` of an empty seed (`"".dup`, `[].dup`, `{}.dup`).
+        def copied_empty_seed?(node)
+          return false unless node.arguments.nil? && node.block.nil?
+
+          case node.name
+          when :+@ then node.receiver.is_a?(Prism::StringNode) && node.receiver.unescaped.empty?
+          when :dup then empty_seed?(node.receiver)
+          else false
+          end
+        end
+
+        def unpinned(member)
+          case member
+          when Type::Constant
+            member.value.is_a?(String) && member.value.empty? ? Type::Combinator.nominal_of("String") : member
+          when Type::Tuple
+            if member.elements.empty?
+              Type::Combinator.nominal_of("Array",
+                                          type_args: [Type::Combinator.untyped])
+            else
+              member
+            end
+          when Type::HashShape
+            return member unless member.pairs.empty?
+
+            Type::Combinator.nominal_of("Hash", type_args: [Type::Combinator.untyped, Type::Combinator.untyped])
+          else member
+          end
+        end
+        private_class_method :copied_empty_seed?, :unpinned
+      end
+    end
+  end
+end

data/lib/rigor/inference/scope_indexer/ivar_contributions.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "../../analysis/dependency_recorder"
+require_relative "../../run_scoped_slots"
+require_relative "../../type"
+require_relative "../refined_dispatch/own_method"
+
+module Rigor
+  module Inference
+    module ScopeIndexer
+      # Issues #2079 and #2170 — the instance-side ivar writes the class-ivar census of one file does not walk, joined
+      # into the ivars that census already holds for a class `K`:
+      #
+      # - the writes another file's reopening of `K` makes;
+      # - the writes of every project module and superclass on `K`'s instance resolution chain (`include`,
+      #   `prepend`, transitively, and `<`), from this file's own census of that ancestor where it declares one
+      #   (`writes`, taken before the read-before-write `nil` is added, so an ancestor's `initialize` exempts nothing
+      #   and its read-before-write adds nothing, and only for an ivar an instance body of the ancestor writes in this
+      #   file) and from every other file's entries for it.
+      #
+      # Another file's write comes from its `[:own_write_type, owner, ivar, value, path]` census entry
+      # ({IvarWriterCensus}): a literal joins as its `Constant`, anything else as `Dynamic[top]`. An ivar the census
+      # has no entry for gains none, so a read of an ivar only another file writes still reads `Dynamic[top]`. The
+      # join only widens, and every joined type is in the seed, so a `nil` it brings is declaration-sourced (ADR-58
+      # WD1). A file the scope names no path for (a census built outside the project pre-pass, `rigor sig-gen`'s
+      # unseeded scopes) joins nothing.
+      #
+      # ADR-46: each ivar read files `own_write_type:<owner>#<ivar>` for `K` and each chain owner, which the
+      # incremental session fires when a file's entries for the pair appear, vanish or change value; and the chain
+      # files its class edges ({Scope::ResolutionChain#record}), so an `include` added or removed re-checks the reader.
+      module IvarContributions
+        TABLE_KEY = RunScopedSlots.register(:__rigor_ivar_contributions_table__)
+        EMPTY = {}.freeze
+        private_constant :TABLE_KEY, :EMPTY
+
+        module_function
+
+        def join!(accumulator, writes, scope)
+          path = scope.source_path
+          return if path.nil?
+
+          path = canonical(path)
+
+          table = table(scope.discovered_global_write_census)
+          accumulator.each do |class_name, entries|
+            next unless class_name.is_a?(String) && !entries.empty?
+
+            owners = chain_owners(scope, class_name)
+            entries.each_key do |ivar|
+              joined = contributed(owners, class_name, ivar, table, writes, path)
+              entries[ivar] = Type::Combinator.union(entries[ivar], joined) if joined
+            end
+          end
+        end
+
+        # `K` and the project classes and modules on its instance chain, in chain order, with their class edges filed.
+        # A module's own census takes no chain: its ancestors' writes land on whatever includes it.
+        def chain_owners(scope, class_name)
+          return [class_name] if RefinedDispatch::OwnMethod.module_name?(scope, class_name)
+
+          chain = Scope::ResolutionChain.for(scope, class_name, :instance, :methods)
+          # A guard: the class body's own `include` / `<` resolution already files these edges; kept so the read
+          # states its own dependency.
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          ancestors = chain.entries.filter_map do |entry|
+            # An external entry has no name, so `filter_map` drops it. The side check is a guard: an instance chain
+            # holds only instance-side entries.
+            entry.name if entry.side == :instance && entry.name != class_name
+          end
+          [class_name, *ancestors.uniq]
+        rescue StandardError
+          [class_name]
+        end
+
+        # The union of what the owners contribute to `ivar`, or nil for nothing.
+        def contributed(owners, class_name, ivar, table, writes, path)
+          types = []
+          owners.each do |owner|
+            if Analysis::DependencyRecorder.active?
+              Analysis::DependencyRecorder.read_name(:own_write_type, "#{owner}##{ivar}")
+            end
+            by_path = table.dig(owner, ivar) || EMPTY
+            # This file's census of an ancestor counts only an ivar an instance body of it writes here: the census
+            # also holds a `def self.` write of a module (#1958), which runs on the module object.
+            own = writes.dig(owner, ivar) if owner != class_name && by_path.key?(path)
+            types << own if own
+            by_path.each do |value_path, values|
+              next if value_path == path
+
+              values.each { |value| types << value_type(value) }
+            end
+          end
+          types.empty? ? nil : Type::Combinator.union(*types)
+        end
+
+        # A String literal joins as `String`, not its `Constant`: a write elsewhere cannot see an in-place mutation of
+        # the String (`@s << "abc"`) in this file, in another or in an ancestor, so the value would be pinned too
+        # narrowly. Every other literal kind is immutable and joins as its `Constant`.
+        def value_type(value)
+          return Type::Combinator.untyped unless value.is_a?(Array)
+
+          literal = value[1]
+          literal.is_a?(String) ? Type::Combinator.nominal_of("String") : Type::Combinator.constant_of(literal)
+        end
+
+        # `path` resolved through symlinks, so a file the pre-pass tagged under one spelling (`/tmp/…`) is the one
+        # analysed under another (`/private/tmp/…`); the expanded spelling when it cannot be resolved.
+        def canonical(path)
+          File.realpath(path)
+        rescue SystemCallError
+          File.expand_path(path)
+        end
+
+        # `{ owner => { ivar => { path => [value, ...] } } }` over `census`'s path-tagged `:own_write_type` entries,
+        # built once per census and kept in one run-scoped slot keyed by its identity.
+        def table(census)
+          slot = Thread.current[TABLE_KEY]
+          return slot[1] if slot && slot[0].equal?(census)
+
+          table = {}
+          canonical_paths = {}
+          census.each do |entry|
+            next unless entry.size == 5 && entry[0] == :own_write_type
+
+            by_path = ((table[entry[1]] ||= {})[entry[2]] ||= {})
+            (by_path[canonical_paths[entry[4]] ||= canonical(entry[4])] ||= []) << entry[3]
+          end
+          Thread.current[TABLE_KEY] = [census, table]
+          table
+        end
+        private_class_method :chain_owners, :contributed, :value_type, :canonical, :table
+      end
+    end
+  end
+end