rigortype 0.1.18 → 0.2.0

data/lib/rigor/inference/scope_indexer.rb

@@ -4,9 +4,11 @@ require "prism"
 
 require_relative "../scope"
 require_relative "../type"
+require_relative "../source/constant_path"
 require_relative "mutation_widening"
 require_relative "narrowing"
 require_relative "statement_evaluator"
+require_relative "struct_fold_safety"
 
 module Rigor
   module Inference
@@ -49,9 +51,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
@@ -109,12 +116,8 @@ module Rigor
         # recognised `define_method` calls and records the
         # introduced method names. `rigor check` consults the
         # table to suppress false positives for methods the
-        # user has defined but no RBS sig describes.
-        # Merged UNDER any cross-file pre-pass seed (like the def-node
-        # / include tables below) so a method `def`/`attr_reader`-
-        # declared in one file suppresses a false `undefined-method`
-        # for a call in another — `rigor check` seeds the project-wide
-        # table via `Runner#seed_project_scope`.
+        # user has defined but no RBS sig describes. Merged
+        # UNDER the cross-file pre-pass seed; details: merge_project_method_indexes.
         discovered_methods = deep_merge_class_methods(
           default_scope.discovered_methods, build_discovered_methods(root)
         )
@@ -145,13 +148,29 @@ module Rigor
         # `table[node]` to type predicates; the second pass's
         # entry is the one that reflects all flow-derived
         # rebinds, so it MUST overwrite the first.
+        # ADR-48 Struct slice 3 — install the top-level fold-safe-local set so
+        # a member read off a mutation-free top-level struct binding folds.
+        seeded_scope = seed_struct_fold_safe(seeded_scope, root)
+
         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
       end
 
+      # ADR-48 Struct slice 3 — installs the top-level fold-safe-local set
+      # ({Inference::StructFoldSafety}). Struct member layouts of constant
+      # receivers are resolved through the side-table the seeded scope carries.
+      def seed_struct_fold_safe(seeded_scope, root)
+        seeded_scope.with_struct_fold_safe(
+          StructFoldSafety.fold_safe_locals(
+            root, ->(name) { seeded_scope.struct_member_layout(name)&.[](:members) }
+          )
+        )
+      end
+
       # v0.0.2 #5 + ADR-24 slice 2 — seeds the three
       # project-method indexes onto `seeded_scope`: the
       # per-instance-method def-node table, the class ->
@@ -164,6 +183,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)
         )
@@ -176,23 +198,34 @@ module Rigor
         method_visibilities = default_scope.discovered_method_visibilities.merge(
           build_discovered_method_visibilities(root)
         ) { |_class, cross_file, per_file| cross_file.merge(per_file) }
-        # ADR-48 — per-file Data member layouts merged OVER the cross-file
-        # seed (same-file declaration is authoritative for its own classes).
-        data_member_layouts = default_scope.data_member_layouts.merge(
-          build_data_member_layouts(root)
-        )
+        # ADR-48 — per-file Data + Struct member layouts merged OVER the
+        # cross-file seed (same-file declaration is authoritative).
+        data_member_layouts, struct_member_layouts = merge_member_layouts(default_scope, root)
 
         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
+            data_member_layouts: data_member_layouts,
+            struct_member_layouts: struct_member_layouts
           )
         )
       end
 
+      # ADR-48 — the per-file Data + Struct member-layout tables, each merged
+      # OVER the cross-file seed so a same-file declaration wins for its own
+      # classes. Returned as a pair to keep {#merge_project_method_indexes}
+      # under the method-size budget.
+      def merge_member_layouts(default_scope, root)
+        [
+          default_scope.data_member_layouts.merge(build_data_member_layouts(root)),
+          default_scope.struct_member_layouts.merge(build_struct_member_layouts(root))
+        ]
+      end
+
       # Slice 7 phase 2. Builds the class-level ivar accumulator
       # by walking every `Prism::ClassNode` / `Prism::ModuleNode`
       # body, descending into each nested `Prism::DefNode`, and
@@ -210,8 +243,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
@@ -334,13 +374,13 @@ module Rigor
         end
       end
 
-      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars, # rubocop:disable Metrics/CyclomaticComplexity
-                           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
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             if node.body
@@ -361,13 +401,13 @@ 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? &&
@@ -380,12 +420,12 @@ module Rigor
 
         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("::")
@@ -399,7 +439,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
@@ -589,13 +645,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
@@ -603,12 +675,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
 
@@ -646,16 +719,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
@@ -723,6 +802,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 = Source::ConstantPath.qualified_name(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)
 
@@ -747,10 +1152,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)
@@ -775,7 +1274,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             walk_class_cvars(node.body, child_prefix, default_scope, accumulator) if node.body
@@ -861,7 +1360,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             walk_constant_writes(node.body, child_prefix, default_scope, accumulator) if node.body
@@ -871,7 +1370,7 @@ module Rigor
           record_constant_write(node, qualified_prefix, default_scope, accumulator, node.name.to_s)
           return
         when Prism::ConstantPathWriteNode
-          full = qualified_name_for(node.target)
+          full = Source::ConstantPath.qualified_name(node.target)
           record_constant_write(node, [], default_scope, accumulator, full) if full
           return
         end
@@ -937,7 +1436,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             record_meta_superclass_members(node, child_prefix, accumulator) if node.is_a?(Prism::ClassNode)
@@ -990,7 +1489,7 @@ module Rigor
         when Prism::SelfNode
           qualified_prefix
         when Prism::ConstantReadNode, Prism::ConstantPathNode
-          rendered = qualified_name_for(node.expression)
+          rendered = Source::ConstantPath.qualified_name(node.expression)
           return nil unless rendered
 
           if !qualified_prefix.empty? && qualified_prefix.last == rendered
@@ -1097,7 +1596,7 @@ module Rigor
         when Prism::ConstantReadNode
           receiver.name.to_s == qualified_prefix.last
         when Prism::ConstantPathNode
-          rendered = render_constant_path(receiver)
+          rendered = Source::ConstantPath.render(receiver)
           return false unless rendered
 
           path = rendered.split("::")
@@ -1129,7 +1628,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             walk_def_nodes(node.body, child_prefix, false, accumulator) if node.body
@@ -1175,6 +1674,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 = Source::ConstantPath.qualified_name(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
@@ -1194,16 +1833,16 @@ module Rigor
 
         case node
         when Prism::ClassNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             full = (qualified_prefix + [name]).join("::")
-            superclass = node.superclass && qualified_name_for(node.superclass)
+            superclass = node.superclass && Source::ConstantPath.qualified_name(node.superclass)
             accumulator[full] = superclass if superclass
             walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
             return
           end
         when Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             walk_class_superclasses(node.body, qualified_prefix + [name], accumulator) if node.body
             return
@@ -1235,14 +1874,14 @@ module Rigor
 
         case node
         when Prism::ClassNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             record_data_member_layout(accumulator, qualified_prefix + [name], node.superclass)
             walk_data_member_layouts(node.body, qualified_prefix + [name], accumulator) if node.body
             return
           end
         when Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             walk_data_member_layouts(node.body, qualified_prefix + [name], accumulator) if node.body
             return
@@ -1267,6 +1906,74 @@ module Rigor
         accumulator[qualified_parts.join("::")] = members.freeze
       end
 
+      # ADR-48 Struct follow-up — the `Struct.new(...)` sibling of
+      # {#build_data_member_layouts}. A separate, additive table so the
+      # existing `Data.define` value-shape contract (a bare `[Symbol]`) is
+      # untouched: a Struct entry carries `{ members:, keyword_init: }`
+      # because the dispatcher needs the flag to fold the matching `.new`
+      # call form (positional vs keyword) without manufacturing a wrong map.
+      def build_struct_member_layouts(root)
+        accumulator = {}
+        walk_struct_member_layouts(root, [], accumulator)
+        accumulator.freeze
+      end
+
+      def walk_struct_member_layouts(node, qualified_prefix, accumulator)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode
+          name = Source::ConstantPath.qualified_name(node.constant_path)
+          if name
+            record_struct_member_layout(accumulator, qualified_prefix + [name], node.superclass)
+            walk_struct_member_layouts(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        when Prism::ModuleNode
+          name = Source::ConstantPath.qualified_name(node.constant_path)
+          if name
+            walk_struct_member_layouts(node.body, qualified_prefix + [name], accumulator) if node.body
+            return
+          end
+        when Prism::ConstantWriteNode
+          record_struct_member_layout(accumulator, qualified_prefix + [node.name.to_s], node.value)
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_struct_member_layouts(child, qualified_prefix, accumulator)
+        end
+      end
+
+      # Records `qualified -> { members:, keyword_init: }` when `expr` is a
+      # `Struct.new(*Symbol [, keyword_init: <bool>])` call with at least one
+      # literal-Symbol member.
+      def record_struct_member_layout(accumulator, qualified_parts, expr)
+        return unless struct_new_call?(expr)
+
+        members = meta_member_names(expr)
+        return if members.empty?
+
+        accumulator[qualified_parts.join("::")] = {
+          members: members.freeze,
+          keyword_init: struct_new_keyword_init?(expr)
+        }.freeze
+      end
+
+      # True when a `Struct.new` call carries `keyword_init: true` as a
+      # literal in its trailing keyword hash. A non-literal value (or its
+      # absence) reads as `false` — the conservative positional default.
+      def struct_new_keyword_init?(call_node)
+        args = call_node.arguments&.arguments || []
+        last = args.last
+        return false unless last.is_a?(Prism::KeywordHashNode)
+
+        last.elements.any? do |assoc|
+          assoc.is_a?(Prism::AssocNode) &&
+            assoc.key.is_a?(Prism::SymbolNode) && assoc.key.unescaped == "keyword_init" &&
+            assoc.value.is_a?(Prism::TrueNode)
+        end
+      end
+
       MIXIN_CALL_NAMES = %i[include prepend].freeze
 
       # ADR-24 slice 2 — per-class/module table mapping a fully
@@ -1290,7 +1997,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             full = (qualified_prefix + [name]).join("::")
             walk_class_includes(node.body, qualified_prefix + [name], full, accumulator) if node.body
@@ -1310,7 +2017,7 @@ module Rigor
         return unless MIXIN_CALL_NAMES.include?(node.name)
 
         node.arguments&.arguments&.each do |arg|
-          mod = qualified_name_for(arg)
+          mod = Source::ConstantPath.qualified_name(arg)
           (accumulator[current_class] ||= []) << mod if mod
         end
       end
@@ -1350,7 +2057,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
             walk_method_visibilities(node.body, child_prefix, false, :public, accumulator) if node.body
@@ -1488,7 +2195,7 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             collect_class_alias_map(node.body, qualified_prefix + [name], accumulator) if node.body
             return accumulator
@@ -1635,8 +2342,9 @@ 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: {},
+                struct_member_layouts: {} }
         paths.each do |path|
           physical = buffer ? buffer.resolve(path) : path
           root = Prism.parse(File.read(physical), filepath: path).value
@@ -1655,7 +2363,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)
@@ -1678,6 +2386,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)
@@ -1687,6 +2398,7 @@ module Rigor
         record_class_sources(acc[:class_sources], path, root, superclasses, includes)
         merge_class_keyed_index_tables(acc, root)
         acc[:data_member_layouts].merge!(build_data_member_layouts(root))
+        acc[:struct_member_layouts].merge!(build_struct_member_layouts(root))
       end
 
       # Folds the per-class method-visibility and method-existence tables of
@@ -1745,20 +2457,72 @@ module Rigor
 
         case node
         when Prism::ClassNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(node.constant_path)
           if name
             full = (qualified_prefix + [name]).join("::")
             accumulator[full] = Type::Combinator.singleton_of(full)
             return collect_class_decls(node.body, qualified_prefix + [name], accumulator) if node.body
           end
         when Prism::ModuleNode
-          name = qualified_name_for(node.constant_path)
+          name = Source::ConstantPath.qualified_name(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 = Source::ConstantPath.qualified_name(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
@@ -1791,7 +2555,7 @@ module Rigor
       end
 
       def record_class_or_module?(node, qualified_prefix, identity_table, discovered)
-        name = qualified_name_for(node.constant_path)
+        name = Source::ConstantPath.qualified_name(node.constant_path)
         return false unless name
 
         full = (qualified_prefix + [name]).join("::")
@@ -1903,25 +2667,6 @@ module Rigor
         end
       end
 
-      def qualified_name_for(constant_path_node)
-        case constant_path_node
-        when Prism::ConstantReadNode
-          constant_path_node.name.to_s
-        when Prism::ConstantPathNode
-          render_constant_path(constant_path_node)
-        end
-      end
-
-      def render_constant_path(node)
-        prefix =
-          case node.parent
-          when Prism::ConstantReadNode then "#{node.parent.name}::"
-          when Prism::ConstantPathNode then "#{render_constant_path(node.parent)}::"
-          else ""
-          end
-        "#{prefix}#{node.name}"
-      end
-
       # Walks `node`'s subtree DFS and fills in scope entries for every
       # Prism node the StatementEvaluator did not visit (i.e. expression-
       # interior nodes like the receiver/args of a CallNode). Those