rigortype 0.1.18 → 0.2.0

data/lib/rigor/inference/method_dispatcher/shape_dispatch.rb

@@ -81,6 +81,7 @@ module Rigor
           sum: :tuple_sum,
           min: :tuple_min,
           max: :tuple_max,
+          minmax: :tuple_minmax_pair,
           sort: :tuple_sort,
           reverse: :tuple_reverse,
           to_a: :tuple_to_a,
@@ -98,9 +99,16 @@ module Rigor
           uniq: :tuple_uniq,
           index: :tuple_find_index,
           find_index: :tuple_find_index,
-          rindex: :tuple_rindex
+          rindex: :tuple_rindex,
+          flatten: :tuple_flatten,
+          join: :tuple_join
         }.freeze
 
+        # Byte cap on a folded `tuple.join` result — a huge tuple times a
+        # long separator must not materialise an unbounded `Constant`.
+        TUPLE_JOIN_BYTE_LIMIT = 4096
+        private_constant :TUPLE_JOIN_BYTE_LIMIT
+
         HASH_SHAPE_HANDLERS = {
           size: :hash_size,
           length: :hash_size,
@@ -228,15 +236,8 @@ module Rigor
           end
 
           def dispatch_nominal_size(nominal, method_name, args)
-            if nominal.class_name == "String" && args.size == 1
-              string_binary = dispatch_string_binary_from_arg(method_name, args.first)
-              return string_binary if string_binary
-            end
-
-            if nominal.class_name == "Integer" && args.size == 1
-              integer_binary = dispatch_integer_binary_from_arg(method_name, args.first)
-              return integer_binary if integer_binary
-            end
+            projection = nominal_projection(nominal, method_name, args)
+            return projection if projection
 
             return nil unless args.empty?
 
@@ -246,6 +247,106 @@ module Rigor
             Type::Combinator.non_negative_int
           end
 
+          # Arg-/method-driven precision projections for a `Nominal`
+          # receiver, consulted ahead of the no-arg size tier. Each
+          # branch gates on the class name first so unrelated nominals
+          # skip the work. Returns nil when no projection applies.
+          def nominal_projection(nominal, method_name, args)
+            case nominal.class_name
+            when "String"
+              dispatch_string_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Integer"
+              dispatch_integer_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Array"
+              case method_name
+              when :flatten then array_nominal_flatten(nominal, args)
+              when :compact then array_nominal_compact(nominal, args)
+              end
+            end
+          end
+
+          # `Array[T]#compact` — `compact` removes every `nil` element,
+          # so the result element type is `T` with its `nil` constituent
+          # stripped (`Array[Node?]#compact` → `Array[Node]`). Mirrors
+          # the `Tuple#compact` constant fold for the generic element
+          # case. Declines when the receiver carries no type argument
+          # (the RBS `Array[untyped]` answer is already maximal) or when
+          # `T` has no `nil` constituent to remove (the result equals the
+          # receiver, so the RBS tier's answer is already precise).
+          def array_nominal_compact(nominal, args)
+            return nil unless args.empty?
+
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            stripped = strip_nil_constituent(element)
+            return nil if stripped.equal?(element)
+
+            Type::Combinator.nominal_of("Array", type_args: [stripped])
+          end
+
+          # Removes the `nil` constituent from a (possibly union) type,
+          # returning the same object when there is nothing to remove so
+          # callers can detect the no-op cheaply. Kept local to the
+          # dispatch tier to avoid a dependency on the narrowing module.
+          def strip_nil_constituent(type)
+            case type
+            when Type::Constant
+              type.value.nil? ? Type::Combinator.bot : type
+            when Type::Nominal
+              type.class_name == "NilClass" ? Type::Combinator.bot : type
+            when Type::Union
+              kept = type.members.map { |m| strip_nil_constituent(m) }
+              return type if kept.zip(type.members).all? { |k, m| k.equal?(m) }
+
+              Type::Combinator.union(*kept)
+            else
+              type
+            end
+          end
+
+          # `Array[T]#flatten` (and `flatten(depth)`). When `T` is a
+          # nested `Array[U]` nominal, one flatten level yields the
+          # joined inner element type — `Array[Array[U]]#flatten` →
+          # `Array[U]`. When `T` is non-nested the result is `Array[T]`
+          # unchanged (Ruby returns a copy with the same element type).
+          # Multi-level nesting is handled conservatively: each level
+          # joins its element types, and a `depth` argument that does
+          # not fully resolve the nesting still produces a sound
+          # superset. Declines on an `Array` with no type argument
+          # (the RBS `Array[untyped]` answer is already as precise as
+          # we can be) and on a non-static depth argument.
+          def array_nominal_flatten(nominal, args)
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            flattened = flatten_nominal_element(element, depth)
+            Type::Combinator.nominal_of("Array", type_args: [flattened])
+          end
+
+          # Resolves the element type of a flattened `Array[element]`.
+          # Each `Array[U]` nesting level contributes `U`; the per-level
+          # element types are unioned. `depth < 0` recurses without
+          # bound; `depth == 0` stops (Ruby's `flatten(0)` is a no-op
+          # copy and returns the element unchanged).
+          def flatten_nominal_element(element, depth)
+            return element if depth.zero?
+            return element unless array_nominal?(element)
+
+            inner = element.type_args.first
+            return element if inner.nil?
+
+            flatten_nominal_element(inner, depth - 1)
+          end
+
+          def array_nominal?(type)
+            type.is_a?(Type::Nominal) && type.class_name == "Array" && !type.type_args.nil? &&
+              !type.type_args.empty?
+          end
+
           # Arg-type-driven String binary projections for any String-typed
           # receiver (including Nominal, Refined, and Difference fallbacks).
           # Called before the no-arg size guard so binary operators are seen.
@@ -479,8 +580,17 @@ module Rigor
                                                                %i[lowercase upcase] => :uppercase_string,
                                                                %i[uppercase upcase] => :refined_self,
                                                                %i[uppercase downcase] => :lowercase_string,
+                                                               # `numeric-string` is the full Ruby numeric-literal
+                                                               # grammar (since the predicate delegates to the
+                                                               # parser). `#downcase` preserves it — lowercasing a
+                                                               # literal (hex digits, `0X` / `E` prefixes) yields a
+                                                               # valid lowercase literal — but `#upcase` does NOT:
+                                                               # the rational / imaginary suffixes are lowercase-only
+                                                               # (`"1r".upcase == "1R"` is not a literal), so `upcase`
+                                                               # drops to the plain base `String` — still sound (the
+                                                               # result is a String), just no longer numeric.
                                                                %i[numeric downcase] => :refined_self,
-                                                               %i[numeric upcase] => :refined_self,
+                                                               %i[numeric upcase] => :base_string,
                                                                # Digit-only strings are case-invariant; the prefix
                                                                # letters in `0o…` / `0x…` are accepted by the
                                                                # predicate in either case so the predicate-subset
@@ -493,19 +603,19 @@ module Rigor
                                                                %i[hex_int downcase] => :refined_self,
                                                                %i[hex_int upcase] => :refined_self,
                                                                # v0.1.1 Track 1 slice 2 — `to_i` / `to_int` on a
-                                                               # known digit-only string. `decimal-int-string`
-                                                               # (`/\A\d+\z/`) and `numeric-string` (Rigor's
-                                                               # numeric-string predicate, ASCII digits) are
-                                                               # predicates over digit-only strings, so the parse
-                                                               # is total over the carrier domain and the result
-                                                               # is always `>= 0`. `non-negative-int` is the
-                                                               # tightest carrier that captures both the lower
-                                                               # bound and the integer-ness without inventing a
-                                                               # narrower carrier.
-                                                               %i[decimal_int to_i] => :non_negative_int,
-                                                               %i[decimal_int to_int] => :non_negative_int,
-                                                               %i[numeric to_i] => :non_negative_int,
-                                                               %i[numeric to_int] => :non_negative_int
+                                                               # `decimal-int-string` parses to an `Integer`. The
+                                                               # carrier is `universal_int`, NOT `non-negative-int`:
+                                                               # the predicate `/\A-?\d+\z/` admits a leading sign, so
+                                                               # `"-7"` is a valid decimal-int-string and
+                                                               # `"-7".to_i == -7 < 0`. `String#to_i` is total (never
+                                                               # raises), so the projection is sound — just signed.
+                                                               # `numeric-string` is deliberately NOT projected to
+                                                               # `to_i` at all: it now spans the full numeric-literal
+                                                               # grammar, so a `"1.5"` / `"2i"` inhabitant has a
+                                                               # fractional or non-Integer parse — it falls through to
+                                                               # the RBS `Integer`.
+                                                               %i[decimal_int to_i] => :universal_int,
+                                                               %i[decimal_int to_int] => :universal_int
                                                              })
           private_constant :REFINED_STRING_PROJECTIONS
 
@@ -530,6 +640,8 @@ module Rigor
             when :uppercase_string then Type::Combinator.uppercase_string
             when :lowercase_string then Type::Combinator.lowercase_string
             when :non_negative_int then Type::Combinator.non_negative_int
+            when :universal_int then Type::Combinator.universal_int
+            when :base_string then refined.base
             end
           end
 
@@ -697,6 +809,37 @@ module Rigor
             Type::Combinator.constant_of(values.sum)
           end
 
+          # `tuple.join(sep = "")` — fold to the joined `Constant[String]`
+          # when every element is a `Constant` (its `to_s` is deterministic
+          # for the scalar value classes) and the separator is absent or a
+          # `Constant[String]`. Capped at `TUPLE_JOIN_BYTE_LIMIT`.
+          def tuple_join(tuple, _method_name, args)
+            sep = tuple_join_separator(args)
+            return nil if sep.nil?
+
+            values = constant_values(tuple.elements)
+            return nil if values.nil?
+
+            result = values.join(sep)
+            return nil if result.bytesize > TUPLE_JOIN_BYTE_LIMIT
+
+            Type::Combinator.constant_of(result)
+          rescue StandardError
+            nil
+          end
+
+          # The join separator: `""` for the no-arg form, the value of a
+          # single `Constant[String]` arg, or `nil` to decline.
+          def tuple_join_separator(args)
+            return "" if args.empty?
+            return nil unless args.size == 1
+
+            arg = args.first
+            return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(String)
+
+            arg.value
+          end
+
           # `tuple.min` / `tuple.max` — fold when every element is
           # a `Constant` whose values share a Ruby-comparable
           # domain. Empty tuples fold to `Constant[nil]`.
@@ -721,6 +864,32 @@ module Rigor
             nil
           end
 
+          # `tuple.minmax` — the `[min, max]` pair as a 2-slot
+          # `Tuple[Constant[min], Constant[max]]`, mirroring the
+          # `Range#minmax` fold. Every element must be a `Constant`
+          # and the values must Ruby-compare; an empty tuple folds to
+          # `Tuple[nil, nil]` (Ruby's `[].minmax`), incomparable
+          # mixed-class values decline.
+          def tuple_minmax_pair(tuple, _method_name, args)
+            return nil unless args.empty?
+
+            if tuple.elements.empty?
+              nil_const = Type::Combinator.constant_of(nil)
+              return Type::Combinator.tuple_of(nil_const, nil_const)
+            end
+
+            values = constant_values(tuple.elements)
+            return nil if values.nil?
+
+            low, high = values.minmax
+            Type::Combinator.tuple_of(
+              Type::Combinator.constant_of(low),
+              Type::Combinator.constant_of(high)
+            )
+          rescue StandardError
+            nil
+          end
+
           # `tuple.sort` — every element must be a `Constant` and
           # the values must Ruby-compare. The result is a Tuple
           # with the same elements in sorted order. Comparison
@@ -875,6 +1044,50 @@ module Rigor
             constant_index(tuple, args) { |elements, value| elements.index { |e| e.value == value } }
           end
 
+          # `tuple.flatten` / `tuple.flatten(depth)` — recursively
+          # flattens nested Tuple elements into a single Tuple. With
+          # no argument the flatten is unbounded (matching Ruby's
+          # `Array#flatten`); a `Constant[Integer]` depth bounds it.
+          # Non-Tuple elements (scalars, `Array[T]` nominals, …) pass
+          # through unchanged at their level. A non-static depth
+          # argument (or a non-Integer one) declines so RBS answers.
+          def tuple_flatten(tuple, _method_name, args)
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            Type::Combinator.tuple_of(*flatten_elements(tuple.elements, depth))
+          end
+
+          # Returns the requested flatten depth: `-1` for the no-arg
+          # (unbounded) form, the Integer for a `Constant[Integer]`
+          # argument, or `:decline` for any non-static / wrong-arity
+          # argument shape.
+          def tuple_flatten_depth(args)
+            return -1 if args.empty?
+            return :decline unless args.size == 1
+
+            arg = args.first
+            return arg.value if arg.is_a?(Type::Constant) && arg.value.is_a?(Integer)
+
+            :decline
+          end
+
+          # Flattens a list of element types to `depth` levels.
+          # `depth < 0` means unbounded. A Tuple element is spliced
+          # in (recursing with `depth - 1`); everything else passes
+          # through at this level.
+          def flatten_elements(elements, depth)
+            return elements if depth.zero?
+
+            elements.flat_map do |element|
+              if element.is_a?(Type::Tuple)
+                flatten_elements(element.elements, depth - 1)
+              else
+                [element]
+              end
+            end
+          end
+
           # `rindex(obj)` → the LAST matching index, same decidability gate.
           def tuple_rindex(tuple, _method_name, args)
             constant_index(tuple, args) { |elements, value| elements.rindex { |e| e.value == value } }

data/lib/rigor/inference/method_dispatcher/struct_folding.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+require_relative "singleton_folding"
+require_relative "member_shape_projection"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # ADR-48 Struct follow-up — `Struct.new` value folding, the mutable
+      # sibling of {DataFolding}. Same fully-decidable-shape, degrade-on-any-
+      # uncertainty discipline, with one extra premise the immutable `Data`
+      # path does not need: **mutation soundness.**
+      #
+      # A `Struct` instance is mutable (`s.x = v`, `s[:x] = v`, escape), so a
+      # member map bound to a variable can be invalidated by a later write.
+      # This slice (ADR-48 slices 1+2 in the sound *transient* form) folds a
+      # member read ONLY off a **fresh** instance — the transient receiver of
+      # a `.new(...).x` / `.with(...).x` chain, which provably cannot have
+      # been mutated between materialisation and the read. A member read off
+      # a *stored* binding degrades to `Dynamic[top]` rather than fold a
+      # possibly-stale value. Promoting the fold to mutation-free bound
+      # locals is the deferred slice 3 (relax the fresh-receiver gate to a
+      # fold-safe-local scan); precise mutated-member re-typing is slice 4.
+      #
+      # Responsibilities:
+      #
+      # 1. `Struct.new(:x, :y [, keyword_init: <bool>])` on a
+      #    `Singleton[Struct]` receiver, literal-Symbol members, NO block ->
+      #    `StructClass{members:, keyword_init:}`. A block / non-literal
+      #    members defer.
+      # 2. `.new` / `.[]` on a `StructClass` (or a `Singleton[Point]` with a
+      #    recorded struct layout) -> a `StructInstance`, the member map built
+      #    from the call's arguments (positional or keyword per the class's
+      #    `keyword_init`). A form / arity mismatch degrades to `Dynamic[top]`
+      #    rather than a wrong member map. `.members` on the class folds.
+      # 3. member reads + `[]` / `to_h` / `deconstruct` / `deconstruct_keys`
+      #    / `members` / `with` on a *fresh* `StructInstance` -> the precise
+      #    projected type; member *setters* (`s.x = v`) return the assigned
+      #    value type. Unhandled / stored-receiver calls return nil so the
+      #    pipeline projects the instance to its nominal through RbsDispatch.
+      #
+      # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+      module StructFolding
+        module_function
+
+        # The `[]` / `to_h` / `deconstruct` / `members` / `with` projections
+        # and the reader-redefinition guard are shared with {DataFolding}.
+        extend MemberShapeProjection
+
+        # @return [Rigor::Type, nil] the folded result, or nil to defer.
+        def try_dispatch(context)
+          receiver = context.receiver
+
+          return fold_struct_new(context) if SingletonFolding.receiver?(receiver, "Struct")
+
+          case receiver
+          when Type::StructClass
+            dispatch_struct_class(receiver, context)
+          when Type::StructInstance
+            fold_instance(receiver, context)
+          when Type::Singleton
+            fold_named_new(receiver, context)
+          end
+        end
+
+        # A `Struct.new`-defined class assigned to a constant (or a
+        # `class Point < Struct.new(...)` subclass) is canonicalised by the
+        # engine to `Singleton[Point]`, not a `StructClass` — so its member
+        # layout is read from the project side-table the scope indexer built
+        # (`Scope#struct_member_layout`) rather than from the receiver
+        # carrier.
+        def fold_named_new(singleton, context)
+          scope = context.scope
+          return nil if scope.nil?
+
+          layout = scope.struct_member_layout(singleton.class_name)
+          return nil if layout.nil?
+
+          materialize_instance(layout[:members], layout[:keyword_init], singleton.class_name, context)
+        end
+
+        # --- 1. Struct.new(:x, :y) --------------------------------------
+
+        def fold_struct_new(context)
+          return nil unless context.method_name == :new
+          # Block-form (`Struct.new(:x) do ... end`) defers — the named
+          # constant/subclass forms still fold via the layout side-table.
+          return nil unless context.block_type.nil?
+
+          parsed = parse_struct_new_args(context.args)
+          return nil if parsed.nil?
+
+          Type::Combinator.struct_class_of(members: parsed[:members], keyword_init: parsed[:keyword_init])
+        end
+
+        # Parses `Struct.new`'s arguments into `{ members:, keyword_init: }`,
+        # or nil when any argument is non-conforming (a dynamic member name,
+        # an unexpected trailing keyword). Handles the optional leading String
+        # class name and the trailing `keyword_init:` option hash.
+        def parse_struct_new_args(args)
+          rest = args.dup
+          keyword_init = false
+
+          if rest.last.is_a?(Type::HashShape)
+            options = rest.pop
+            return nil unless struct_options_hash?(options)
+
+            value = options.pairs[:keyword_init]
+            keyword_init = value.is_a?(Type::Constant) && value.value == true
+          end
+
+          # Optional leading String name: `Struct.new("Point", :x, :y)`.
+          rest = rest[1..] if rest.first.is_a?(Type::Constant) && rest.first.value.is_a?(String)
+
+          members = []
+          rest.each do |arg|
+            return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(Symbol)
+
+            members << arg.value
+          end
+          return nil if members.empty?
+          return nil unless members.uniq.size == members.size
+
+          { members: members, keyword_init: keyword_init }
+        end
+
+        # A trailing hash is the `Struct.new` options hash only when it is a
+        # closed shape whose sole key is `:keyword_init`. Any other key means
+        # the call is not a recognisable member-list definition -> defer.
+        def struct_options_hash?(shape)
+          shape.closed? && shape.optional_keys.empty? &&
+            shape.pairs.keys.all? { |key| key == :keyword_init }
+        end
+
+        # --- 2. Point.new(...) / Point[...] / Point.members -------------
+
+        def dispatch_struct_class(struct_class, context)
+          case context.method_name
+          when :new, :[]
+            materialize_instance(struct_class.members, struct_class.keyword_init,
+                                 struct_class.class_name, context)
+          when :members
+            Type::Combinator.tuple_of(*struct_class.members.map { |name| Type::Combinator.constant_of(name) })
+          end
+        end
+
+        def materialize_instance(members, keyword_init, class_name, context)
+          return nil unless %i[new []].include?(context.method_name)
+
+          map = member_map_for_new(members, keyword_init, context)
+          return degraded_instance if map.nil?
+
+          Type::Combinator.struct_instance_of(members: map, class_name: class_name)
+        end
+
+        # Builds the member -> type map honouring the class's `keyword_init`
+        # flag: a `keyword_init: true` struct accepts only the keyword form,
+        # a positional struct only the positional form. The mismatched form
+        # is a different runtime shape, so it degrades rather than fold.
+        def member_map_for_new(members, keyword_init, context)
+          if keyword_new?(context)
+            keyword_init ? keyword_member_map(members, context.args) : nil
+          else
+            keyword_init ? nil : positional_member_map(members, context.args)
+          end
+        end
+
+        # `Point.new(x: 1)` arrives as a single trailing `HashShape` whose
+        # call node is a `KeywordHashNode`; distinguishing it from a
+        # positional hash needs the call node (both type to a `HashShape`).
+        def keyword_new?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          arguments = node.arguments&.arguments
+          return false if arguments.nil? || arguments.empty?
+
+          arguments.last.is_a?(Prism::KeywordHashNode)
+        end
+
+        # `Struct.new(:a, :b).new(v)` is legal — trailing members default to
+        # `nil` — so fewer positionals than members pad with `Constant[nil]`;
+        # more positionals than members is an ArgumentError -> degrade.
+        def positional_member_map(members, args)
+          return nil if args.size > members.size
+
+          members.each_with_index.to_h do |name, index|
+            [name, index < args.size ? args[index] : Type::Combinator.constant_of(nil)]
+          end
+        end
+
+        # `Struct.new(:a, :b).new(a: 1)` is legal — omitted members default
+        # to `nil` — so a keyword subset pads the rest; an unknown key is an
+        # ArgumentError -> degrade.
+        def keyword_member_map(members, args)
+          return nil unless args.size == 1
+
+          shape = args.first
+          return nil unless shape.is_a?(Type::HashShape) && shape.closed?
+          return nil unless shape.optional_keys.empty?
+          return nil unless shape.pairs.keys.all? { |key| members.include?(key) }
+
+          members.to_h { |name| [name, shape.pairs[name] || Type::Combinator.constant_of(nil)] }
+        end
+
+        # A `.new` whose arguments cannot soundly populate the member map
+        # degrades to `Dynamic[top]` (today's behaviour for `Struct.new(...)`
+        # instances), never a wrong map.
+        def degraded_instance
+          Type::Combinator.untyped
+        end
+
+        # --- 3. inst.x / inst.x = v / inst[...] / inst.to_h / ... -------
+
+        def fold_instance(instance, context)
+          method_name = context.method_name
+          args = context.args
+          members = instance.members
+
+          # Member setter `s.x = v`: returns the assigned value type. Sound
+          # regardless of mutation state (it models the setter's own return),
+          # and avoids a fall-through undefined-method on a writer the
+          # existence table does not register.
+          setter = member_setter_target(method_name, members)
+          return args.first if setter && args.size == 1
+
+          foldable = foldable_receiver?(context)
+
+          if members.key?(method_name) && args.empty? && !reader_overridden?(instance, method_name, context.scope)
+            # A stored receiver folds only when the bound local is proven
+            # fold-safe (ADR-48 slice 3 — never mutated / aliased / escaped);
+            # otherwise the member value may be stale, so it degrades to
+            # `Dynamic[top]` (not nil -> no undefined-method fall-through).
+            return foldable ? members.fetch(method_name) : Type::Combinator.untyped
+          end
+
+          # Projections fold only off a foldable (fresh, or proven fold-safe)
+          # instance; off any other stored binding they defer to Struct's RBS
+          # (`to_h` / `[]` / `members` / `deconstruct*` all exist on `Struct`),
+          # which is sound and non-regressive.
+          return nil unless foldable
+
+          fold_fresh_projection(instance, method_name, args)
+        end
+
+        def fold_fresh_projection(instance, method_name, args)
+          case method_name
+          when :[] then instance_index(instance, args)
+          when :to_h, :to_hash then instance_to_h(instance)
+          when :deconstruct then instance_deconstruct(instance)
+          when :deconstruct_keys then instance_deconstruct_keys(instance, args)
+          when :members then instance_members(instance)
+          when :with
+            instance_with(instance, args) do |members, class_name|
+              Type::Combinator.struct_instance_of(members: members, class_name: class_name)
+            end
+          end
+        end
+
+        # The member name a `:<member>=` setter targets, or nil. Comparison
+        # operators (`==`, `>=`, ...) end with `=` too but never strip to a
+        # member symbol, so they fall through to the normal dispatch path.
+        def member_setter_target(method_name, members)
+          name = method_name.to_s
+          return nil unless name.end_with?("=")
+
+          base = name[0..-2].to_sym
+          members.key?(base) ? base : nil
+        end
+
+        # A member read is foldable when the receiver is either FRESH (the
+        # transient result of a `.new(...)`/`.with(...)` chain, which cannot
+        # have been mutated between materialisation and this read) or a
+        # FOLD-SAFE stored local (ADR-48 slice 3 — `StructFoldSafety` proved
+        # the binding is never mutated / aliased / escaped in its scope).
+        def foldable_receiver?(context)
+          fresh_receiver?(context) || fold_safe_local_receiver?(context)
+        end
+
+        # A fresh receiver is the transient result of a chained call
+        # (`Point.new(1, 2).x`, `inst.with(x: 9).y`).
+        def fresh_receiver?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          node.receiver.is_a?(Prism::CallNode)
+        end
+
+        # A fold-safe stored receiver is a local-variable read whose name the
+        # body's fold-safe set (on the scope) marks as never mutated.
+        def fold_safe_local_receiver?(context)
+          node = context.call_node
+          receiver = node&.receiver
+          scope = context.scope
+          return false unless receiver.is_a?(Prism::LocalVariableReadNode) && scope
+
+          scope.struct_fold_safe?(receiver.name)
+        end
+      end
+    end
+  end
+end