rigortype 0.2.9 → 0.3.0

data/lib/rigor/inference/scope_indexer.rb

@@ -5,6 +5,9 @@ require "prism"
 require_relative "../scope"
 require_relative "../type"
 require_relative "../source/constant_path"
+require_relative "../source/node_children"
+require_relative "../cache/file_digest"
+require_relative "def_handle"
 require_relative "mutation_widening"
 require_relative "narrowing"
 require_relative "statement_evaluator"
@@ -310,7 +313,7 @@ module Rigor
         end
       end
 
-      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars, # rubocop:disable Metrics/CyclomaticComplexity,Metrics/ParameterLists
+      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars, # rubocop:disable Metrics/ParameterLists
                            read_before_write = nil, init_writes = nil, method_assign_effects = nil)
         return unless node.is_a?(Prism::Node)
 
@@ -346,7 +349,7 @@ module Rigor
           end
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_class_ivars(child, qualified_prefix, default_scope, accumulator,
                            mutated_ivars, read_before_write, init_writes, method_assign_effects)
         end
@@ -511,7 +514,7 @@ module Rigor
           (init_writes[class_name] ||= Set.new) << node.name
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           collect_class_body_ivar_writes(child, class_name, init_writes)
         end
       end
@@ -522,16 +525,49 @@ module Rigor
 
         read_first << node.name if node.is_a?(Prism::InstanceVariableReadNode) && !seen_writes.include?(node.name)
 
+        # N1 — parallel / multiple assignment (`@m, @n = [], []`). The ivar targets are `InstanceVariableTargetNode`s,
+        # not `InstanceVariableWriteNode`s, so the generic descent below never records them as writes. Left unhandled,
+        # an ivar written only via massign in `initialize` stays absent from `init_writes`, and
+        # `contribute_read_before_write_nil!` then unions a spurious `nil` into its class-ivar seed — masking a
+        # genuinely-typed `@m` (e.g. `Tuple[]`) as `T | nil` at every sibling read. The RHS runs before any target is
+        # committed, so descend into `value` FIRST (an ivar read there is read-before-write), then mark every ivar
+        # target as written.
+        if node.is_a?(Prism::MultiWriteNode)
+          detect_read_before_write(node.value, seen_writes, read_first) if node.value
+          detect_multi_write_target_writes(node, seen_writes, read_first)
+          return
+        end
+
         # Descend BEFORE recording a write — `@x = @x + 1`'s RHS is an `InstanceVariableReadNode` that runs before the
-        # write is committed; the read is therefore read-before-write semantically. Prism's `compact_child_nodes`
-        # returns the value child before the lvalue target, matching this order.
-        node.compact_child_nodes.each do |c|
+        # write is committed; the read is therefore read-before-write semantically. `each_child` yields the value
+        # child before the lvalue target (`compact_child_nodes` field order), matching this order.
+        node.rigor_each_child do |c|
           detect_read_before_write(c, seen_writes, read_first)
         end
 
         seen_writes << node.name if IVAR_WRITE_NODES.any? { |klass| node.is_a?(klass) }
       end
 
+      # Records each ivar target of a `MultiWriteNode` / nested `MultiTargetNode` into `seen_writes`, and descends into
+      # any non-ivar target (a `CallTargetNode` / `IndexTargetNode` receiver such as `@obj.x, @y = …`) so an ivar read
+      # inside a target receiver still counts as read-before-write.
+      def detect_multi_write_target_writes(node, seen_writes, read_first)
+        targets = (node.lefts || []) + [node.rest].compact + (node.rights || [])
+        targets.each do |target|
+          case target
+          when Prism::InstanceVariableTargetNode
+            seen_writes << target.name
+          when Prism::MultiTargetNode
+            detect_multi_write_target_writes(target, seen_writes, read_first)
+          when Prism::SplatNode
+            inner = target.expression
+            seen_writes << inner.name if inner.is_a?(Prism::InstanceVariableTargetNode)
+          else
+            detect_read_before_write(target, seen_writes, read_first)
+          end
+        end
+      end
+
       IVAR_BARRIER_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode].freeze
       private_constant :IVAR_BARRIER_NODES
 
@@ -568,7 +604,7 @@ module Rigor
           return
         end
 
-        node.compact_child_nodes.each do |c|
+        node.rigor_each_child do |c|
           gather_ivar_writes(c, scope, class_name, accumulator, guarded_ivars, mutated_ivars, dead_writes)
         end
       end
@@ -742,7 +778,7 @@ module Rigor
           return acc
         end
 
-        root.compact_child_nodes.each { |c| collect_class_method_defs(c, prefix, acc) }
+        root.rigor_each_child { |c| collect_class_method_defs(c, prefix, acc) }
         acc
       end
 
@@ -773,7 +809,7 @@ module Rigor
         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) }
+        node.rigor_each_child { |c| ivar_write_targets(c, acc) }
         acc
       end
 
@@ -1106,7 +1142,7 @@ module Rigor
           return
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_class_cvars(child, qualified_prefix, default_scope, accumulator)
         end
       end
@@ -1125,7 +1161,7 @@ module Rigor
         record_cvar_write(node, scope, class_name, accumulator) if node.is_a?(Prism::ClassVariableWriteNode)
         return if IVAR_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
-        node.compact_child_nodes.each { |c| gather_cvar_writes(c, scope, class_name, accumulator) }
+        node.rigor_each_child { |c| gather_cvar_writes(c, scope, class_name, accumulator) }
       end
 
       def record_cvar_write(node, scope, class_name, accumulator)
@@ -1149,7 +1185,7 @@ module Rigor
         return unless node.is_a?(Prism::Node)
 
         record_global_write(node, scope, accumulator) if node.is_a?(Prism::GlobalVariableWriteNode)
-        node.compact_child_nodes.each { |c| gather_global_writes(c, scope, accumulator) }
+        node.rigor_each_child { |c| gather_global_writes(c, scope, accumulator) }
       end
 
       def record_global_write(node, scope, accumulator)
@@ -1189,7 +1225,7 @@ module Rigor
           return
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_constant_writes(child, qualified_prefix, default_scope, accumulator)
         end
       end
@@ -1249,7 +1285,7 @@ module Rigor
         end
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
       # Combined `walk_methods` + `walk_def_nodes` descent. The two walks had identical class / module / singleton-class
       # / meta-block traversals and both stopped at `DefNode`; the only divergences are leaf actions (recorded into the
       # right accumulator) and the original `walk_methods` returning at `AliasMethodNode` (its symbol-only children
@@ -1295,7 +1331,7 @@ module Rigor
           end
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_methods_and_def_nodes(child, qualified_prefix, in_singleton_class, methods_acc, def_nodes_acc)
         end
       end
@@ -1323,7 +1359,7 @@ module Rigor
           end
         end
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
 
       # v0.1.2 — when a `Const = Data.define(*sym) do ... end` / `Const = Struct.new(*sym) do ... end` constant write
       # carries a block, the block body holds method overrides whose canonical class is `Const`. Survey item (e)
@@ -1474,7 +1510,7 @@ module Rigor
           return
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_singleton_def_nodes(child, qualified_prefix, in_singleton_class, accumulator)
         end
       end
@@ -1586,7 +1622,7 @@ module Rigor
           end
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_class_superclasses(child, qualified_prefix, accumulator)
         end
       end
@@ -1623,7 +1659,7 @@ module Rigor
           record_data_member_layout(accumulator, qualified_prefix + [node.name.to_s], node.value)
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_data_member_layouts(child, qualified_prefix, accumulator)
         end
       end
@@ -1670,7 +1706,7 @@ module Rigor
           record_struct_member_layout(accumulator, qualified_prefix + [node.name.to_s], node.value)
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_struct_member_layouts(child, qualified_prefix, accumulator)
         end
       end
@@ -1731,7 +1767,7 @@ module Rigor
           record_mixin_call(node, current_class, accumulator)
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           walk_class_includes(child, qualified_prefix, current_class, accumulator)
         end
       end
@@ -1772,7 +1808,7 @@ module Rigor
         accumulator.transform_values(&:freeze).freeze
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/AbcSize
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
       def walk_method_visibilities(node, qualified_prefix, in_singleton_class, current_visibility, accumulator)
         return current_visibility unless node.is_a?(Prism::Node)
 
@@ -1810,18 +1846,18 @@ module Rigor
         # entry visibility unchanged.
         if node.is_a?(Prism::StatementsNode)
           local_visibility = current_visibility
-          node.compact_child_nodes.each do |child|
+          node.rigor_each_child do |child|
             local_visibility = walk_method_visibilities(child, qualified_prefix, in_singleton_class,
                                                         local_visibility, accumulator)
           end
         else
-          node.compact_child_nodes.each do |child|
+          node.rigor_each_child do |child|
             walk_method_visibilities(child, qualified_prefix, in_singleton_class, current_visibility, accumulator)
           end
         end
         current_visibility
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
 
       def record_def_visibility(def_node, qualified_prefix, in_singleton_class, current_visibility, accumulator)
         return if def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class
@@ -1922,7 +1958,7 @@ module Rigor
           return accumulator
         end
 
-        node.compact_child_nodes.each { |child| collect_class_alias_map(child, qualified_prefix, accumulator) }
+        node.rigor_each_child { |child| collect_class_alias_map(child, qualified_prefix, accumulator) }
         accumulator
       end
 
@@ -2031,9 +2067,7 @@ 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: {}, singleton_def_nodes: {}, def_sources: {}, superclasses: {}, includes: {},
-                method_visibilities: {}, methods: {}, class_sources: {}, data_member_layouts: {},
-                struct_member_layouts: {} }
+        acc = new_def_index_accumulator
         paths.each do |path|
           physical = buffer ? buffer.resolve(path) : path
           root = Prism.parse(File.read(physical), filepath: path).value
@@ -2042,13 +2076,391 @@ module Rigor
           # Skip files that fail to parse or read; the per-file analyzer surfaces the parse error separately.
           next
         end
+        finalize_def_index(acc)
+      end
+
+      # B1 / ADR-89 WD1 (incremental propagation gates) — parses `paths` ONCE and returns the merged def-index
+      # (as {#discovered_def_index_for_paths}), each file's comment-stripped {#code_fingerprint} (B1), AND each
+      # file's {#declaration_signature} (ADR-89 WD1 — the per-def SIGNATURE shape that replaces the per-def body
+      # fingerprint, so a body edit that leaves every signature equal is declaration-stable). The incremental
+      # session drives the fingerprint / class-declaration change detection off `def_index` and the
+      # declaration-stability skip decision off `declaration_signatures`, so a changed file is parsed once for
+      # all of them (recon §2 dedup). A per-file live index (built + folded, exactly as
+      # {#discovered_project_index_incremental}'s changed-file branch) yields the live def nodes the signature
+      # reads their parameter structure from.
+      # @return [Hash{Symbol => Object}] `{ def_index:, code_fingerprints:, declaration_signatures: }`.
+      def scan_summary_for_paths(paths, buffer: nil)
+        acc = new_def_index_accumulator
+        code_fingerprints = {}
+        declaration_signatures = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          source = File.read(physical)
+          parsed = Prism.parse(source, filepath: path)
+          file_index = build_file_index(path, parsed.value)
+          fold_file_index(acc, file_index)
+          code_fingerprints[path] = code_fingerprint(source, parsed.comments)
+          declaration_signatures[path] = declaration_signature(file_index)
+        rescue StandardError
+          next
+        end
+        { def_index: finalize_def_index(acc), code_fingerprints: code_fingerprints,
+          declaration_signatures: declaration_signatures }
+      end
+
+      # ADR-89 WD1 — a per-file digest of every cross-file DECLARATION surface an ancestry / file-level
+      # dependent consumes, EXCLUDING method bodies (which only symbol dependents consume, via the ADR-46
+      # symbol edges the change-detection already fingerprints per method). A body edit that touches no
+      # signature leaves this equal, so the session drops the file's ancestry / file-level dependents; an
+      # arity / visibility / added-or-removed-method / ancestry / member-layout edit moves it. Deliberately
+      # SYNTACTIC (parameter structure from the def node, not inferred types).
+      #
+      # It captures, from a single file's live def-index: declared class/module names, superclass + include
+      # ancestry, Data/Struct member layouts, the accessor/alias/define_method existence table, per-method
+      # visibilities, and per method (instance + singleton) its name, parameter signature, AND def-start LINE.
+      # The line is load-bearing for soundness: a body edit that SHIFTS a later def's line moves the ADR-17
+      # `project_definition_site` a `call.undefined-method` consumer embeds, so a line shift must invalidate
+      # the declaration (the file's dependents re-check) — this is why the signature is a superset of B1's
+      # comment-stripped code fingerprint on line-moving edits, and strictly more permissive only on
+      # same-line body edits (a local rename, an internal literal), which is the collapse WD1 exists for.
+      def declaration_signature(file_index)
+        parts = []
+        append_ancestry_signature(parts, file_index)
+        append_declaration_tables(parts, file_index)
+        append_def_signatures(parts, file_index[:def_nodes], "#")
+        append_def_signatures(parts, file_index[:singleton_def_nodes], ".")
+        Digest::SHA256.hexdigest(parts.join("\x00"))
+      end
+
+      # The class-declaration + ancestry + member-layout surface of the declaration signature (declared class
+      # names, superclass / include ancestry, Data/Struct member layouts). Kept out of
+      # {#declaration_signature} to hold its ABC budget.
+      def append_ancestry_signature(parts, file_index)
+        parts.concat(file_index[:class_sources].keys.sort_by(&:to_s).map { |cn| "c:#{cn}" })
+        parts.concat(sorted_by_class(file_index[:superclasses]).map { |cn, sc| "s:#{cn}<#{sc}" })
+        parts.concat(sorted_by_class(file_index[:includes]).map do |cn, mods|
+          "i:#{cn}=#{Array(mods).map(&:to_s).sort.join(',')}"
+        end)
+        parts.concat(sorted_by_class(file_index[:data_member_layouts]).map { |cn, l| "d:#{cn}=#{l.inspect}" })
+        parts.concat(sorted_by_class(file_index[:struct_member_layouts]).map { |cn, l| "t:#{cn}=#{l.inspect}" })
+      end
+
+      # A class-keyed table's pairs sorted by class name (stringified) for a deterministic signature.
+      def sorted_by_class(table)
+        table.sort_by { |cn, _| cn.to_s }
+      end
+
+      # The method-existence and visibility surfaces of the declaration signature (kept out of
+      # {#declaration_signature} to hold its ABC budget). Both are consumed cross-file — the existence table
+      # by undefined-method suppression, the visibilities by the ADR-35 override-visibility rule.
+      def append_declaration_tables(parts, file_index)
+        file_index[:methods].sort_by { |cn, _| cn.to_s }.each do |cn, table|
+          table.sort_by { |m, _| m.to_s }.each { |m, kind| parts << "e:#{cn}##{m}=#{kind}" }
+        end
+        file_index[:method_visibilities].sort_by { |cn, _| cn.to_s }.each do |cn, table|
+          table.sort_by { |m, _| m.to_s }.each { |m, vis| parts << "v:#{cn}##{m}=#{vis}" }
+        end
+      end
+
+      # Appends one def-node table's per-method signature entries (name + parameter structure + def-start
+      # line) under `separator` (`#` instance / `.` singleton). Nodes here are always LIVE (both call sites —
+      # {#scan_summary_for_paths} and {#build_seed_bundle} — pass a freshly parsed single-file index), so the
+      # parameter structure and location are read directly.
+      def append_def_signatures(parts, defs, separator)
+        defs.sort_by { |cn, _| cn.to_s }.each do |class_name, methods|
+          methods.sort_by { |m, _| m.to_s }.each do |method_name, node|
+            parts << "m:#{class_name}#{separator}#{method_name}#{parameter_signature(node)}@#{def_start_line(node)}"
+          end
+        end
+      end
+
+      # ADR-89 WD1 — a compact, order-preserving descriptor of a def node's parameter STRUCTURE: each
+      # parameter's kind (required / optional / rest / post / keyword-required / keyword-optional /
+      # keyword-rest / block / forwarding) and name, plus default-PRESENCE (implied by the optional kinds).
+      # Names are included for all parameter positions: soundness-first (a keyword-name change is Liskov-
+      # visible to overriders; a positional-name change is rare and only over-conservatively keeps a
+      # dependent). Not the inferred parameter TYPE — this gate is deliberately syntactic.
+      def parameter_signature(node)
+        return "()" unless node.respond_to?(:parameters)
+
+        params = node.parameters
+        return "()" if params.nil?
+
+        parts = []
+        parts.concat(labelled_params(params.requireds, "r"))
+        parts.concat(labelled_params(params.optionals, "o"))
+        parts.concat(labelled_params(params.posts, "p"))
+        parts.concat(labelled_params(params.keywords) { |p| keyword_param_kind(p) })
+        parts.concat(rest_param_parts(params))
+        "(#{parts.join(',')})"
+      end
+
+      # The `<kind>:<name>` labels for a list of parameter nodes (nil → none). `kind` is a fixed String or a
+      # block computing it per node (for the keyword-required / keyword-optional split).
+      def labelled_params(nodes, kind = nil)
+        (nodes || []).map { |p| "#{kind || yield(p)}:#{param_label(p)}" }
+      end
+
+      # The single rest / keyword-rest / block parameter labels (each present at most once).
+      def rest_param_parts(params)
+        parts = []
+        parts << "*:#{param_label(params.rest)}" if params.rest
+        parts << "**:#{param_label(params.keyword_rest)}" if params.keyword_rest
+        parts << "&:#{param_label(params.block)}" if params.block
+        parts
+      end
+
+      def keyword_param_kind(param)
+        param.is_a?(Prism::OptionalKeywordParameterNode) ? "ko" : "kr"
+      end
+
+      # A parameter node's name, or a class-tagged sentinel for the nameless / destructuring forms
+      # (`MultiTargetNode`, an anonymous `*` / `**` / `&`, `NoKeywordsParameterNode`, `ForwardingParameterNode`).
+      def param_label(param)
+        return "" if param.nil?
+
+        param.respond_to?(:name) && param.name ? param.name.to_s : param.class.name.split("::").last
+      end
+
+      # The 1-based start line of a live def node (the `project_definition_site` an ADR-17 consumer embeds).
+      def def_start_line(node)
+        node.respond_to?(:location) ? node.location.start_line : 0
+      end
+
+      # B1 — the SHA-256 of `source` with every comment's byte range excised (a line comment ends before its
+      # newline, so the newline is KEPT: stripping it preserves the line count, hence every def's start line
+      # and the whole engine bundle). Two revisions of a file that differ ONLY in comment text therefore share
+      # a code fingerprint — the signal the bundle-equality gate uses to prove a changed file's *code* (and so
+      # every code-derived cross-file fact the engine and code-reading plugins produce from it) is unchanged.
+      # A comment that adds or removes a LINE shifts subsequent code, so the fingerprint changes (the gate then
+      # conservatively keeps the file's dependents — a line shift can move a def the ADR-17 diagnostic names).
+      def code_fingerprint(source, comments)
+        bytes = source.b
+        return Digest::SHA256.hexdigest(bytes) if comments.empty?
+
+        result = +"".b
+        cursor = 0
+        comments.sort_by { |comment| comment.location.start_offset }.each do |comment|
+          loc = comment.location
+          result << bytes.byteslice(cursor, loc.start_offset - cursor) if loc.start_offset > cursor
+          cursor = loc.end_offset if loc.end_offset > cursor
+        end
+        result << bytes.byteslice(cursor, bytes.bytesize - cursor)
+        Digest::SHA256.hexdigest(result)
+      end
+
+      # Combined single-parse cross-file pre-pass used by the project-wide runner pre-pass
+      # ({Analysis::Runner::ProjectPrePasses#discover}). {#discovered_classes_for_paths} and
+      # {#discovered_def_index_for_paths} each `Prism.parse` every project file independently; this walks the
+      # project ONCE, parsing each file a single time and driving BOTH collectors over the same tree, then
+      # returns `{ classes:, def_index: }`. Each file is parsed, collected, and dropped before the next
+      # iteration, so no more than one AST is held alive at a time (peak RSS stays flat on large projects).
+      #
+      # Error degradation is identical to the two independent loops it replaces: a read / parse failure (the
+      # rescue's real target) contributes nothing to either table. The subset-scoped callers
+      # ({IncrementalSession}, `coverage --protection`) keep calling the individual methods unchanged.
+      #
+      # @param paths [Array<String>] project file paths.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{Symbol => Object}] `{ classes: Hash, def_index: Hash }`.
+      def discovered_project_index_for_paths(paths, buffer: nil)
+        classes = {}
+        acc = new_def_index_accumulator
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          root = Prism.parse(File.read(physical), filepath: path).value
+          collect_class_decls(root, [], classes)
+          accumulate_project_index(acc, path, root)
+        rescue StandardError
+          # Skip files that fail to parse or read; the per-file analyzer surfaces the parse error separately.
+          next
+        end
+        { classes: classes.freeze, def_index: finalize_def_index(acc) }
+      end
+
+      # ADR-85 WD2 — the incremental cross-file discovery pass. The bundle-driven twin of
+      # {#discovered_project_index_for_paths}: instead of parsing + walking every file, it folds each file's
+      # cached per-file *seed bundle* (plain-data tables + `(node_id, name, fingerprint)` def-node handles),
+      # re-walking ONLY the files whose current digest does not match their cached bundle (changed / added).
+      # Rebuilds in canonical file order — the sound reconstruction (the merged tables are Set-union / later-wins
+      # / whole-project-finalize, so a changed file cannot be delta-patched, only re-folded in place; recon Q2).
+      #
+      # Returns `{ classes:, def_index:, bundles: }` — `bundles` is the CURRENT per-file bundle set (cached ones
+      # reused, changed ones refreshed, removed ones absent) so the caller persists the up-to-date snapshot.
+      # A re-walked file's methods stay LIVE `Prism::DefNode`s in the returned index (no on-demand re-parse for
+      # a file we just walked); an unchanged file's methods are {DefHandle}s the accessor choke points resolve
+      # lazily. On a cold run (`seed_bundles` empty) every file is re-walked, so the index is entirely live —
+      # identical to {#discovered_project_index_for_paths} — while the bundles are built for the next run.
+      #
+      # @param paths [Array<String>] project file paths, in canonical order.
+      # @param seed_bundles [Hash{String => Hash}] the prior run's per-file bundles, keyed by logical path.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @return [Hash{Symbol => Object}] `{ classes:, def_index:, bundles: }`.
+      def discovered_project_index_incremental(paths, seed_bundles:, buffer: nil)
+        classes = {}
+        acc = new_def_index_accumulator
+        bundles = {}
+        paths.each do |path|
+          physical = buffer ? buffer.resolve(path) : path
+          digest = Cache::FileDigest.hexdigest(physical)
+          cached = seed_bundles[path]
+          if cached && cached[:digest] == digest
+            bundles[path] = cached
+            classes.merge!(cached[:classes])
+            fold_file_index(acc, bundle_to_file_index(cached, path))
+          else
+            source = File.read(physical)
+            parsed = Prism.parse(source, filepath: path)
+            root = parsed.value
+            file_index = build_file_index(path, root)
+            file_classes = {}
+            collect_class_decls(root, [], file_classes)
+            bundles[path] = build_seed_bundle(file_index, file_classes, digest,
+                                              code_fingerprint(source, parsed.comments))
+            classes.merge!(file_classes)
+            fold_file_index(acc, file_index)
+          end
+        rescue StandardError
+          # Skip files that fail to parse / read; the per-file analyzer surfaces the parse error separately.
+          next
+        end
+        { classes: classes.freeze, def_index: finalize_def_index(acc), bundles: bundles }
+      end
+
+      # Builds ONE file's isolated def-index contribution (live `Prism::DefNode`s) by folding it into a fresh
+      # accumulator — recon Q2(a)'s "constructible in isolation" property. Shared by the cold-baseline bundle
+      # build and the incremental changed-file re-walk.
+      def build_file_index(path, root)
+        file_acc = new_def_index_accumulator
+        accumulate_project_index(file_acc, path, root)
+        file_acc
+      end
+
+      # ADR-85 WD2 — folds a single file's isolated def-index contribution into the cross-file accumulator,
+      # applying EXACTLY the merge semantics {#accumulate_project_index} applies incrementally (def_nodes
+      # later-wins, def_sources first-wins, includes / class_sources accumulate, everything else later-wins).
+      # Polymorphic over the def-node value: a re-walked file's `file_index` carries live nodes; a cached
+      # bundle's carries {DefHandle}s. The merges never deref the value, so both fold identically.
+      def fold_file_index(acc, file_index)
+        fold_def_tables(acc, file_index)
+        fold_ancestry_tables(acc, file_index)
+      end
+
+      # def_nodes / singleton_def_nodes / method_visibilities / methods fold class-nested later-wins;
+      # def_sources / singleton_def_sources fold first-wins ({#fold_def_sources}).
+      def fold_def_tables(acc, file_index)
+        file_index[:def_nodes].each { |cn, methods| (acc[:def_nodes][cn] ||= {}).merge!(methods) }
+        file_index[:singleton_def_nodes].each { |cn, methods| (acc[:singleton_def_nodes][cn] ||= {}).merge!(methods) }
+        file_index[:method_visibilities].each { |cn, table| (acc[:method_visibilities][cn] ||= {}).merge!(table) }
+        file_index[:methods].each { |cn, table| (acc[:methods][cn] ||= {}).merge!(table) }
+        fold_def_sources(acc, :def_sources, file_index[:def_sources])
+        fold_def_sources(acc, :singleton_def_sources, file_index[:singleton_def_sources])
+      end
+
+      # A `"path:line"` source table (instance or singleton) is first-file-wins per `(class, method)` (`||=`),
+      # matching `merge_discovered_defs`.
+      def fold_def_sources(acc, key, file_sources)
+        file_sources.each do |cn, methods|
+          target = (acc[key][cn] ||= {})
+          methods.each { |method_name, source| target[method_name] ||= source }
+        end
+      end
+
+      # superclasses later-wins; includes / class_sources accumulate; member layouts later-wins.
+      def fold_ancestry_tables(acc, file_index)
+        acc[:superclasses].merge!(file_index[:superclasses])
+        file_index[:includes].each { |cn, mods| acc[:includes][cn] = ((acc[:includes][cn] || []) + mods).uniq }
+        file_index[:class_sources].each { |cn, files| (acc[:class_sources][cn] ||= Set.new).merge(files) }
+        acc[:data_member_layouts].merge!(file_index[:data_member_layouts])
+        acc[:struct_member_layouts].merge!(file_index[:struct_member_layouts])
+      end
+
+      # ADR-85 WD2 — converts a file's live single-file index + its class table into a Marshal-clean seed
+      # bundle: the plain-data tables verbatim, the def-node tables re-expressed as `[node_id, name,
+      # fingerprint]` triples (the path is the bundle key), the class-source names (path implicit), and the
+      # content digest that gates the bundle's reuse.
+      def build_seed_bundle(file_index, file_classes, digest, code_fingerprint)
+        {
+          digest: digest,
+          # B1 — the comment-stripped code fingerprint, so a recheck can prove this file's edit was
+          # comment-only and skip its dependents.
+          code_fingerprint: code_fingerprint,
+          # ADR-89 WD1 — the per-def SIGNATURE-shape declaration signature (bodies excluded, def lines kept),
+          # so a recheck can prove this file's body edit changed no declaration and skip its ancestry /
+          # file-level dependents. Computed from the same live `file_index` the bundle is built from, so the
+          # value stored here equals the one a later recheck recomputes for an unchanged declaration.
+          declaration_signature: declaration_signature(file_index),
+          classes: file_classes,
+          def_nodes: live_defs_to_bundle(file_index[:def_nodes]),
+          singleton_def_nodes: live_defs_to_bundle(file_index[:singleton_def_nodes]),
+          def_sources: file_index[:def_sources],
+          singleton_def_sources: file_index[:singleton_def_sources],
+          superclasses: file_index[:superclasses],
+          includes: file_index[:includes],
+          method_visibilities: file_index[:method_visibilities],
+          methods: file_index[:methods],
+          class_source_names: file_index[:class_sources].keys,
+          data_member_layouts: file_index[:data_member_layouts],
+          struct_member_layouts: file_index[:struct_member_layouts]
+        }
+      end
+
+      # ADR-85 WD2 — reconstitutes a cached bundle into a single-file index {#fold_file_index} folds: the
+      # def-node triples become {DefHandle}s bound to this file's `path`, and the class-source names become a
+      # `{name => Set[path]}` table (the shape `accumulate_project_index` produces).
+      def bundle_to_file_index(bundle, path)
+        {
+          def_nodes: bundle_defs_to_handles(bundle[:def_nodes], path),
+          singleton_def_nodes: bundle_defs_to_handles(bundle[:singleton_def_nodes], path),
+          def_sources: bundle[:def_sources],
+          # ADR-85 schema 7 — a pre-7 bundle lacks this key; the SCHEMA bump loads it as a clean cold rebuild,
+          # but default to `{}` so any in-flight fold stays total.
+          singleton_def_sources: bundle[:singleton_def_sources] || {},
+          superclasses: bundle[:superclasses],
+          includes: bundle[:includes],
+          method_visibilities: bundle[:method_visibilities],
+          methods: bundle[:methods],
+          class_sources: bundle[:class_source_names].to_h { |name| [name, Set[path]] },
+          data_member_layouts: bundle[:data_member_layouts],
+          struct_member_layouts: bundle[:struct_member_layouts]
+        }
+      end
+
+      # `{class => {method => Prism::DefNode}}` → `{class => {method => [node_id, name, fingerprint]}}`.
+      def live_defs_to_bundle(defs)
+        defs.transform_values do |methods|
+          methods.transform_values do |node|
+            [node.node_id, node.name.to_s, Digest::SHA256.hexdigest(node.location.slice)]
+          end
+        end
+      end
+
+      # `{class => {method => [node_id, name, fingerprint]}}` → `{class => {method => DefHandle}}` for `path`.
+      def bundle_defs_to_handles(defs, path)
+        defs.transform_values do |methods|
+          methods.transform_values do |(node_id, name, fingerprint)|
+            DefHandle.new(path: path, node_id: node_id, name: name, fingerprint: fingerprint)
+          end
+        end
+      end
+
+      # The empty per-run accumulator the def-index passes fold each file into.
+      def new_def_index_accumulator
+        { def_nodes: {}, singleton_def_nodes: {}, def_sources: {}, singleton_def_sources: {},
+          superclasses: {}, includes: {}, method_visibilities: {}, methods: {}, class_sources: {},
+          data_member_layouts: {}, struct_member_layouts: {} }
+      end
+
+      # Post-processes and freezes a fully-folded def-index accumulator.
+      def finalize_def_index(acc)
         # Cross-file method suppression is for the project's OWN accessors (attr_* / define_method / alias) — NOT for
         # plain `def`s. A cross-file `def` on a class is exactly the ADR-17 monkey-patch case the undefined-method rule
         # deliberately surfaces (fire + def-site annotation, nudging `pre_eval:`), so dropping the `def`-declared names
         # keeps that contract 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 singleton_def_nodes def_sources includes method_visibilities methods class_sources].each do |key|
+        %i[def_nodes singleton_def_nodes def_sources singleton_def_sources includes method_visibilities
+           methods class_sources].each do |key|
           acc[key].each_value(&:freeze)
         end
         acc.transform_values(&:freeze)
@@ -2073,9 +2485,12 @@ module Rigor
         # def-nodes ×2). See {#build_methods_and_def_nodes}.
         file_methods, file_def_nodes = build_methods_and_def_nodes(root)
         merge_discovered_defs(acc[:def_nodes], acc[:def_sources], path, file_def_nodes)
-        build_discovered_singleton_def_nodes(root).each do |class_name, methods|
-          (acc[:singleton_def_nodes][class_name] ||= {}).merge!(methods)
-        end
+        # ADR-46 slice 4 (singleton) — record the singleton-side `"path:line"` sources alongside the nodes,
+        # the exact mirror of the instance-side `merge_discovered_defs`, so a class/singleton-method body edit
+        # produces a changed `"Class.method"` fingerprint pair (and its call sites a symbol edge) instead of
+        # silently degrading to the file's full ancestry closure.
+        merge_discovered_defs(acc[:singleton_def_nodes], acc[:singleton_def_sources], path,
+                              build_discovered_singleton_def_nodes(root))
         superclasses = build_discovered_superclasses(root)
         includes = build_discovered_includes(root)
         acc[:superclasses].merge!(superclasses)
@@ -2152,7 +2567,7 @@ module Rigor
           record_class_new_constant_decl(node, qualified_prefix, accumulator)
         end
 
-        node.compact_child_nodes.each { |child| collect_class_decls(child, qualified_prefix, accumulator) }
+        node.rigor_each_child { |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`)
@@ -2219,7 +2634,7 @@ module Rigor
           return if record_meta_new_constant?(node, qualified_prefix, identity_table, discovered)
         end
 
-        node.compact_child_nodes.each do |child|
+        node.rigor_each_child do |child|
           record_declarations(child, qualified_prefix, identity_table, discovered)
         end
       end
@@ -2345,7 +2760,7 @@ module Rigor
         when Prism::UnlessNode
           propagate_unless_branches(node, table, current_scope)
         else
-          node.compact_child_nodes.each { |child| propagate(child, table, current_scope) }
+          node.rigor_each_child { |child| propagate(child, table, current_scope) }
         end
       end