rigortype 0.3.8 → 0.3.9

data/lib/rigor/inference/statement_evaluator.rb

@@ -14,9 +14,11 @@ require_relative "body_fixpoint"
 require_relative "captured_locals"
 require_relative "dynamic_origin"
 require_relative "../analysis/check_rules/inferred_param_guard"
+require_relative "../analysis/check_rules/published_constant_guard"
 require_relative "struct_fold_safety"
 require_relative "closure_escape_analyzer"
 require_relative "content_join"
+require_relative "element_read_widening"
 require_relative "indexed_narrowing"
 require_relative "index_write_widening"
 require_relative "method_dispatcher"
@@ -107,7 +109,9 @@ module Rigor
         Prism::SingletonClassNode => :eval_singleton_class,
         Prism::CallNode => :eval_call,
         Prism::BlockNode => :eval_block,
+        Prism::LambdaNode => :eval_lambda,
         Prism::ReturnNode => :eval_return,
+        Prism::NextNode => :eval_next,
         Prism::BreakNode => :eval_break,
         Prism::MatchWriteNode => :eval_match_write
       }.freeze
@@ -121,6 +125,18 @@ module Rigor
       RETURN_SINK_KEY = :rigor_return_sink
       private_constant :RETURN_SINK_KEY
 
+      # Thread-local sink (an Array of `[NextNode, Type]`) collecting the value each `next` carries out of the block it
+      # leaves, so `ExpressionTyper#type_block_body` can join those arms into the block's value type. Issue #841: the
+      # block-return pass modelled only the fall-through tail, so `ops.all? { |o| next false unless o; true }` read as
+      # `Constant[true]` and folded the call to always-truthy — the same defect `RETURN_SINK_KEY` fixes one level up for
+      # a method's early `return`. The flow value of a `next` stays `Bot`.
+      #
+      # The sink also collects `next`s from nested blocks / loops / defs evaluated under the same installation (they do
+      # not install their own), so the consumer filters by node identity against a statically computed
+      # directly-targeting set, exactly as the break sink does. nil means "not collecting".
+      NEXT_SINK_KEY = :rigor_next_sink
+      private_constant :NEXT_SINK_KEY
+
       # Thread-local sink (an Array of `[BreakNode, Scope]`) collecting the scope at each `break` reached while
       # evaluating a loop body, so `eval_loop` / `eval_for` can join a `break`-path binding (`flag = true; break`) into
       # the loop continuation that the fall-through would otherwise drop. Stacks like the return sink: a nested loop
@@ -131,6 +147,19 @@ module Rigor
       BREAK_SINK_KEY = :rigor_break_sink
       private_constant :BREAK_SINK_KEY
 
+      # Thread-local sink (an Array of `[BreakNode, Type]`) collecting the value each `break` carries out of the
+      # construct it leaves. Issue #853: `break value` terminates the yielding CALL and is that call's value, so —
+      # unlike `next`, which {NEXT_SINK_KEY} joins into the block — these arms are consumed one level up, by
+      # `ExpressionTyper#call_dispatch_type_for`. Without them `ops.all? { |o| break false unless o; true }` folded to
+      # `Constant[true]` and warned about a program that really can answer false.
+      #
+      # Separate from {BREAK_SINK_KEY}, which records SCOPES for the loop-continuation join: the two consumers want
+      # different things from the same node, and a loop body evaluated under a call's collection must keep feeding its
+      # own sink. Both are filtered by node identity against a statically computed directly-targeting set, so a `break`
+      # that belongs to an inner loop or block never reaches the wrong consumer. nil means "not collecting".
+      BREAK_VALUE_SINK_KEY = :rigor_break_value_sink
+      private_constant :BREAK_VALUE_SINK_KEY
+
       # Lexical class frame: the `name:` field is the qualified class name as it would render in Ruby (e.g.,
       # `"Foo::Bar"`); the `singleton:` field is `true` for `class << self` frames so nested defs resolve to
       # singleton-method RBS lookups.
@@ -145,20 +174,18 @@ module Rigor
       EMPTY_NESTING = [].freeze
       private_constant :EMPTY_NESTING
 
-      # @param scope [Rigor::Scope]
-      # @param tracer [Rigor::Inference::FallbackTracer, nil]
-      # @param on_enter [#call, nil] optional `(node, scope) ->` callable
+      # @param on_enter — optional `(node, scope) ->` callable
       #   invoked once at the start of every {#evaluate} call (the node
       #   itself, *before* its handler runs). Threaded through every
       #   recursive `sub_eval` so the tooling that builds a per-node
       #   scope index (`Rigor::Inference::ScopeIndexer`) can record the
       #   entry scope for every Prism node the evaluator visits without
       #   the StatementEvaluator carrying any additional state itself.
-      # @param class_context [Array<ClassFrame>] lexical class scope used
+      # @param class_context — lexical class scope used
       #   by {#eval_def} to look up the method's RBS signature. Each
       #   `ClassNode`/`ModuleNode` entry pushes a frame; `SingletonClassNode`
       #   over `self` flips the innermost frame to singleton mode.
-      # @param converged_loop_recording [Boolean] when true (and an
+      # @param converged_loop_recording — when true (and an
       #   `on_enter` recorder is installed), {#eval_loop} re-evaluates a
       #   fixpoint-tracked loop body ONE extra time from the CONVERGED
       #   bindings so the last-visit-wins per-node scope index reflects
@@ -193,11 +220,40 @@ module Rigor
         [result, sink]
       end
 
+      # Runs `block` with a fresh `next` sink installed, then yields the collected `[NextNode, Type]` pairs to the
+      # caller. Stacks like the return sink, and for the same reason: a block body evaluated inside another block body's
+      # evaluation must not spill its arms into the outer collection. Used by `ExpressionTyper#type_block_body` to join
+      # the `next` arms into the block's value type.
+      def self.with_next_sink
+        previous = Thread.current[NEXT_SINK_KEY]
+        sink = []
+        Thread.current[NEXT_SINK_KEY] = sink
+        begin
+          result = yield
+        ensure
+          Thread.current[NEXT_SINK_KEY] = previous
+        end
+        [result, sink]
+      end
+
+      # Runs `block` with a fresh `break`-value sink installed, then yields the collected `[BreakNode, Type]` pairs to
+      # the caller. Stacks like the other sinks: a block body evaluated inside another block body's evaluation must not
+      # spill its arms into the outer collection. Used by `ExpressionTyper#call_dispatch_type_for` to union the `break`
+      # arms into the yielding call's type (issue #853).
+      def self.with_break_value_sink
+        previous = Thread.current[BREAK_VALUE_SINK_KEY]
+        sink = []
+        Thread.current[BREAK_VALUE_SINK_KEY] = sink
+        begin
+          result = yield
+        ensure
+          Thread.current[BREAK_VALUE_SINK_KEY] = previous
+        end
+        [result, sink]
+      end
+
       # Evaluate `node` under the receiver scope. Returns `[type, scope']` where `type` is the value the node produces
       # and `scope'` is the scope observable after the node has run. The receiver scope is never mutated.
-      #
-      # @param node [Prism::Node]
-      # @return [Array(Rigor::Type, Rigor::Scope)]
       def evaluate(node)
         @on_enter&.call(node, @scope)
 
@@ -246,14 +302,27 @@ module Rigor
       # to a follow-up; for now they degrade to "type the rhs, do not rebind" via the default branch in {#evaluate}.
       def eval_local_write(node)
         rhs_type, post_rhs = sub_eval(node.value, scope)
+        bound = bind_local_write(node, rhs_type, post_rhs)
+        # Issue #667 — `m = AppConfig::MODE` makes `m` a copy of a constant the reader's file does not
+        # declare, so `m == :production` folding to `true` is the project's configuration and not a logic
+        # error the author can see. Stamped LAST, across every binding path above: an RHS can be both an
+        # ADR-58 ivar copy and a published-constant copy (`@mode = AppConfig::MODE` in the ctor, `m = @mode`
+        # here), and the two marks answer unrelated questions.
+        return [rhs_type, bound] unless published_constant_copy?(node.value, rhs_type, post_rhs)
+
+        [rhs_type, bound.with_published_constant_mark(:local, node.name)]
+      end
+
+      # The binding half of {#eval_local_write}: the three mutually exclusive provenance paths a local write
+      # can take, unchanged from when they were inline.
+      def bind_local_write(node, rhs_type, post_rhs)
         # ADR-58 WD1 — `r = @right` where `@right`'s optionality is purely declaration-sourced makes `r`
         # declaration-sourced too (the survey's exact rotation/traversal shape `r = @right; r.key`). The mark is
         # computed on the RHS *value*'s provenance — a pure ivar read of a currently declaration-sourced ivar — so it
         # survives the local copy. Any other RHS (a call result, a method-local-nil-bearing value) leaves the local
         # flow-live and the diagnostic fires as before.
-        if declaration_sourced_ivar_read?(node.value, post_rhs)
-          return [rhs_type, post_rhs.with_declaration_sourced_local(node.name, rhs_type)]
-        end
+        return post_rhs.with_declaration_sourced_local(node.name, rhs_type) if
+          declaration_sourced_ivar_read?(node.value, post_rhs)
 
         bound = post_rhs.with_local(node.name, rhs_type)
         # ADR-67 WD6b — a local whose RHS is (transitively) rooted at an inferred parameter inherits the
@@ -261,14 +330,24 @@ module Rigor
         # same lower-bound reason (`vindex = codepoints[i] - x; vindex < y`). The mark is STICKY across
         # narrowing/joins (see `Scope#without_inferred_param_mark`), so a genuine rewrite from a non-param RHS
         # must clear it here. No-op unless the `parameter_inference:` gate seeded a parameter this RHS reaches.
-        if Analysis::CheckRules::InferredParamGuard.rooted?(node.value, scope)
-          return [rhs_type, bound.with_inferred_param_mark(node.name)]
-        end
+        return bound.with_inferred_param_mark(node.name) if
+          Analysis::CheckRules::InferredParamGuard.rooted?(node.value, scope)
 
         bound = bound.without_inferred_param_mark(node.name)
         bound = bound.with_local_origin(node.name, rhs_origin(node.value, post_rhs, rhs_type))
-        bound = bound.with_optimistic_local(node.name, optimistic_rhs_origin(node.value, post_rhs))
-        [rhs_type, bound]
+        bound.with_optimistic_local(node.name, optimistic_rhs_origin(node.value, post_rhs))
+      end
+
+      # Issue #667 — true when this write copies a value whose constancy rests on a foreign published
+      # constant. The `Type::Constant` pre-gate is what keeps the question cheap and is not merely an
+      # optimisation: the mark exists to withhold `flow.always-truthy-condition`, which only ever fires on a
+      # predicate that folded, so a non-constant RHS has nothing to withhold. It also keeps the guard's one
+      # interprocedural hop off every `x = foo(y)` in a project that publishes anything at all — the same
+      # gate {Analysis::CheckRules::AlwaysTruthyConditionCollector} puts in front of it.
+      def published_constant_copy?(value_node, rhs_type, scope_after_rhs)
+        return false unless rhs_type.is_a?(Type::Constant)
+
+        Analysis::CheckRules::PublishedConstantGuard.rooted?(value_node, scope_after_rhs)
       end
 
       # Issue #286 — the optimistic-nil-free counterpart of {#rhs_origin}, differing in two ways. It does not
@@ -314,6 +393,11 @@ module Rigor
         bound = post_rhs.with_ivar(node.name, rhs_type)
         bound = bound.with_ivar_origin(node.name, rhs_origin(node.value, post_rhs, rhs_type))
         bound = bound.with_optimistic_ivar(node.name, optimistic_rhs_origin(node.value, post_rhs))
+        # Issue #667 — the ivar twin of the local stamp. This is the SAME-method half; the cross-method one
+        # (`@mode = AppConfig::MODE` in `initialize`, read in a sibling) rides the class-ivar census and is
+        # stamped by {#seed_instance_ivars}.
+        bound = bound.with_published_constant_mark(:ivar, node.name) if
+          published_constant_copy?(node.value, rhs_type, post_rhs)
         [rhs_type, bound]
       end
 
@@ -351,24 +435,38 @@ module Rigor
       # The class context a meta-new rvalue block is entered under, or nil when the rvalue is not that shape. The
       # KEY must be the one `ScopeIndexer` filed the body's defs and member layout under, so the two passes agree —
       # which is why the decision is delegated to the ScopeIndexer's own recognition rather than re-spelled here. A
-      # `Prism::ConstantWriteNode` whose rvalue `ScopeIndexer.meta_new_block_body` recognises is keyed by the
-      # constant's qualified name, one frame appended to the lexical context exactly as a `class Const` keyword body
-      # would be. Every other block form — a constant-PATH write (`A::B = Struct.new do … end`, which has no
-      # constant-keyed registration) or a shape the ScopeIndexer's stricter argument check rejects
-      # (`Const = Struct.new(*names) do … end`) — was registered under the call site's anonymous name and is
-      # entered under that.
+      # constant write whose rvalue `ScopeIndexer.meta_new_block_body` recognises is keyed by the constant's
+      # qualified name, one frame appended to the lexical context exactly as a `class Const` keyword body would be
+      # — the path spelling included since [#703](https://github.com/rigortype/rigor/issues/703). A shape the
+      # ScopeIndexer's stricter argument check rejects (`Const = Struct.new(*names) do … end`) is registered under
+      # the call site's anonymous name and is entered under that.
       def meta_new_constant_body_context(node)
         call_node = node.value
         return nil unless call_node.is_a?(Prism::CallNode) && call_node.block.is_a?(Prism::BlockNode)
 
-        if node.is_a?(Prism::ConstantWriteNode) && ScopeIndexer.meta_new_block_body(node)
-          return @class_context + [ClassFrame.new(name: node.name.to_s, singleton: false)]
-        end
+        constant = meta_new_constant_context(node)
+        return constant if constant
 
         anonymous = AnonymousMetaClass.name_for(call_node, scope.source_path)
         anonymous && [ClassFrame.new(name: anonymous, singleton: false)]
       end
 
+      # The frame stack for a constant-keyed meta-new body, or nil when nothing keys it by a constant. A ROOTED
+      # path write re-anchors at the top level the way a rooted `class ::Rooted::Bar` header does
+      # ({#eval_class_or_module}), so the stack resets to that frame alone rather than gaining one under the
+      # enclosure — `current_class_path` joins the stack, and `ScopeIndexer`'s own prefix resets there too.
+      def meta_new_constant_context(node)
+        return nil unless ScopeIndexer.meta_new_block_body(node)
+
+        case node
+        when Prism::ConstantWriteNode
+          @class_context + [ClassFrame.new(name: node.name.to_s, singleton: false)]
+        when Prism::ConstantPathWriteNode
+          frame = ClassFrame.new(name: Source::ConstantPath.qualified_name(node.target), singleton: false)
+          Source::ConstantPath.rooted?(node.target) ? [frame] : @class_context + [frame]
+        end
+      end
+
       # Slice 7 phase 3 — compound writes (||=, &&=, +=/-=/...) for every variable kind. Each handler:
       #   1. Reads the current type from the appropriate scope
       #      binding map (or `Dynamic[Top]` when unbound).
@@ -550,10 +648,23 @@ module Rigor
       # join will not consume is pure overhead, and `<<` on a String buffer is one of the commonest calls
       # there is. The content-adder table skips a non-adding mutator (`pop`, `sort!`); `joinable_receiver?`
       # skips a receiver whose current binding is not a literal-shape carrier.
+      # Both mutator-receiver widenings, against one typing of the call's arguments: the bindings the
+      # receiver NAMES ({MutationWidening.widen_after_call}) and, when it names none because the
+      # receiver is an element read into a local, that element's pin inside its container
+      # ({ElementReadWidening.widen_element_read}, issue #643).
+      def widen_mutated_receivers(call_node, current_scope)
+        arg_types = mutator_arg_types(call_node, current_scope)
+        widened = MutationWidening.widen_after_call(call_node: call_node, current_scope: current_scope,
+                                                    arg_types: arg_types)
+        ElementReadWidening.widen_element_read(call_node: call_node, current_scope: widened, arg_types: arg_types)
+      end
+
       def mutator_arg_types(call_node, current_scope)
         return MutationWidening::NO_ARG_TYPES unless ContentJoin::CONTENT_ADDERS.include?(call_node.name)
-        return MutationWidening::NO_ARG_TYPES unless MutationWidening.joinable_receiver?(call_node.receiver,
-                                                                                         current_scope)
+        unless MutationWidening.joinable_receiver?(call_node.receiver, current_scope) ||
+               ElementReadWidening.joinable_element_read?(call_node.receiver, current_scope)
+          return MutationWidening::NO_ARG_TYPES
+        end
 
         content_arg_types(call_node, scope)
       end
@@ -1557,8 +1668,7 @@ module Rigor
         # Flow-folding G1 / G2 — widen a local- or instance-variable binding when the call is an in-place mutator on it
         # (e.g. `arms << x`, `@tags << hashtag`). Stops a literal-shape carrier (`Tuple` / `HashShape`) from outliving
         # its justification when the value is mutated. Always-safe (loses precision, never invents facts).
-        post_scope = MutationWidening.widen_after_call(call_node: node, current_scope: post_scope,
-                                                       arg_types: mutator_arg_types(node, post_scope))
+        post_scope = widen_mutated_receivers(node, post_scope)
         # ADR-48 slice 4 — Struct member-setter re-typing. After `s.x = v` on a fold-safe StructInstance local, rebind
         # `s` to a StructInstance with member `:x` replaced by the assigned type, so a later `s.x` folds to `v` and a
         # sibling `s.y` stays precise. `call_type` is the setter's own result (the assigned value type). Sound only for
@@ -2071,8 +2181,7 @@ module Rigor
         classification = classify_closure_escape(node)
         return post_scope if classification == :non_escaping
 
-        post_scope = drop_captured_narrowing(node.block, post_scope)
-        post_scope = widen_escaping_content_captures(node.block, post_scope)
+        post_scope = escaping_closure_captures(node.block, post_scope)
         post_scope.with_fact(
           Analysis::FactStore::Fact.new(
             bucket: :dynamic_origin,
@@ -2562,15 +2671,22 @@ module Rigor
       ].freeze
       private_constant :INDEX_WRITE_NODES
 
+      # The shared "not a content mutation" answer. This predicate runs on every node of every block, loop and
+      # method body it censuses (~950k calls on the lib self-check) and almost always declines, so a fresh
+      # `[nil, nil]` per decline was one of the largest allocation sites in the evaluator.
+      NO_CONTENT_MUTATION = [nil, nil].freeze
+      private_constant :NO_CONTENT_MUTATION
+
       # `[receiver_name, node]` when `node` is a content mutation whose receiver is a local variable satisfying `accept`
-      # (depth predicate), else `[nil, nil]`. Covers `[]=`-style CallNode mutators and the index-write node forms.
+      # (depth predicate), else the frozen `[nil, nil]`. Covers `[]=`-style CallNode mutators and the index-write node
+      # forms.
       def content_mutation_target(node)
         is_call_mutator = node.is_a?(Prism::CallNode) && ContentJoin::CONTENT_ADDERS.include?(node.name)
-        return [nil, nil] unless is_call_mutator || index_write?(node)
+        return NO_CONTENT_MUTATION unless is_call_mutator || index_write?(node)
 
         receiver = node.receiver
-        return [nil, nil] unless receiver.is_a?(Prism::LocalVariableReadNode)
-        return [nil, nil] unless yield(receiver)
+        return NO_CONTENT_MUTATION unless receiver.is_a?(Prism::LocalVariableReadNode)
+        return NO_CONTENT_MUTATION unless yield(receiver)
 
         [receiver.name, node]
       end
@@ -2675,6 +2791,32 @@ module Rigor
         sub_eval(node.body, scope)
       end
 
+      # Issue #878 — `->() { }` and `lambda { }` build the same object, so they MUST type the same. The `lambda`
+      # spelling is an ordinary call carrying a `Prism::BlockNode` and reaches {#eval_call}; the `->` spelling is a
+      # node of its own, and without an entry here it was only ever typed as an expression (`Proc`) with its body left
+      # un-evaluated. The body's reads and literals still reported — the rule walker falls back to the enclosing
+      # method's scope — but a write made INSIDE the body joined no scope, so every later read in the body kept the
+      # pre-write type.
+      #
+      # The body is run under the same entry scope `lambda { }` gets ({#build_block_entry_scope}, which binds the
+      # parameters and enters `self` opaque), and the continuation gets the same escaping-closure treatment: a lambda
+      # literal is a value that outlives the expression, exactly like the Proc `lambda` returns, so the outer locals it
+      # can rebind lose their narrowing rather than being written back through ADR-56's non-escaping fixpoint. Both
+      # halves are widenings — the two spellings now agree in both directions instead of `->` being the precise one.
+      def eval_lambda(node)
+        lambda_type = scope.type_of(node, tracer: tracer)
+        sub_eval(node.body, build_block_entry_scope(nil, node)) unless node.body.nil?
+
+        [lambda_type, escaping_closure_captures(node, scope)]
+      end
+
+      # The continuation effects of an escaping closure body: the outer locals it can rebind drop their narrowing, and
+      # the ones it content-mutates are floored. Shared by the two spellings — a block on an escaping call
+      # ({#record_closure_escape_if_any}) and a lambda literal ({#eval_lambda}) — so they cannot drift.
+      def escaping_closure_captures(closure_node, post_scope)
+        widen_escaping_content_captures(closure_node, drop_captured_narrowing(closure_node, post_scope))
+      end
+
       # Builds the entry scope for a block body. The block sees the outer scope's locals (Ruby's lexical scoping rule)
       # and adds bindings for every named block parameter on top. Parameter types come from the receiving method's RBS
       # signature when one is available; the rest default to `Dynamic[Top]`.
@@ -2703,7 +2845,11 @@ module Rigor
         params_root.locals.map(&:name)
       end
 
+      # A lambda literal has no receiving method, so it passes no call node and every parameter defaults to
+      # `Dynamic[Top]` — the same answer `lambda { |y| }` gets, where the implicit-self receiver yields no signature.
       def expected_block_param_types_for(call_node)
+        return [] if call_node.nil?
+
         receiver_type = call_node.receiver ? scope.type_of(call_node.receiver, tracer: tracer) : nil
         return [] if receiver_type.nil?
 
@@ -2846,7 +2992,15 @@ module Rigor
         # flow-live, so `seed_declaration_sourced_ivar` marks each seeded ivar: `possible-nil-receiver` then declines to
         # fire on the cross-method invariant unless a method-local write or narrowing makes the nil flow-live (which
         # drops the mark).
-        seeded.reduce(body_scope) { |acc, (name, type)| acc.seed_declaration_sourced_ivar(name, type) }
+        #
+        # Issue #667 — the same seed carries the published-constant mark for the ivars the class-ivar census
+        # found assigned straight from a foreign published constant, so `@mode == :production` in a sibling
+        # method withholds `flow.always-truthy-condition` the way the direct read of the constant does.
+        marked = scope.published_constant_ivars_for(path)
+        seeded.reduce(body_scope) do |acc, (name, type)|
+          stamped = acc.seed_declaration_sourced_ivar(name, type)
+          marked.include?(name) ? stamped.with_published_constant_mark(:ivar, name) : stamped
+        end
       end
 
       # Cvars are visible from BOTH instance and singleton method bodies of the enclosing class, so this seed is
@@ -3013,7 +3167,22 @@ module Rigor
       # inferred.
       def eval_return(node)
         sink = Thread.current[RETURN_SINK_KEY]
-        record_return_value(node, sink) if sink
+        sink << jump_value_type(node) if sink
+        [Type::Combinator.bot, scope]
+      end
+
+      # `next value` ends the current block invocation and makes `value` that invocation's result. Structurally the same
+      # story as {#eval_return} one level down: the control-transfer value is `Bot`, and the escaping value is recorded
+      # into the active `next` sink so `ExpressionTyper#type_block_body` joins it with the body's fall-through tail
+      # (issue #841). The node itself is recorded alongside the type because the sink also collects `next`s belonging to
+      # a nested block / loop / def; the consumer filters by identity.
+      #
+      # A `next` on a provably dead branch is never reached by the evaluator at all (`eval_if` / `eval_unless` skip the
+      # dead arm), so the join is flow-sensitive for free: `[1, 2].map { |x| next nil if x.nil?; x.to_s }` keeps its
+      # exact per-element answer.
+      def eval_next(node)
+        sink = Thread.current[NEXT_SINK_KEY]
+        sink << [node, jump_value_type(node)] if sink
         [Type::Combinator.bot, scope]
       end
 
@@ -3022,26 +3191,28 @@ module Rigor
       # would drop (`flag = true; break` -> `flag` is `false | true` after the loop). nil sink = a `break` not inside an
       # inferred loop body (a block targeting a method, or top-level) — left to the existing escaping-block / no-op
       # handling.
+      #
+      # Issue #853: the value it carries out belongs to the yielding CALL, so it is recorded into the separate
+      # break-value sink for `ExpressionTyper#call_dispatch_type_for` to union in. Both sinks are optional and
+      # independent — a loop body collects scopes while an enclosing call collects values from the same walk.
       def eval_break(node)
         sink = Thread.current[BREAK_SINK_KEY]
         sink << [node, scope] if sink
+        value_sink = Thread.current[BREAK_VALUE_SINK_KEY]
+        value_sink << [node, jump_value_type(node)] if value_sink
         [Type::Combinator.bot, scope]
       end
 
-      def record_return_value(node, sink)
+      # The value a `return` / `next` / `break` carries out of the construct it leaves. A bare jump carries nil; a
+      # single argument carries its own type; `return a, b, c` (and `next` / `break` alike) packs `[a, b, c]`, so the
+      # corresponding Tuple is contributed element-by-element. The argument is evaluated under the entry scope and the
+      # resulting scope discarded — control leaves here, so nothing the argument binds is observable downstream.
+      def jump_value_type(node)
         args = node.arguments&.arguments || []
-        # `return` with no argument returns nil; `return a` records the argument's type; `return a, b, c` packs a Tuple
-        # — in Ruby a multi-value return yields the array `[a, b, c]`, so the inferred return contributes the
-        # corresponding Tuple element-by-element.
-        if args.empty?
-          sink << Type::Combinator.constant_of(nil)
-        elsif args.size == 1
-          type, = sub_eval(args.first, scope)
-          sink << type
-        else
-          element_types = args.map { |arg| sub_eval(arg, scope).first }
-          sink << Type::Combinator.tuple_of(*element_types)
-        end
+        return Type::Combinator.constant_of(nil) if args.empty?
+        return sub_eval(args.first, scope).first if args.size == 1
+
+        Type::Combinator.tuple_of(*args.map { |arg| sub_eval(arg, scope).first })
       end
 
       def sub_eval(node, with_scope, class_context: @class_context, lexical_nesting: @lexical_nesting)

data/lib/rigor/inference/string_mutation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # The String half of {MutationWidening}'s straight-line seam (issue #617 residue (4)).
+    #
+    # `s = +"ab"; s << "c"; s == "ab"` folded `flow.always-truthy-condition` on correct code: the seam
+    # responded to `Tuple` / `HashShape` / empty-witness carriers only, while a `Constant[String]` is just as
+    # falsified by an in-place mutator as a `Tuple` is by `<<`. The ADR-56 block-capture path already widened
+    # the same binding, so the two seams disagreed about one carrier.
+    #
+    # It lives beside `MutationWidening` rather than inside it because the tables here answer a different
+    # question from the Array / Hash ones: those partition a carrier's SHAPE evidence, this one partitions a
+    # VALUE pin and an emptiness proof.
+    module StringMutation
+      # Receiver-mutating String methods only. The non-bang siblings (`upcase` vs `upcase!`, `sub` vs `sub!`)
+      # return a new String and leave the receiver's value intact, so they stay precise.
+      MUTATORS = %i[
+        << concat insert prepend replace clear []= slice!
+        sub! gsub! tr! tr_s! delete! squeeze! succ! next!
+        upcase! downcase! capitalize! swapcase! reverse!
+        strip! lstrip! rstrip! chomp! chop! force_encoding
+      ].to_set.freeze
+
+      # The {MUTATORS} that can leave the receiver EMPTY, and so retract a `non-empty-string` refinement. The
+      # rest are appenders or same-length rewrites: `s << x` / `s.prepend(x)` / `s.upcase!` cannot empty a
+      # string that already holds a character, so the refinement is still provable afterwards.
+      EMPTYING_MUTATORS = %i[
+        replace clear slice! []=
+        sub! gsub! delete! squeeze! strip! lstrip! rstrip! chomp! chop!
+      ].to_set.freeze
+
+      module_function
+
+      # `Constant["ab"]` under a String mutator → the bare `String` nominal. The pinned value is what the
+      # mutation falsifies, and nothing else about the carrier survives it, so there is no `values: :keep`
+      # half to preserve the way a `Tuple`'s surviving slots have one: an appended, substituted or
+      # case-folded string is a different string.
+      #
+      # Only a String-valued `Constant` widens. Every other literal (`Integer`, `Symbol`, `Range`) can only
+      # reach this arm through a name in the Array or Hash table and not in {MUTATORS}, and answering for it
+      # would erase a value no in-place mutator on that class can change.
+      #
+      # `nil` — no widening — for every other input, which is the contract `MutationWidening#widen_for_mutator`
+      # signals a decline with.
+      def widen_constant(constant, method_name)
+        return nil unless constant?(constant)
+        return nil unless MUTATORS.include?(method_name)
+
+        Type::Combinator.nominal_of("String")
+      end
+
+      def constant?(type)
+        type.is_a?(Type::Constant) && type.value.is_a?(String)
+      end
+    end
+  end
+end

data/lib/rigor/inference/struct_fold_safety.rb

@@ -55,10 +55,10 @@ module Rigor
           node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
       end
 
-      # @param root [Prism::Node, nil] the local-variable scope to scan.
-      # @param layout_lookup [#call] a `String -> Array[Symbol] | nil` resolver mapping a constant receiver name to its
+      # @param root — the local-variable scope to scan.
+      # @param layout_lookup — a `String -> Array[Symbol] | nil` resolver mapping a constant receiver name to its
       #   struct member list.
-      # @return [Set<Symbol>] the fold-safe local names.
+      # @return the fold-safe local names.
       def fold_safe_locals(root, layout_lookup)
         return EMPTY if root.nil?
 
@@ -208,10 +208,9 @@ module Rigor
       # Nested `def` / `class` / `module` bodies are skipped: their statements do not run during THIS body's
       # evaluation. Blocks are descended into — they share `self`.
       #
-      # @param body [Prism::Node, nil]
-      # @param member_names [Enumerable<Symbol>] the receiver carrier's member names.
-      # @yieldparam name [Symbol] an unrecognised self-call selector.
-      # @yieldreturn [Boolean] whether that sibling method is itself self-fold-safe.
+      # @param member_names — the receiver carrier's member names.
+      # @yieldparam name — an unrecognised self-call selector.
+      # @yieldreturn whether that sibling method is itself self-fold-safe.
       def self_fold_safe_body?(body, member_names, &sibling_pure)
         return false if body.nil?
 

data/lib/rigor/inference/synthetic_method_index.rb

@@ -22,8 +22,7 @@ module Rigor
     class SyntheticMethodIndex
       attr_reader :entries, :class_names
 
-      # @param entries [Array<SyntheticMethod>]
-      # @param class_names [Array<String>, Set<String>] names of classes the substrate synthesises wholesale (ADR-36
+      # @param class_names — names of classes the substrate synthesises wholesale (ADR-36
       #   nested-class emission — the variant subclasses that have no RBS/source declaration of their own). Recorded so
       #   `Environment#class_known?` can resolve them as classes (their constant reference + `.new` dispatch) even
       #   though nothing else in the type universe declares them. Tier B/C method emissions leave this empty (their

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -40,26 +40,24 @@ module Rigor
     module SyntheticMethodScanner # rubocop:disable Metrics/ModuleLength
       module_function
 
-      # @param plugin_registry [Rigor::Plugin::Registry]
-      # @param paths [Array<String>] absolute paths to the project
+      # @param paths — absolute paths to the project
       #   source files to scan.
-      # @param environment [Rigor::Environment, nil] used for
+      # @param environment — used for
       #   inheritance resolution against RBS-known classes
       #   (ActiveRecord::Base, Dry::Struct, etc.) that aren't
       #   declared in project source.
-      # @param fact_store [Rigor::Plugin::FactStore, nil]
+      # @param fact_store —
       #   the per-run cross-plugin fact store. ADR-18 lookups
       #   (`Plugin::Macro::HeredocTemplate::Emit#returns_from_arg`)
       #   consult this at scan time to resolve per-call-site
       #   return types from published facts; without it, those
       #   emit rows fall back to their static `returns:` (or
       #   `"untyped"` → `Dynamic[Top]`).
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
+      # @param buffer —
       #   editor-mode buffer binding. When set, reads for the
       #   logical path resolve to the buffer's physical path so
       #   the pre-pass sees the in-flight bytes instead of the
       #   on-disk copy.
-      # @return [Rigor::Inference::SyntheticMethodIndex]
       def scan(plugin_registry:, paths:, environment: nil, fact_store: nil, buffer: nil)
         templates = collect_templates(plugin_registry)
         registries = collect_trait_registries(plugin_registry)