rigortype 0.1.17 → 0.1.19

data/lib/rigor/inference/scope_indexer.rb

@@ -49,9 +49,14 @@ module Rigor
       # @param default_scope [Rigor::Scope] the scope used for the root,
       #   and the fallback returned for any Prism node not contained in
       #   `root`'s subtree.
+      # @param converged_loop_recording [Boolean] display-path flag —
+      #   when true the evaluator re-records fixpoint-tracked loop
+      #   bodies from their CONVERGED bindings so per-line probes
+      #   (`rigor annotate`) reflect the post-writeback state, not the
+      #   cap-N intermediate constants. Off for the check path.
       # @return [Hash{Prism::Node => Rigor::Scope}] identity-comparing
       #   table whose default value is `default_scope`.
-      def index(root, default_scope:) # rubocop:disable Metrics/AbcSize
+      def index(root, default_scope:, converged_loop_recording: false) # rubocop:disable Metrics/AbcSize
         # Slice A-declarations. Build the declaration overrides
         # first so every scope handed to the StatementEvaluator
         # already carries the table; structural sharing through
@@ -68,16 +73,17 @@ module Rigor
         # collision — same-file declarations are the most
         # specific authority.
         merged_classes = default_scope.discovered_classes.merge(discovered_classes)
-        seeded_scope = default_scope
-                       .with_declared_types(declared_types)
-                       .with_discovered_classes(merged_classes)
+        seeded_scope = default_scope.with_discovery(
+          default_scope.discovery.with(declared_types: declared_types,
+                                       discovered_classes: merged_classes)
+        )
 
         # Slice 7 phase 2. Pre-pass over every class/module body
         # to collect the per-class ivar accumulator. Seeded after
         # declared_types so the rvalue typer in the pre-pass can
         # see declaration overrides.
         class_ivars = build_class_ivar_index(root, seeded_scope)
-        seeded_scope = seeded_scope.with_class_ivars(class_ivars)
+        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(class_ivars: class_ivars))
 
         # Slice 7 phase 6. Same pre-pass shape for cvars (per
         # class) and globals (program-wide). Globals are also
@@ -86,9 +92,9 @@ module Rigor
         # not enter a method body) observe the precise type
         # without consulting the accumulator on every lookup.
         class_cvars = build_class_cvar_index(root, seeded_scope)
-        seeded_scope = seeded_scope.with_class_cvars(class_cvars)
+        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(class_cvars: class_cvars))
         program_globals = build_program_global_index(root, seeded_scope)
-        seeded_scope = seeded_scope.with_program_globals(program_globals)
+        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(program_globals: program_globals))
         program_globals.each { |name, type| seeded_scope = seeded_scope.with_global(name, type) }
 
         # Slice 7 phase 9. In-source constant value tracking.
@@ -99,7 +105,9 @@ module Rigor
         # references resolve correctly. Multiple writes to the
         # same qualified name union via `Type::Combinator.union`.
         in_source_constants = build_in_source_constants(root, seeded_scope)
-        seeded_scope = seeded_scope.with_in_source_constants(in_source_constants)
+        seeded_scope = seeded_scope.with_discovery(
+          seeded_scope.discovery.with(in_source_constants: in_source_constants)
+        )
 
         # Slice 7 phase 12. In-source method discovery. Walks
         # every class/module body for `Prism::DefNode` and
@@ -115,7 +123,7 @@ module Rigor
         discovered_methods = deep_merge_class_methods(
           default_scope.discovered_methods, build_discovered_methods(root)
         )
-        seeded_scope = seeded_scope.with_discovered_methods(discovered_methods)
+        seeded_scope = seeded_scope.with_discovery(seeded_scope.discovery.with(discovered_methods: discovered_methods))
 
         # v0.0.2 #5 + ADR-24 slice 2 — record per-instance-method
         # def nodes, the class -> superclass map, and the
@@ -143,7 +151,8 @@ module Rigor
         # entry is the one that reflects all flow-derived
         # rebinds, so it MUST overwrite the first.
         on_enter = ->(node, scope) { table[node] = scope }
-        StatementEvaluator.new(scope: seeded_scope, on_enter: on_enter).evaluate(root)
+        StatementEvaluator.new(scope: seeded_scope, on_enter: on_enter,
+                               converged_loop_recording: converged_loop_recording).evaluate(root)
 
         propagate(root, table, seeded_scope)
         table
@@ -161,6 +170,9 @@ module Rigor
         def_nodes = default_scope.discovered_def_nodes.merge(
           build_discovered_def_nodes(root)
         ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
+        singleton_def_nodes = default_scope.discovered_singleton_def_nodes.merge(
+          build_discovered_singleton_def_nodes(root)
+        ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
         superclasses = default_scope.discovered_superclasses.merge(
           build_discovered_superclasses(root)
         )
@@ -179,12 +191,16 @@ module Rigor
           build_data_member_layouts(root)
         )
 
-        seeded_scope
-          .with_discovered_def_nodes(def_nodes)
-          .with_discovered_superclasses(superclasses)
-          .with_discovered_includes(includes)
-          .with_discovered_method_visibilities(method_visibilities)
-          .with_data_member_layouts(data_member_layouts)
+        seeded_scope.with_discovery(
+          seeded_scope.discovery.with(
+            discovered_def_nodes: def_nodes,
+            discovered_singleton_def_nodes: singleton_def_nodes,
+            discovered_superclasses: superclasses,
+            discovered_includes: includes,
+            discovered_method_visibilities: method_visibilities,
+            data_member_layouts: data_member_layouts
+          )
+        )
       end
 
       # Slice 7 phase 2. Builds the class-level ivar accumulator
@@ -204,8 +220,15 @@ module Rigor
         mutated_ivars = {}
         read_before_write = {}
         init_writes = {}
+        # WD3 — per-class summary of `{class_name => {method_name =>
+        # Set<ivar names definitely assigned non-nil on every
+        # completing path>}}`, consulted by `dead_transient_nil_writes`
+        # so a ctor that reassigns `@x` indirectly through an
+        # unconditional same-class method call (`mask!`) credits the
+        # overwrite. Built once per program here, memoised by class.
+        method_assign_effects = build_method_assign_effects(root)
         walk_class_ivars(root, [], default_scope, accumulator, mutated_ivars,
-                         read_before_write, init_writes)
+                         read_before_write, init_writes, method_assign_effects)
         widen_mutated_ivar_entries!(accumulator, mutated_ivars)
         contribute_read_before_write_nil!(accumulator, read_before_write, init_writes)
         accumulator.transform_values(&:freeze).freeze
@@ -328,8 +351,8 @@ module Rigor
         end
       end
 
-      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars,
-                           read_before_write = nil, init_writes = nil)
+      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars, # rubocop:disable Metrics/CyclomaticComplexity,Metrics/ParameterLists
+                           read_before_write = nil, init_writes = nil, method_assign_effects = nil)
         return unless node.is_a?(Prism::Node)
 
         case node
@@ -355,24 +378,31 @@ module Rigor
               # read.
               collect_class_body_ivar_writes(node.body, child_prefix.join("::"), init_writes) if init_writes
               walk_class_ivars(node.body, child_prefix, default_scope, accumulator,
-                               mutated_ivars, read_before_write, init_writes)
+                               mutated_ivars, read_before_write, init_writes, method_assign_effects)
             end
             return
           end
         when Prism::DefNode
           collect_def_ivar_writes(node, qualified_prefix, default_scope, accumulator,
-                                  mutated_ivars, read_before_write, init_writes)
+                                  mutated_ivars, read_before_write, init_writes, method_assign_effects)
           return
+        when Prism::CallNode
+          if init_writes && !qualified_prefix.empty? &&
+             node.block.is_a?(Prism::BlockNode) &&
+             block_initializer?(qualified_prefix.join("::"), node.name, default_scope)
+            collect_block_ivar_writes(node.block, qualified_prefix, default_scope,
+                                      accumulator, mutated_ivars, init_writes)
+          end
         end
 
         node.compact_child_nodes.each do |child|
           walk_class_ivars(child, qualified_prefix, default_scope, accumulator,
-                           mutated_ivars, read_before_write, init_writes)
+                           mutated_ivars, read_before_write, init_writes, method_assign_effects)
         end
       end
 
-      def collect_def_ivar_writes(def_node, qualified_prefix, default_scope, accumulator, mutated_ivars,
-                                  read_before_write = nil, init_writes = nil)
+      def collect_def_ivar_writes(def_node, qualified_prefix, default_scope, accumulator, mutated_ivars, # rubocop:disable Metrics/ParameterLists
+                                  read_before_write = nil, init_writes = nil, method_assign_effects = nil)
         return if def_node.body.nil? || qualified_prefix.empty?
 
         class_name = qualified_prefix.join("::")
@@ -386,7 +416,23 @@ module Rigor
           end
         body_scope = default_scope.with_self_type(self_type)
 
-        gather_ivar_writes(def_node.body, body_scope, class_name, accumulator, EMPTY_GUARDED_IVARS, mutated_ivars)
+        # C2 — transient `@x = nil` dead-write elimination. When a
+        # method body opens with an unconditional `@x = nil`
+        # (defensive init) and then *definitely* reassigns `@x` to a
+        # non-nil value on every completing path (a later
+        # unconditional statement-level write, OR an `if/else` whose
+        # both branches write `@x`), the opening nil is dead — it can
+        # never be observed at method exit. Recording it anyway folds
+        # a spurious `nil` constituent into the flow-insensitive
+        # class-ivar union, which then poisons reads in OTHER methods
+        # (e.g. ipaddr `IN4MASK ^ @mask_addr` rejects the resulting
+        # `Integer | nil`). The set holds the `object_id`s of the
+        # transient write nodes to skip; soundness is post-domination
+        # at the top statement level, so dropping the nil never hides
+        # a real runtime-nil read.
+        dead_writes = dead_transient_nil_writes(def_node.body, class_name, method_assign_effects)
+        gather_ivar_writes(def_node.body, body_scope, class_name, accumulator,
+                           EMPTY_GUARDED_IVARS, mutated_ivars, dead_writes)
 
         # B2.3 — collect per-method evidence for the read-before-
         # write nil contribution. The accumulator-level decision
@@ -399,6 +445,53 @@ module Rigor
         collect_read_before_write_evidence(def_node, class_name, read_before_write, init_writes, default_scope)
       end
 
+      # ADR-38 block-form: collects ivar writes from a CallNode's
+      # block body (e.g. RSpec `before { @x = … }` / `let(:x) { … }`)
+      # and folds them into `init_writes`, suppressing the
+      # read-before-write nil contribution the same way a def-form
+      # initializer does. The block body is always treated as an
+      # initializer (the caller has already verified the method name
+      # is declared as a block_method initializer), so there is no
+      # read-before-write evidence collection step here.
+      def collect_block_ivar_writes(block_node, qualified_prefix, default_scope, accumulator,
+                                    mutated_ivars, init_writes)
+        return if block_node.body.nil? || qualified_prefix.empty?
+
+        class_name = qualified_prefix.join("::")
+        self_type = Type::Combinator.nominal_of(class_name)
+        body_scope = default_scope.with_self_type(self_type)
+
+        gather_ivar_writes(block_node.body, body_scope, class_name, accumulator,
+                           EMPTY_GUARDED_IVARS, mutated_ivars)
+
+        seen_writes = Set.new
+        read_first = Set.new
+        detect_read_before_write(block_node.body, seen_writes, read_first)
+        init_set = (init_writes[class_name] ||= Set.new)
+        seen_writes.each { |name| init_set << name }
+      end
+
+      # ADR-38 block-form gate: true when a loaded plugin declares
+      # `method_name` a block-form initializer for `class_name` (or
+      # an ancestor). Mirrors `additional_initializer?` but queries
+      # `covers_block_method?` instead of `covers_method?`.
+      def block_initializer?(class_name, method_name, default_scope)
+        return false if class_name.nil? || default_scope.nil?
+
+        environment = default_scope.environment
+        registry = environment&.plugin_registry
+        return false if registry.nil?
+        return false if registry.respond_to?(:empty?) && registry.empty?
+        return false unless registry.respond_to?(:additional_initializers)
+
+        registry.additional_initializers.any? do |entry|
+          entry.covers_block_method?(method_name) &&
+            class_matches_constraint?(class_name, entry.receiver_constraint, environment)
+        end
+      rescue StandardError
+        false
+      end
+
       # Walks the method body in AST (== execution) order
       # tracking ivar names whose first reference is a read.
       # The set is unioned into the class-wide
@@ -529,13 +622,29 @@ module Rigor
       private_constant :EMPTY_GUARDED_IVARS
 
       def gather_ivar_writes(node, scope, class_name, accumulator, guarded_ivars = EMPTY_GUARDED_IVARS,
-                             mutated_ivars = nil)
+                             mutated_ivars = nil, dead_writes = nil)
         return unless node.is_a?(Prism::Node)
 
-        if node.is_a?(Prism::InstanceVariableWriteNode)
+        if node.is_a?(Prism::InstanceVariableWriteNode) &&
+           !(dead_writes && dead_writes.include?(node.object_id))
           record_ivar_write(node, scope, class_name, accumulator,
                             guarded: guarded_ivars.include?(node.name))
         end
+
+        # N1 — parallel / multiple assignment (`old, @cb = @cb, block`,
+        # `@i, @o, @e, @thr = Open3.popen3(cmd)`). A direct
+        # `InstanceVariableWriteNode` is the only write form this
+        # collector handled, so an ivar appearing as a `MultiWriteNode`
+        # target was silently dropped from the class-ivar union — leaving
+        # it to seed as pure `nil` (from a sibling `@cb = nil` ctor write,
+        # or absent entirely) and false-fire `if @cb` always-falsey /
+        # `@thr.alive?` undefined-for-nil. Record each ivar target with
+        # its tuple-position RHS type where the RHS is array/tuple-shaped,
+        # else the unanalyzable floor (the same `Dynamic[top]` a single
+        # write to an unknown RHS records — an unanalyzable multi-write
+        # means unknown, not nil).
+        record_multi_write_ivars(node, scope, class_name, accumulator)
+
         record_ivar_mutator_call(node, class_name, mutated_ivars) if mutated_ivars && node.is_a?(Prism::CallNode)
 
         # Don't recurse into nested defs, classes, or modules; their
@@ -543,12 +652,13 @@ module Rigor
         return if IVAR_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
         if node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
-          walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+          walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars,
+                                       mutated_ivars, dead_writes)
           return
         end
 
         node.compact_child_nodes.each do |c|
-          gather_ivar_writes(c, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+          gather_ivar_writes(c, scope, class_name, accumulator, guarded_ivars, mutated_ivars, dead_writes)
         end
       end
 
@@ -586,16 +696,22 @@ module Rigor
       # reads of `@x` would then surface a nil-receiver FP. The
       # ELSE branch is left ungarded so those reads continue to type
       # as they did before this fix.
-      def walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars, mutated_ivars = nil)
+      def walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars,
+                                       mutated_ivars = nil, dead_writes = nil)
         then_guards = then_body_guarded_ivars(node)
         then_guarded = then_guards.empty? ? guarded_ivars : (guarded_ivars | then_guards)
 
-        gather_ivar_writes(node.predicate, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+        gather_ivar_writes(node.predicate, scope, class_name, accumulator, guarded_ivars,
+                           mutated_ivars, dead_writes)
         if node.statements
-          gather_ivar_writes(node.statements, scope, class_name, accumulator, then_guarded, mutated_ivars)
+          gather_ivar_writes(node.statements, scope, class_name, accumulator, then_guarded,
+                             mutated_ivars, dead_writes)
         end
         branch = node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause
-        gather_ivar_writes(branch, scope, class_name, accumulator, guarded_ivars, mutated_ivars) if branch
+        return unless branch
+
+        gather_ivar_writes(branch, scope, class_name, accumulator, guarded_ivars,
+                           mutated_ivars, dead_writes)
       end
 
       # Returns the set of ivar names that, in the THEN body of this
@@ -663,6 +779,332 @@ module Rigor
         end
       end
 
+      # C2 — returns a Set of `object_id`s for transient `@x = nil`
+      # writes that a later statement in the same method body
+      # *definitely* overwrites with a non-nil value on every
+      # completing path. Such a nil can never be the ivar's value at
+      # method exit, so it must not contribute a `nil` constituent to
+      # the (flow-insensitive) class-ivar union.
+      #
+      # Scope is deliberately narrow and post-domination-sound:
+      #   - only the top-level statement sequence of the body is
+      #     considered (no writes hidden inside loops / rescue / nested
+      #     conditionals count as the "definite" overwrite, except the
+      #     one structured `if/else` form below);
+      #   - the killing statement is either an unconditional
+      #     statement-level `@x = <non-nil>`, OR an `if/else` (with a
+      #     real `else`) where BOTH branches' final top-level write to
+      #     `@x` is non-nil. Both shapes overwrite `@x` on every path;
+      #   - only `@x = nil` literal writes are ever marked dead — a
+      #     non-nil transient is left untouched (it is already
+      #     precision-additive in the union).
+      # WD3 — ADR-41-style hard cap on how deep the same-class-call
+      # definite-assignment crediting recurses (the ctor calls
+      # `mask!`, which could itself call another same-class helper).
+      # Cycle-guarded independently; the cap bounds even acyclic
+      # chains.
+      SAME_CLASS_CALL_DEPTH_CAP = 3
+      private_constant :SAME_CLASS_CALL_DEPTH_CAP
+
+      # WD3 — builds the per-class definite-assignment summary
+      # `{class_name => {method_name => Set<ivar names assigned
+      # non-nil on every completing path>}}`. Used so a ctor's
+      # `dead_transient_nil_writes` can credit an indirect overwrite
+      # through an unconditionally-called same-class method (ipaddr's
+      # `initialize` reassigns `@mask_addr` via `mask!`).
+      #
+      # Each method's set is computed by the same suffix
+      # definite-assignment analysis used for the ctor seed, run from
+      # the method body's first statement for every ivar the method
+      # writes anywhere. Same-class calls inside a method are credited
+      # transitively (depth-capped, cycle-guarded) so the resulting
+      # FLAT table is correct at depth 0 for the ctor lookup.
+      def build_method_assign_effects(root)
+        defs = collect_class_method_defs(root)
+        effects = {}
+        memo = {}.compare_by_identity
+        defs.each do |class_name, methods|
+          methods.each do |method_name, def_node|
+            assigns = method_definite_assigns(class_name, method_name, def_node, defs, effects, memo, 0)
+            (effects[class_name] ||= {})[method_name] = assigns unless assigns.empty?
+          end
+        end
+        effects.freeze
+      end
+
+      # Collects `{class_name => {method_name => DefNode}}` for every
+      # instance-method def in the program. Singleton defs (`def
+      # self.x`) are excluded — the ctor-call crediting only follows
+      # instance-method calls on `self`. Last def wins on redefinition.
+      def collect_class_method_defs(root, prefix = [], acc = {})
+        return acc unless root.is_a?(Prism::Node)
+
+        case root
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(root.constant_path)
+          if name && root.body
+            child = prefix + [name]
+            collect_class_method_defs(root.body, child, acc)
+          end
+          return acc
+        when Prism::DefNode
+          (acc[prefix.join("::")] ||= {})[root.name] = root unless prefix.empty? || root.receiver
+          return acc
+        end
+
+        root.compact_child_nodes.each { |c| collect_class_method_defs(c, prefix, acc) }
+        acc
+      end
+
+      # Computes the definite-assignment set for one method, memoised
+      # per def node. The `memo` cycle-guards: a method re-entered
+      # while its own summary is in progress contributes nothing
+      # (sound under-approximation), so mutual recursion terminates.
+      def method_definite_assigns(class_name, _method_name, def_node, defs, effects, memo, depth)
+        return Set.new if def_node.body.nil?
+        return memo[def_node] if memo.key?(def_node)
+        return Set.new if depth >= SAME_CLASS_CALL_DEPTH_CAP
+
+        memo[def_node] = Set.new # in-progress sentinel (cycle guard)
+        statements = top_level_statements(def_node.body)
+        candidates = ivar_write_targets(def_node.body)
+        # A transient `@x = nil` opener whose own method reassigns it
+        # later must still count `@x` as assigned for callers, so the
+        # crediting is computed at the BUILD-time depth.
+        resolver = MethodEffectResolver.new(self, class_name, defs, effects, memo, depth)
+        assigns = Set.new
+        candidates.each do |ivar|
+          assigns << ivar if suffix_definitely_assigns_with_resolver?(statements, 0, ivar, class_name, resolver, depth)
+        end
+        memo[def_node] = assigns
+      end
+
+      # Every ivar this body assigns a non-nil value to ANYWHERE (the
+      # candidate set for the method's definite-assignment scan).
+      def ivar_write_targets(node, acc = Set.new)
+        return acc unless node.is_a?(Prism::Node)
+
+        acc << node.name if node.is_a?(Prism::InstanceVariableWriteNode) && !nil_literal_value?(node.value)
+        node.compact_child_nodes.each { |c| ivar_write_targets(c, acc) }
+        acc
+      end
+
+      # Build-time variant of `suffix_definitely_assigns?` that resolves
+      # same-class calls through the lazy `resolver` (which recurses
+      # into `method_definite_assigns` for not-yet-computed callees)
+      # rather than the finished flat table.
+      def suffix_definitely_assigns_with_resolver?(statements, from, target, class_name, resolver, depth)
+        statements[from..].each do |stmt|
+          outcome = statement_assignment_outcome(stmt, target, class_name, resolver, depth, nil)
+          return true if outcome == :assigned
+          return false if outcome == :terminates_unassigned
+        end
+        false
+      end
+
+      # Adapts `effects.dig(class, method)` for build-time crediting:
+      # when the callee summary is not yet in the flat table, compute
+      # it on demand (depth+1) via `method_definite_assigns`.
+      class MethodEffectResolver
+        def initialize(indexer, class_name, defs, effects, memo, depth)
+          @indexer = indexer
+          @class_name = class_name
+          @defs = defs
+          @effects = effects
+          @memo = memo
+          @depth = depth
+        end
+
+        def dig(class_name, method_name)
+          existing = @effects.dig(class_name, method_name)
+          return existing if existing
+
+          def_node = @defs.dig(class_name, method_name)
+          return nil if def_node.nil?
+
+          @indexer.send(:method_definite_assigns, class_name, method_name, def_node, @defs, @effects, @memo,
+                        @depth + 1)
+        end
+      end
+
+      def dead_transient_nil_writes(body, class_name = nil, method_assign_effects = nil)
+        statements = top_level_statements(body)
+        return nil if statements.length < 2
+
+        dead = nil
+
+        statements.each_with_index do |stmt, i|
+          next unless stmt.is_a?(Prism::InstanceVariableWriteNode) && nil_literal_value?(stmt.value)
+
+          # The opening `@x = nil` is dead when every completing path
+          # of the SUFFIX after it (normal end OR early `return`,
+          # never a `raise`-terminated path) definitely reassigns
+          # `@x` non-nil. The suffix analysis credits an
+          # unconditionally-called same-class method's own definite
+          # assignments via `method_assign_effects`.
+          if suffix_definitely_assigns?(statements, i + 1, stmt.name, class_name, method_assign_effects)
+            (dead ||= Set.new) << stmt.object_id
+          end
+        end
+
+        dead
+      end
+
+      def top_level_statements(body)
+        return [] if body.nil?
+        return body.body if body.is_a?(Prism::StatementsNode)
+
+        [body]
+      end
+
+      def nil_literal_value?(node)
+        node.is_a?(Prism::NilNode)
+      end
+
+      # True when, starting from `statements[from]`, EVERY path that
+      # completes the method (falls off the end OR hits an early
+      # `return`) definitely assigns `target` a non-nil value first.
+      # Paths terminated by `raise` are not completing paths and are
+      # ignored (they never observe the ivar at method exit). A path
+      # that can fall through `statements` without assigning fails.
+      def suffix_definitely_assigns?(statements, from, target, class_name, effects)
+        statements[from..].each do |stmt|
+          outcome = statement_assignment_outcome(stmt, target, class_name, effects, 0, nil)
+          # The statement assigned on every continuing path -> the
+          # suffix is satisfied no matter what follows.
+          return true if outcome == :assigned
+          # The statement terminates control here (return/raise) and
+          # the value it carried did not assign on every path -> some
+          # completing path reached exit without the assignment.
+          return false if outcome == :terminates_unassigned
+          # Otherwise (:falls_through_unassigned) keep scanning the
+          # remaining statements.
+        end
+        # Fell off the end with no definite assignment.
+        false
+      end
+
+      # Classifies a single statement's effect on `target`:
+      #   :assigned                 — every path through the statement
+      #                               that continues OR returns assigns
+      #                               `target` non-nil (suffix is done);
+      #   :terminates_unassigned    — the statement ends the method
+      #                               (return/raise) on some path
+      #                               without a definite assignment, so
+      #                               a completing path escaped;
+      #   :falls_through_unassigned — control may continue past it
+      #                               without the assignment (keep
+      #                               scanning the suffix).
+      def statement_assignment_outcome(stmt, target, class_name, effects, depth, visiting)
+        case stmt
+        when Prism::InstanceVariableWriteNode
+          return :falls_through_unassigned if stmt.name != target
+
+          nil_literal_value?(stmt.value) ? :falls_through_unassigned : :assigned
+        when Prism::CallNode
+          if unconditional_call_assigns?(stmt, target, class_name, effects, depth, visiting)
+            :assigned
+          else
+            :falls_through_unassigned
+          end
+        when Prism::IfNode, Prism::UnlessNode
+          conditional_assignment_outcome(stmt, target, class_name, effects, depth, visiting)
+        when Prism::CaseNode
+          case_assignment_outcome(stmt, target, class_name, effects, depth, visiting)
+        when Prism::ReturnNode
+          :terminates_unassigned
+        else
+          # Any other statement — including a bare `raise`/`fail`,
+          # which terminates without a completing path that observes
+          # the seed nil — is neutral: control either continues or the
+          # path never reaches method exit. Keep scanning the suffix.
+          :falls_through_unassigned
+        end
+      end
+
+      # True when a branch body (a StatementsNode / single node)
+      # definitely assigns `target` non-nil on every path that
+      # completes the method through it, OR terminates every path by
+      # raise (vacuously safe — no completing path observes the seed
+      # nil). Returns false if any path can complete/return without the
+      # assignment.
+      def branch_definitely_assigns?(branch, target, class_name, effects, depth, visiting)
+        stmts = top_level_statements(branch)
+        return false if stmts.empty?
+
+        stmts.each do |stmt|
+          outcome = statement_assignment_outcome(stmt, target, class_name, effects, depth, visiting)
+          return true if outcome == :assigned
+          return false if outcome == :terminates_unassigned
+        end
+        # Reached the end of the branch without a definite assignment;
+        # safe only if the branch's last statement always raises (no
+        # completing path falls out of it).
+        always_raises?(stmts.last)
+      end
+
+      # `if`/`unless` is a definite assignment of `target` only when
+      # BOTH the then and else arms definitely assign (or raise-out).
+      # A missing else arm means the fall-through path skips the
+      # assignment -> not definite. Modifier-form `if`/`unless` (no
+      # else, single predicate'd statement) likewise.
+      def conditional_assignment_outcome(node, target, class_name, effects, depth, visiting)
+        else_branch = node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause
+        return :falls_through_unassigned unless else_branch.is_a?(Prism::ElseNode)
+        return :falls_through_unassigned unless node.statements
+
+        then_ok = branch_definitely_assigns?(node.statements, target, class_name, effects, depth, visiting)
+        else_ok = branch_definitely_assigns?(else_branch.statements, target, class_name, effects, depth, visiting)
+        then_ok && else_ok ? :assigned : :falls_through_unassigned
+      end
+
+      # `case` is a definite assignment only when there is a real
+      # `else` clause AND every `when`/`in` body plus the else body
+      # definitely assigns (or raises-out). A missing else lets an
+      # unmatched subject fall through unassigned.
+      def case_assignment_outcome(node, target, class_name, effects, depth, visiting)
+        else_clause = node.else_clause
+        return :falls_through_unassigned unless else_clause.is_a?(Prism::ElseNode)
+
+        branches = node.conditions.map { |c| c.respond_to?(:statements) ? c.statements : nil }
+        branches << else_clause.statements
+        all_ok = branches.all? do |b|
+          branch_definitely_assigns?(b, target, class_name, effects, depth, visiting)
+        end
+        all_ok ? :assigned : :falls_through_unassigned
+      end
+
+      # True when `node` (a single statement or its last statement) is
+      # an unconditional `raise`/`fail` call that always terminates the
+      # path — used to treat raise-terminated branches as
+      # non-completing (they never observe the seed nil).
+      def always_raises?(node)
+        node = top_level_statements(node).last if node.is_a?(Prism::StatementsNode)
+        return false unless node.is_a?(Prism::CallNode)
+        return false unless node.receiver.nil?
+
+        %i[raise fail].include?(node.name)
+      end
+
+      # True when `call` is an unconditional, statement-level,
+      # implicit-self (or `self.`) call to a SAME-CLASS method whose
+      # definite-assignment summary includes `target`. Calls through a
+      # block, on another receiver, or to an unresolved name contribute
+      # nothing (the seed nil stays).
+      def unconditional_call_assigns?(call, target, class_name, effects, depth, _visiting)
+        return false if effects.nil? || class_name.nil?
+        return false if depth >= SAME_CLASS_CALL_DEPTH_CAP
+        return false unless call.is_a?(Prism::CallNode)
+        return false unless call.block.nil?
+        # Implicit self (`mask!(x)`) or explicit `self.mask!(x)` only.
+        return false unless call.receiver.nil? || call.receiver.is_a?(Prism::SelfNode)
+
+        assigns = effects.dig(class_name, call.name)
+        return false if assigns.nil?
+
+        assigns.include?(target)
+      end
+
       def record_ivar_write(node, scope, class_name, accumulator, guarded: false)
         rvalue_type = scope.type_of(node.value)
 
@@ -687,10 +1129,104 @@ module Rigor
         return if guarded && falsey_constant?(rvalue_type)
 
         rvalue_type = Type::Combinator.union(rvalue_type, Type::Combinator.constant_of(nil)) if guarded
+        accumulate_ivar_type(accumulator, class_name, node.name, rvalue_type)
+      end
+
+      # Unions `type` into the class-ivar accumulator for `(class_name,
+      # ivar_name)`. Shared by the single-write and multi-write
+      # (parallel-assignment) collectors.
+      def accumulate_ivar_type(accumulator, class_name, ivar_name, type)
         accumulator[class_name] ||= {}
-        existing = accumulator[class_name][node.name]
-        accumulator[class_name][node.name] =
-          existing ? Type::Combinator.union(existing, rvalue_type) : rvalue_type
+        existing = accumulator[class_name][ivar_name]
+        accumulator[class_name][ivar_name] =
+          existing ? Type::Combinator.union(existing, type) : type
+      end
+
+      # N1 — records each `InstanceVariableTargetNode` of a
+      # `MultiWriteNode` (parallel / multiple assignment) into the
+      # class-ivar union, with the best cheap per-slot type. When the RHS
+      # is array/tuple-shaped (`Type::Tuple`) the ivar at position `i`
+      # records the type of element `i`; otherwise — an unanalyzable RHS
+      # such as `Open3.popen3(cmd)` typing to `Dynamic[top]` — every ivar
+      # slot records that unanalyzable floor (NOT `nil`: a multi-write we
+      # cannot decompose means the value is *unknown*, and `Dynamic[top]`
+      # is the sound union constituent, mirroring what a single write to
+      # an unknown RHS records). Nested targets (`(@a, @b), @c = …`)
+      # recurse with the slot's type as the new RHS type.
+      def record_multi_write_ivars(node, scope, class_name, accumulator)
+        return unless node.is_a?(Prism::MultiWriteNode)
+
+        rhs_type = scope.type_of(node.value)
+        record_multi_target_ivars(node, rhs_type, class_name, accumulator)
+      end
+
+      # Walks a `MultiWriteNode` / `MultiTargetNode` target tree against
+      # `rhs_type`, recording ivar targets per slot. Mirrors
+      # `MultiTargetBinder`'s tuple decomposition but for ivar (rather
+      # than local-variable) targets.
+      def record_multi_target_ivars(node, rhs_type, class_name, accumulator)
+        lefts = node.lefts || []
+        rest = node.rest
+        rights = node.rights || []
+        fronts, rest_type, backs =
+          decompose_multi_write_rhs(rhs_type, lefts.size, rights.size, rest_present: !rest.nil?)
+
+        lefts.each_with_index { |t, i| record_multi_ivar_target(t, fronts[i], class_name, accumulator) }
+        record_multi_ivar_rest(rest, rest_type, class_name, accumulator) if rest
+        rights.each_with_index { |t, i| record_multi_ivar_target(t, backs[i], class_name, accumulator) }
+      end
+
+      def decompose_multi_write_rhs(rhs_type, front_count, back_count, rest_present:)
+        if rhs_type.is_a?(Type::Tuple)
+          elements = rhs_type.elements
+          fronts = Array.new(front_count) { |i| multi_write_slot_type(elements, i) }
+          if rest_present
+            middle_end = [elements.size - back_count, front_count].max
+            backs = Array.new(back_count) { |i| multi_write_slot_type(elements, middle_end + i) }
+            [fronts, Type::Combinator.untyped, backs]
+          else
+            backs = Array.new(back_count) { |i| multi_write_slot_type(elements, front_count + i) }
+            [fronts, nil, backs]
+          end
+        else
+          # Unanalyzable / non-tuple RHS: every slot is the unknown floor.
+          floor = Type::Combinator.untyped
+          [Array.new(front_count) { floor }, rest_present ? floor : nil, Array.new(back_count) { floor }]
+        end
+      end
+
+      # The per-slot type for index `i` of a tuple RHS. A missing slot
+      # (over-destructure) is `nil` at runtime; a present slot keeps its
+      # type. Unlike the local-variable binder we do NOT soften an
+      # optional slot here — a class-ivar seed deliberately preserves a
+      # genuine `T | nil`, and any spurious nil is removed by the
+      # flow-side narrowing, not by dropping it at collection time.
+      def multi_write_slot_type(elements, index)
+        element = elements[index]
+        return Type::Combinator.constant_of(nil) if element.nil?
+
+        element
+      end
+
+      def record_multi_ivar_target(target, type, class_name, accumulator)
+        case target
+        when Prism::InstanceVariableTargetNode
+          accumulate_ivar_type(accumulator, class_name, target.name, type)
+        when Prism::MultiTargetNode
+          record_multi_target_ivars(target, type, class_name, accumulator)
+        end
+      end
+
+      def record_multi_ivar_rest(splat_node, _type, class_name, accumulator)
+        return unless splat_node.is_a?(Prism::SplatNode)
+
+        expression = splat_node.expression
+        return unless expression.is_a?(Prism::InstanceVariableTargetNode)
+
+        # A splat collects the middle slots into an Array; the precise
+        # element type is not worth recovering here. Record the
+        # unanalyzable floor (an Array of unknown), never nil.
+        accumulate_ivar_type(accumulator, class_name, expression.name, Type::Combinator.untyped)
       end
 
       def falsey_constant?(type)
@@ -1115,6 +1651,146 @@ module Rigor
         accumulator[class_name][def_node.name] = def_node
       end
 
+      # Module-singleton call resolution (ADR-57 follow-up) — the
+      # SINGLETON-side mirror of `build_discovered_def_nodes`. Records the
+      # `Prism::DefNode` for every singleton-side method (`def self.x`,
+      # `def Foo.x`, a `class << self` body, and a `module_function`
+      # method) keyed by qualified class/module name → method → node, so
+      # `ExpressionTyper` can re-type the body when a `Singleton[Foo]`
+      # receiver dispatches `Foo.x`. The instance-side table is kept
+      # singleton-free on purpose (its ancestor walk binds `self` as
+      # `Nominal`), so the two never overlap except for `module_function`
+      # defs, which are genuinely callable on both sides and so appear in
+      # both tables. Top-level singleton defs (`def self.x` outside any
+      # class — `self` is `main`) are not recorded; they have no constant
+      # receiver to dispatch through.
+      def build_discovered_singleton_def_nodes(root)
+        accumulator = {}
+        walk_singleton_def_nodes(root, [], false, accumulator)
+        accumulator.transform_values(&:freeze).freeze
+      end
+
+      # Walks every node, entering class/module/singleton-class bodies via
+      # {#walk_singleton_body} so a bare `module_function` toggle threads
+      # correctly across the body's *sibling* statements (a child-by-child
+      # recursion would reset it). At the top level / inside an arbitrary
+      # node there is no `module_function` state to carry, so descent is a
+      # plain per-child walk.
+      def walk_singleton_def_nodes(node, qualified_prefix, in_singleton_class, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            walk_singleton_body(node.body, qualified_prefix + [name], false, accumulator) if node.body
+            return
+          end
+        when Prism::SingletonClassNode
+          if node.body
+            singleton_prefix = singleton_class_prefix(node, qualified_prefix)
+            if singleton_prefix
+              walk_singleton_body(node.body, singleton_prefix, true, accumulator)
+              return
+            end
+          end
+        when Prism::ConstantWriteNode
+          if meta_new_block_body(node)
+            child_prefix = qualified_prefix + [node.name.to_s]
+            walk_singleton_body(meta_new_block_body(node), child_prefix, false, accumulator)
+            return
+          end
+        when Prism::DefNode
+          record_singleton_def_node(node, qualified_prefix, in_singleton_class, false, accumulator)
+          return
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_singleton_def_nodes(child, qualified_prefix, in_singleton_class, accumulator)
+        end
+      end
+
+      # Walks a class/module/singleton-class body's direct statements in
+      # source order, threading the bare-`module_function` toggle: once a
+      # bare `module_function` is seen, every subsequent `def` in the body
+      # registers as a singleton method. Nested classes/modules/defs and
+      # `module_function :a, :b` named forms recurse / record through the
+      # general walker so the toggle stays scoped to its own body.
+      def walk_singleton_body(body, qualified_prefix, in_singleton_class, accumulator)
+        module_function_on = false
+        statements_of(body).each do |stmt|
+          if stmt.is_a?(Prism::CallNode) && module_function_toggle?(stmt)
+            if bare_module_function?(stmt)
+              module_function_on = true
+            else
+              record_module_function_names(stmt, qualified_prefix, body, accumulator)
+            end
+            next
+          end
+          if stmt.is_a?(Prism::DefNode)
+            record_singleton_def_node(stmt, qualified_prefix, in_singleton_class, module_function_on, accumulator)
+            next
+          end
+          walk_singleton_def_nodes(stmt, qualified_prefix, in_singleton_class, accumulator)
+        end
+      end
+
+      # Direct statement children of a class/module body node (a
+      # `Prism::StatementsNode`, a `Prism::BeginNode` wrapping one, or a
+      # lone statement). Returns an empty list for an empty body.
+      def statements_of(body)
+        case body
+        when Prism::StatementsNode then body.body
+        when Prism::BeginNode then statements_of(body.statements)
+        when nil then []
+        else [body]
+        end
+      end
+
+      def record_singleton_def_node(def_node, qualified_prefix, in_singleton_class, module_function_on, accumulator)
+        singleton = def_singleton?(def_node, qualified_prefix, in_singleton_class) || module_function_on
+        return unless singleton
+        return if qualified_prefix.empty?
+
+        class_name = qualified_prefix.join("::")
+        (accumulator[class_name] ||= {})[def_node.name] = def_node
+      end
+
+      # A bare `module_function` (no arguments) flips every following `def`
+      # in the module body to module-function (instance + singleton) mode.
+      def module_function_toggle?(node)
+        node.name == :module_function && node.receiver.nil?
+      end
+
+      def bare_module_function?(node)
+        node.arguments.nil? || node.arguments.arguments.empty?
+      end
+
+      # `module_function :a, :b` retro-marks named siblings (defined
+      # earlier OR later in the same body) as module-functions. Resolves
+      # each symbol-literal argument against the body's own `def`s and
+      # registers the matching `DefNode` on the module's singleton side.
+      # Non-symbol arguments and names with no matching `def` are skipped
+      # (a miss degrades to today's `Dynamic`, never a false resolution).
+      def record_module_function_names(node, qualified_prefix, body, accumulator)
+        return if qualified_prefix.empty?
+
+        defs_by_name = statements_of(body).each_with_object({}) do |stmt, acc|
+          acc[stmt.name] = stmt if stmt.is_a?(Prism::DefNode) && stmt.receiver.nil?
+        end
+        class_name = qualified_prefix.join("::")
+        node.arguments&.arguments&.each do |arg|
+          name = symbol_argument_name(arg)
+          def_node = name && defs_by_name[name]
+          (accumulator[class_name] ||= {})[name] = def_node if def_node
+        end
+      end
+
+      # The Symbol value of a `:name` / `"name"` literal argument, or nil.
+      def symbol_argument_name(arg)
+        arg.unescaped.to_sym if arg.is_a?(Prism::SymbolNode) || arg.is_a?(Prism::StringNode)
+      end
+
       # ADR-24 slice 2 — per-class table mapping a fully
       # qualified user class to its superclass name AS WRITTEN
       # at the `class Foo < Bar` declaration. Only constant
@@ -1575,8 +2251,8 @@ module Rigor
       # @return [Hash{Symbol => Hash}]
       #   `{ def_nodes:, def_sources:, superclasses:, includes:, class_sources: }`
       def discovered_def_index_for_paths(paths, buffer: nil)
-        acc = { def_nodes: {}, def_sources: {}, superclasses: {}, includes: {}, method_visibilities: {}, methods: {},
-                class_sources: {}, data_member_layouts: {} }
+        acc = { def_nodes: {}, singleton_def_nodes: {}, def_sources: {}, superclasses: {}, includes: {},
+                method_visibilities: {}, methods: {}, class_sources: {}, data_member_layouts: {} }
         paths.each do |path|
           physical = buffer ? buffer.resolve(path) : path
           root = Prism.parse(File.read(physical), filepath: path).value
@@ -1595,7 +2271,7 @@ module Rigor
         # intact while still letting `attr_reader :x` in one file
         # suppress a false undefined-method for `obj.x` in another.
         acc[:methods] = subtract_def_methods(acc[:methods], acc[:def_nodes])
-        %i[def_nodes def_sources includes method_visibilities methods class_sources].each do |key|
+        %i[def_nodes singleton_def_nodes def_sources includes method_visibilities methods class_sources].each do |key|
           acc[key].each_value(&:freeze)
         end
         acc.transform_values(&:freeze)
@@ -1618,6 +2294,9 @@ module Rigor
       # visibility declared in a sibling file.
       def accumulate_project_index(acc, path, root)
         merge_discovered_defs(acc[:def_nodes], acc[:def_sources], path, root)
+        build_discovered_singleton_def_nodes(root).each do |class_name, methods|
+          (acc[:singleton_def_nodes][class_name] ||= {}).merge!(methods)
+        end
         superclasses = build_discovered_superclasses(root)
         includes = build_discovered_includes(root)
         acc[:superclasses].merge!(superclasses)
@@ -1694,11 +2373,63 @@ module Rigor
         when Prism::ModuleNode
           name = qualified_name_for(node.constant_path)
           return collect_class_decls(node.body, qualified_prefix + [name], accumulator) if name && node.body
+        when Prism::ConstantWriteNode
+          record_class_new_constant_decl(node, qualified_prefix, accumulator)
         end
 
         node.compact_child_nodes.each { |child| collect_class_decls(child, qualified_prefix, accumulator) }
       end
 
+      # T1 (template-corpora survey) — record a `Const = Class.new(Super)`
+      # (and the bare `Class.new` / `Module.new`) class-creating constant
+      # in the cross-file discovery table so a reference to `Const` from
+      # ANOTHER file under the same namespace resolves to the project
+      # class instead of falling through to a core same-named class
+      # (`Liquid::SyntaxError = Class.new(Error)` referenced in a sibling
+      # file's `rescue SyntaxError => e`, which otherwise resolved to core
+      # `::SyntaxError`). Mirrors the single-file `in_source_constants`
+      # answer, which types `Class.new(Super)` as `Singleton[Super]` (the
+      # constructed class answers method lookups through Super's chain).
+      # The superclass name is resolved lexically against the enclosing
+      # prefix; a bare `Class.new` with no superclass (or `Module.new`)
+      # types as `Singleton[Const]` itself. The block form is left to the
+      # existing `meta_new_block_body` machinery — only the plain
+      # `Class.new(Super)` constant (the namespaced-sibling-error idiom)
+      # is added here.
+      def record_class_new_constant_decl(node, qualified_prefix, accumulator)
+        rvalue = node.value
+        return unless class_new_call?(rvalue) || module_new_call?(rvalue)
+        return if rvalue.block # block form: handled by meta_new_block_body walks
+
+        full = (qualified_prefix + [node.name.to_s]).join("::")
+        super_name = class_new_superclass_name(rvalue, qualified_prefix, accumulator)
+        accumulator[full] = Type::Combinator.singleton_of(super_name || full)
+      end
+
+      # Lexically-qualified name of a `Class.new(Super)` superclass
+      # argument, or nil when there is no positional superclass (a bare
+      # `Class.new` / `Module.new`). When the unqualified super name is a
+      # class already discovered under an enclosing-prefix segment, the
+      # qualified form is returned (so `Class.new(Error)` inside `module M`
+      # resolves to `M::Error`); otherwise the literal name is returned
+      # (covering a core / RBS-known superclass spelled bare).
+      def class_new_superclass_name(call_node, qualified_prefix, accumulator)
+        arg = call_node.arguments&.arguments&.first
+        return nil if arg.nil?
+
+        raw = qualified_name_for(arg)
+        return nil if raw.nil?
+
+        prefix = qualified_prefix.dup
+        until prefix.empty?
+          candidate = (prefix + [raw]).join("::")
+          return candidate if accumulator.key?(candidate)
+
+          prefix.pop
+        end
+        raw
+      end
+
       # Walks the program once for `Prism::ModuleNode` and
       # `Prism::ClassNode`, recording the `Singleton[<qualified>]`
       # type for the outermost `constant_path` node of each