branchproof 0.7.0 → 0.9.0

data/lib/branchproof/flow_instrumentation.rb

@@ -1,44 +1,65 @@
 # frozen_string_literal: true
 
 # Keep each bounded source rewrite together so its evaluation order can be audited.
-# rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+# rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ModuleLength
 
 module Branchproof
   # Source-location edits around Ruby's native matching and assignment operations.
   module FlowInstrumentation
     private
 
-    def render_flow(bytes, decision, nested)
+    def render_flow(bytes, decision, nested, encloses)
       metadata = decision.fetch(:instrumentation)
       case metadata.fetch(:type)
       when "safe_navigation"
         receiver = metadata.fetch(:receiver)
-        replacements = [flow_replacement(bytes, receiver, nested) do |expression|
+        replacements = [flow_replacement(bytes, receiver, nested, encloses) do |expression|
           "#{self.class::RUNTIME}.flow_receiver(#{decision[:id].inspect}, (#{expression}))"
         end]
-        flow_fragments(bytes, decision, nested, replacements)
+        flow_fragments(bytes, decision, nested, replacements, encloses)
       when "assignment"
         rhs = metadata.fetch(:rhs)
-        replacements = [flow_replacement(bytes, rhs, nested) do |expression|
-          "(begin; #{self.class::RUNTIME}.flow_path(#{decision[:id].inspect}, 1); (#{expression}); end)"
-        end]
-        expression = flow_fragments(bytes, decision, nested, replacements)
-        flow_frame(decision[:id], expression, default_path: 0)
+        identifier = decision[:id].inspect
+        replacements = []
+        if metadata[:receiver]
+          receiver = metadata.fetch(:receiver)
+          replacements << flow_replacement(bytes, receiver, nested, encloses) do |expression|
+            "#{self.class::RUNTIME}.flow_assignment_receiver(#{identifier}, (#{expression}))"
+          end
+          replacements << flow_replacement(bytes, rhs, nested, encloses) do |expression|
+            "(begin; #{self.class::RUNTIME}.flow_assignment_path(#{identifier}, 2); (#{expression}); end)"
+          end
+        else
+          replacements << flow_replacement(bytes, rhs, nested, encloses) do |expression|
+            "(begin; #{self.class::RUNTIME}.flow_path(#{identifier}, 1); (#{expression}); end)"
+          end
+        end
+        expression = flow_fragments(bytes, decision, nested, replacements, encloses)
+        if metadata[:receiver]
+          flow_assignment_frame(decision[:id], expression, default_path: 1)
+        else
+          flow_frame(decision[:id], expression, default_path: 0)
+        end
       when "case"
-        render_case_flow(bytes, decision, nested, metadata)
+        render_case_flow(bytes, decision, nested, metadata, encloses)
       when "case_match"
-        render_pattern_flow(bytes, decision, nested, metadata)
+        render_pattern_flow(bytes, decision, nested, metadata, encloses)
       else
         raise ArgumentError, "unknown instrumentation type: #{metadata[:type]}"
       end
     end
 
-    def render_case_flow(bytes, decision, nested, metadata)
+    def render_case_flow(bytes, decision, nested, metadata, encloses)
       identifier = decision[:id].inspect
       runtime = self.class::RUNTIME
       replacements = metadata.fetch(:candidates).map do |candidate|
-        flow_replacement(bytes, candidate, nested) do |expression|
-          "(begin; #{runtime}.flow_candidate(#{identifier}, #{candidate[:index]}); (#{expression}); end)"
+        flow_replacement(bytes, candidate, nested, encloses) do |expression|
+          if candidate[:splat]
+            splat_expression = expression.sub(/\A\*/, "")
+            "*(begin; #{runtime}.flow_candidate(#{identifier}, #{candidate[:index]}); (#{splat_expression}); end)"
+          else
+            "(begin; #{runtime}.flow_candidate(#{identifier}, #{candidate[:index]}); (#{expression}); end)"
+          end
         end
       end
       metadata.fetch(:branches).each do |branch|
@@ -55,10 +76,10 @@ module Branchproof
         replacements << { start: metadata.fetch(:end_start), length: 0,
                           text: "else; #{runtime}.flow_select(#{identifier}, #{index}); nil; " }
       end
-      flow_frame(decision[:id], flow_fragments(bytes, decision, nested, replacements))
+      flow_frame(decision[:id], flow_fragments(bytes, decision, nested, replacements, encloses))
     end
 
-    def render_pattern_flow(bytes, decision, nested, metadata)
+    def render_pattern_flow(bytes, decision, nested, metadata, encloses)
       identifier = decision[:id].inspect
       runtime = self.class::RUNTIME
       replacements = metadata.fetch(:branches).map do |branch|
@@ -71,27 +92,27 @@ module Branchproof
         replacements << { start: alternative[:insert_at], length: 0,
                           text: "; #{runtime}.flow_select(#{identifier}, #{alternative[:index]}); " }
       end
-      flow_frame(decision[:id], flow_fragments(bytes, decision, nested, replacements))
+      flow_frame(decision[:id], flow_fragments(bytes, decision, nested, replacements, encloses))
     end
 
-    def flow_replacement(bytes, location, nested)
+    def flow_replacement(bytes, location, nested, encloses)
       start = location.fetch(:byte_start)
       length = location.fetch(:byte_length)
-      { start: start, length: length, text: yield(render_children(bytes, start, length, nested)) }
+      { start: start, length: length, text: yield(render_children(bytes, start, length, nested, encloses)) }
     end
 
-    def flow_fragments(bytes, decision, nested, replacements)
+    def flow_fragments(bytes, decision, nested, replacements, encloses)
       cursor = decision.fetch(:byte_start)
       finish = cursor + decision.fetch(:byte_length)
       chunks = []
       replacements.sort_by { |edit| [edit[:start], edit[:length]] }.each do |edit|
         raise ArgumentError, "overlapping flow edits" if edit[:start] < cursor
 
-        chunks << render_children(bytes, cursor, edit[:start] - cursor, nested)
+        chunks << render_children(bytes, cursor, edit[:start] - cursor, nested, encloses)
         chunks << edit[:text]
         cursor = edit[:start] + edit[:length]
       end
-      chunks << render_children(bytes, cursor, finish - cursor, nested)
+      chunks << render_children(bytes, cursor, finish - cursor, nested, encloses)
       chunks.join
     end
 
@@ -101,7 +122,15 @@ module Branchproof
         "#{runtime}.flow_finish(#{decision_id.inspect}, (#{expression}), #{default_path.inspect}); ensure; " \
         "#{runtime}.leave(#{decision_id.inspect}); end; end)"
     end
+
+    def flow_assignment_frame(decision_id, expression, default_path: nil)
+      runtime = self.class::RUNTIME
+      "(begin; #{runtime}.enter(#{decision_id.inspect}); begin; " \
+        "#{runtime}.flow_assignment_finish(#{decision_id.inspect}, (#{expression}), " \
+        "#{default_path.inspect}); ensure; " \
+        "#{runtime}.leave(#{decision_id.inspect}); end; end)"
+    end
   end
 end
 
-# rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+# rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ModuleLength

data/lib/branchproof/focused_report.rb

@@ -6,16 +6,23 @@ require "pathname"
 module Branchproof
   # Terminal renderings grouped around conditions or tests.
   class FocusedReport
-    def initialize(document:, view:, level:, missing_only: false)
+    DECISION_TABLE_LABELS = { "true" => "T", "false" => "F", "dont_care" => "-" }.freeze
+
+    def initialize(document:, view:, level:, missing_only: false, coordinator: nil)
       @document = document || {}
       @view = view.to_sym
-      raise ArgumentError, "view must be :conditions or :tests" unless %i[conditions tests].include?(@view)
+      unless (Report::VIEWS - [:decisions]).include?(@view)
+        raise ArgumentError, "view must be :conditions, :tests, or :decision_tables"
+      end
 
       @level = level.to_i
       @missing_only = missing_only ? true : false
       @index = CoverageIndex.new(document: @document)
       @tests = @index.tests.to_h { |test| [test[:id].to_s, test] }
-      @coordinator = Report.from_document(document: @document, level: @level)
+      @test_name_counts = @index.tests.each_with_object(Hash.new(0)) do |test, counts|
+        counts[[test[:name], test[:relative_path], test[:line]]] += 1
+      end
+      @coordinator = coordinator || Report.from_document(document: @document, level: @level)
     end
 
     def render
@@ -39,14 +46,19 @@ module Branchproof
       lines << "Empty groups mean no recorded completed observation."
       lines << ""
       lines.concat(@coordinator.coverage_ladder_lines)
-      if @view == :conditions
+      case @view
+      when :conditions
         render_conditions(lines)
         render_alternatives(lines)
+      when :decision_tables
+        render_decision_tables(lines)
       else
         render_tests(lines)
       end
-      render_unowned(lines)
-      render_unsupported(lines)
+      unless @view == :decision_tables
+        render_unowned(lines)
+        render_unsupported(lines)
+      end
       Array(fetch(@document, :diagnostics)).each do |diagnostic|
         lines << "Diagnostic: #{@coordinator.diagnostic_message(diagnostic)}"
       end
@@ -117,6 +129,64 @@ module Branchproof
       end
     end
 
+    # One block per Boolean decision that carries a decision table. With
+    # --missing-only only uncovered, non-impossible rules remain: a rule proven
+    # impossible is not a missing obligation.
+    def render_decision_tables(lines)
+      rows = @index.decision_tables
+      rendered = 0
+      impossible = 0
+      rows.each do |row|
+        impossible += row[:impossible_rules].to_i
+        rules = @missing_only ? row[:rules].select { |rule| rule[:coverage].to_s == "missing" } : row[:rules]
+        next if @missing_only && rules.empty? && row[:status].to_s == "calculated"
+
+        rendered += 1
+        lines << "Decision: #{row[:decision_expression]}"
+        lines << "Location: #{location(row[:relative_path], row[:line], unavailable: "decision line unavailable")}"
+        lines << "Context: #{row[:context]}" unless row[:context].to_s.empty?
+        if row[:status].to_s != "calculated"
+          lines << "Decision Table: NOT CALCULATED"
+          lines << "Reason: #{row[:reason]}"
+          lines << ""
+          next
+        end
+        lines << "Decision Table: #{row[:covered_rules]}/#{row[:required_rules]} rules covered" \
+                 "#{" (#{row[:percentage]}%)" unless row[:percentage].nil?}"
+        lines << "Reachability: not analyzed" unless row[:reachability_analyzed]
+        rules.each { |rule| render_decision_table_rule(lines, row, rule) }
+        lines << ""
+      end
+      lines << "No missing decision-table rules" if @missing_only && rendered.zero?
+      return unless impossible.positive?
+
+      lines << "#{impossible} statically impossible rule#{"s" unless impossible == 1} excluded"
+    end
+
+    def render_decision_table_rule(lines, row, rule)
+      signature = rule[:conditions].map { |item| DECISION_TABLE_LABELS.fetch(item.to_s, item.to_s) }.join
+      status = rule[:coverage].to_s.upcase
+      lines << "  #{rule[:label]} #{signature} => #{rule[:outcome] ? "T" : "F"}  #{status}"
+      row[:conditions].each_with_index do |expression, index|
+        requirement = @coordinator.decision_table_requirement(rule[:conditions][index])
+        next if requirement.nil?
+
+        lines << "    #{expression} = #{requirement}"
+      end
+      lines << "    #{@coordinator.decision_table_expected_heading(row)} #{rule[:outcome] ? "true" : "false"}"
+      if rule[:coverage].to_s == "covered"
+        owners = Array(rule[:tests]).map { |id| test_label(id) }
+        owners << "unattributed" if rule[:unattributed_count].to_i.positive?
+        lines << "    Tests: #{owners.empty? ? "none recorded" : owners.uniq.join(", ")}"
+      else
+        lines << "    Tests: NOT COVERED"
+      end
+      lines << "    Reachability: #{@coordinator.decision_table_reachability(rule)}"
+      return if rule[:reachability_reason].to_s.empty?
+
+      lines << "    Reason: #{Constraints.message(rule[:reachability_reason])}"
+    end
+
     def render_alternatives(lines)
       rows = @index.alternatives
       rows = rows.select { |row| row[:missing] || row[:status].to_s != "covered" } if @missing_only && @level > 1
@@ -271,9 +341,7 @@ module Branchproof
       return id.to_s unless test
 
       label = "#{test[:name]} (#{location(test[:relative_path], test[:line])})"
-      duplicates = @index.tests.count do |row|
-        [row[:name], row[:relative_path], row[:line]] == [test[:name], test[:relative_path], test[:line]]
-      end
+      duplicates = @test_name_counts[[test[:name], test[:relative_path], test[:line]]]
       duplicates > 1 ? "#{label} [#{id}]" : label
     end
 

data/lib/branchproof/instrumenter.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "flow_instrumentation"
+require_relative "iteration_instrumentation"
+require_relative "exception_instrumentation"
+require_relative "default_instrumentation"
+require_relative "value_instrumentation"
 
 module Branchproof
   # Applies the smallest possible source edits around inventoried expressions.
@@ -8,23 +12,24 @@ module Branchproof
   # never evaluates application code or introduces a Ruby scope.
   class Instrumenter
     include FlowInstrumentation
+    include IterationInstrumentation
+    include ExceptionInstrumentation
+    prepend DefaultInstrumentation
+    prepend ValueInstrumentation
 
     RUNTIME = "::Branchproof::Runtime"
 
     def rewrite(unit:)
       bytes = unit.fetch(:original_bytes).dup.force_encoding(Encoding::BINARY)
       reasons = Array(unit[:support_reasons])
-      unless supported_unit?(unit, reasons)
-        return result(bytes, diagnostics: [diagnostic("unsupported_source", reasons.join(", "))])
-      end
+      return result(bytes, diagnostics: [diagnostic("unsupported_source", reasons.join(", "))]) unless supported?(unit)
 
       decisions = Array(unit[:decisions]).select { |decision| supported?(decision) }
+      encloses, enclosed = build_enclosures(decisions)
       edits = decisions.filter_map do |decision|
-        next if decisions.any? do |outer|
-          encloses_decision?(outer, decision)
-        end
+        next if enclosed[decision]
 
-        decision_edit(bytes, decision, decisions)
+        decision_edit(bytes, decision, encloses)
       end
       if decisions.any? && edits.empty?
         return result(bytes,
@@ -34,35 +39,65 @@ module Branchproof
 
       rewritten = apply_edits(bytes, edits)
       begin
-        RubyVM::InstructionSequence.compile(rewritten, unit[:absolute_path] || "(branchproof)",
-                                            unit[:real_path] || unit[:absolute_path] || "(branchproof)", 1)
+        iseq = RubyVM::InstructionSequence.compile(rewritten, unit[:absolute_path] || "(branchproof)",
+                                                   unit[:real_path] || unit[:absolute_path] || "(branchproof)", 1)
       rescue SyntaxError => e
-        return result(bytes, diagnostics: [diagnostic("invalid_rewrite", e.message)])
+        return result(rewritten, diagnostics: [diagnostic("invalid_rewrite", e.message)])
       end
-      result(rewritten.force_encoding(unit[:original_bytes].encoding), changed: rewritten != bytes)
+      result(rewritten.force_encoding(unit[:original_bytes].encoding), changed: edits.any?, iseq: iseq)
     end
 
     private
 
-    def supported_unit?(unit, _reasons)
-      status = unit[:support_status]
+    def supported?(record)
+      status = record[:support_status]
       status.nil? || status.to_s.casecmp("supported").zero?
     end
 
-    def supported?(decision)
-      status = decision[:support_status]
-      status.nil? || status.to_s.casecmp("supported").zero?
+    # Precompute, once, which decisions each decision encloses (and whether it is
+    # itself enclosed by any other), so rendering never re-scans the full decision
+    # list at every recursion level. Safe because `encloses_decision?` containment
+    # is transitive: if the encloses map for `decision` says it contains X, that
+    # holds true within any nested subset that already contains `decision`.
+    def build_enclosures(decisions)
+      encloses = {}.compare_by_identity
+      enclosed = {}.compare_by_identity
+      indexed = decisions.each_index.group_by { |index| decisions[index][:byte_start] }
+      active = []
+      relations = Array.new(decisions.length) { [] }
+
+      indexed.sort_by { |start, _indices| start }.each do |start, indices|
+        active.reject! do |index|
+          decision = decisions[index]
+          decision[:byte_start] + decision[:byte_length] < start
+        end
+        active.concat(indices)
+        indices.each do |inner_index|
+          inner = decisions[inner_index]
+          active.each do |outer_index|
+            outer = decisions[outer_index]
+            next unless encloses_decision?(outer, inner)
+
+            relations[outer_index] << inner_index
+          end
+        end
+      end
+
+      decisions.each_with_index do |outer, outer_index|
+        contained = relations[outer_index].sort.map { |inner_index| decisions[inner_index] }
+        encloses[outer] = contained
+        contained.each { |inner| enclosed[inner] = true }
+      end
+      [encloses, enclosed]
     end
 
-    def decision_edit(bytes, decision, all_decisions)
+    def decision_edit(bytes, decision, encloses)
       start = decision[:byte_start]
       length = decision[:byte_length]
       return nil unless valid_range?(bytes, start, length)
 
-      nested = all_decisions.select do |candidate|
-        encloses_decision?(decision, candidate)
-      end
-      expression = render_decision(bytes, decision, nested)
+      nested = encloses[decision] || []
+      expression = render_decision(bytes, decision, nested, encloses)
       {
         start: start,
         finish: start + length,
@@ -70,7 +105,9 @@ module Branchproof
       }
     end
 
-    def render_range(bytes, start, length, decision, nested)
+    def render_range(bytes, decision, nested, encloses)
+      start = decision[:byte_start]
+      length = decision[:byte_length]
       conditions = Array(decision[:conditions]).sort_by { |condition| condition[:byte_start] }
       cursor = start
       chunks = []
@@ -80,15 +117,15 @@ module Branchproof
         next unless valid_range?(bytes, cstart, clen) && cstart >= start && cstart + clen <= start + length
 
         chunks << bytes.byteslice(cursor, cstart - cursor)
-        original = render_children(bytes, cstart, clen, nested)
-        chunks << condition_wrapper(decision[:id], condition[:index], original)
+        original = render_children(bytes, cstart, clen, nested, encloses)
+        chunks << condition_wrapper(decision, condition, original)
         cursor = cstart + clen
       end
-      chunks << render_children(bytes, cursor, length - (cursor - start), nested)
+      chunks << render_children(bytes, cursor, length - (cursor - start), nested, encloses)
       chunks.join
     end
 
-    def render_children(bytes, start, length, nested)
+    def render_children(bytes, start, length, nested, encloses)
       children = nested.select do |child|
         contains?(start, length, child[:byte_start], child[:byte_length])
       end
@@ -98,8 +135,8 @@ module Branchproof
       children.sort_by! { |child| -child[:byte_start] }
       output = bytes.byteslice(start, length)
       children.each do |child|
-        descendants = nested.select { |candidate| encloses_decision?(child, candidate) }
-        child_text = render_decision(bytes, child, descendants)
+        descendants = encloses[child] || []
+        child_text = render_decision(bytes, child, descendants, encloses)
         offset = child[:byte_start] - start
         output[offset, child[:byte_length]] = child_text
       end
@@ -114,17 +151,33 @@ module Branchproof
       (outer[:kind] || "boolean") == "boolean" && inner[:kind] != "boolean" && !inner[:kind].nil?
     end
 
-    def render_decision(bytes, decision, nested)
+    def render_decision(bytes, decision, nested, encloses)
       if decision[:instrumentation]
-        render_flow(bytes, decision, nested)
+        render_flow(bytes, decision, nested, encloses)
       else
-        expression = render_range(bytes, decision[:byte_start], decision[:byte_length], decision, nested)
+        expression = render_range(bytes, decision, nested, encloses)
         frame(decision[:id], expression)
       end
     end
 
-    def condition_wrapper(decision_id, index, expression)
-      "#{RUNTIME}.condition(#{decision_id.inspect}, #{index}, (#{expression}))"
+    def condition_wrapper(decision, condition, expression)
+      return "(begin; #{expression}; end)" if nonlocal_transfer?(expression)
+
+      identifier = decision[:id].inspect
+      index = condition[:index]
+      case condition[:contextual]
+      when "implicit_regexp", "flip_flop"
+        # These operations require Ruby's conditional context: a bare regexp
+        # implicitly matches $_ and a flip-flop retains its state across calls.
+        "(if (#{expression}) then #{RUNTIME}.condition(#{identifier}, #{index}, true) " \
+        "else #{RUNTIME}.condition(#{identifier}, #{index}, false) end)"
+      else
+        "#{RUNTIME}.condition(#{identifier}, #{index}, (#{expression}))"
+      end
+    end
+
+    def nonlocal_transfer?(expression)
+      expression.lstrip.match?(/\A(?:return|break|next|redo|retry)\b/n)
     end
 
     def frame(decision_id, expression)
@@ -133,10 +186,13 @@ module Branchproof
         "#{RUNTIME}.leave(#{decision_id.inspect}); end; end)"
     end
 
+    # Mutates `bytes` in place: it is already a fresh copy made at the top of
+    # rewrite, so there is no need to copy it again before splicing edits in.
     def apply_edits(bytes, edits)
-      edits.sort_by { |edit| -edit[:start] }.each_with_object(bytes.dup) do |edit, output|
-        output[edit[:start]...edit[:finish]] = edit[:text]
+      edits.sort_by { |edit| -edit[:start] }.each do |edit|
+        bytes[edit[:start]...edit[:finish]] = edit[:text]
       end
+      bytes
     end
 
     def valid_range?(bytes, start, length)
@@ -153,8 +209,8 @@ module Branchproof
       start.is_a?(Integer) && length.is_a?(Integer) && start >= 0 && length >= 0
     end
 
-    def result(bytes, changed: false, diagnostics: [])
-      { bytes: bytes, changed: changed, diagnostics: diagnostics }.freeze
+    def result(bytes, changed: false, diagnostics: [], iseq: nil)
+      { bytes: bytes, changed: changed, diagnostics: diagnostics, iseq: iseq }.freeze
     end
 
     def diagnostic(code, message)

data/lib/branchproof/iteration_instrumentation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Keep matching and iteration in the original lexical scope.
+  module IterationInstrumentation
+    private
+
+    # rubocop:disable Metrics/MethodLength
+    def render_flow(bytes, decision, nested, encloses)
+      metadata = decision.fetch(:instrumentation)
+      case metadata[:type]
+      when "iteration"
+        render_iteration(bytes, decision, nested, encloses)
+      when "required_pattern"
+        expression = render_children(bytes, decision[:byte_start], decision[:byte_length], nested, encloses)
+        runtime = self.class::RUNTIME
+        identifier = decision[:id].inspect
+        "(begin; #{runtime}.enter(#{identifier}); begin; #{expression}; " \
+          "#{runtime}.flow_select(#{identifier}, 0); nil; rescue ::NoMatchingPatternError; " \
+          "#{runtime}.flow_select(#{identifier}, 1); raise; ensure; #{runtime}.leave(#{identifier}); end; end)"
+      else
+        super
+      end
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- nested exception callback seam
+    def render_iteration(bytes, decision, nested, encloses)
+      metadata = decision.fetch(:instrumentation)
+      identifier = decision[:id].inspect
+      runtime = self.class::RUNTIME
+      alternative_count = metadata[:lazy] ? 1 : 2
+      marker = "#{runtime}.flow_iteration_callback(#{identifier}, #{alternative_count})"
+      suffix = metadata[:empty] ? "nil; " : ""
+      callback = "; #{marker}; #{suffix}"
+      exception_child = nested.find do |child|
+        child[:instrumentation]&.fetch(:type, nil) == "exception" &&
+          child[:instrumentation].fetch(:implicit, false) &&
+          contains?(child[:byte_start], child[:byte_length], metadata[:insert_at], 0)
+      end
+      if exception_child
+        instrumentation = exception_child.fetch(:instrumentation)
+        callback_child = exception_child.merge(instrumentation: instrumentation.merge(
+          iteration_callback: { insert_at: metadata[:insert_at], text: callback }
+        ))
+        nested = nested.map { |child| child.equal?(exception_child) ? callback_child : child }
+        encloses = encloses.merge(callback_child => encloses[exception_child])
+      end
+      edits = exception_child ? [] : [{ start: metadata[:insert_at], length: 0, text: callback }]
+      if metadata[:receiver]
+        receiver = metadata.fetch(:receiver)
+        edits << flow_replacement(bytes, receiver, nested, encloses) do |expression|
+          "#{runtime}.flow_iteration_begin(#{identifier}, (#{expression}), #{alternative_count})"
+        end
+      end
+      expression = flow_fragments(bytes, decision, nested, edits, encloses)
+      if metadata[:receiver]
+        "(begin; begin; #{runtime}.flow_iteration_finish(#{identifier}, (#{expression}), 0); ensure; " \
+          "#{runtime}.flow_iteration_leave(#{identifier}); end; end)"
+      else
+        flow_frame(decision[:id], expression, default_path: 0)
+      end
+    end
+  end
+end

data/lib/branchproof/iteration_runtime.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Runtime support for callback based iteration, including lazy receivers
+  # whose callbacks execute after the constructing call has returned.
+  module IterationRuntime
+    def flow_iteration_begin(decision_id, receiver, alternative_count = 2)
+      # Case equality bypasses an application's overridden `is_a?` method.
+      # rubocop:disable-next Style/CaseEquality
+      return receiver if alternative_count == 1 || ::Enumerator::Lazy === receiver
+
+      enter(decision_id)
+      receiver
+    end
+
+    # rubocop:disable-next Metrics/MethodLength
+    def flow_iteration_callback(decision_id, alternative_count = 2)
+      frame = iteration_frame(decision_id)
+      if frame
+        return nil if frame[:finished]
+
+        iteration_select(frame, alternative_count.to_i == 1 ? 0 : 1, alternative_count)
+      else
+        enter(decision_id)
+        begin
+          if alternative_count.to_i == 1
+            flow_select(decision_id, 0)
+          else
+            flow_path(decision_id, 1)
+          end
+        ensure
+          leave(decision_id)
+        end
+      end
+      nil
+    end
+
+    def flow_iteration_finish(decision_id, value, default_path = nil)
+      frame = iteration_frame(decision_id)
+      iteration_select(frame, default_path, 2) if frame && !frame[:finished] && !default_path.nil?
+      value
+    end
+
+    def flow_iteration_leave(decision_id)
+      frame = iteration_frame(decision_id)
+      frames = Thread.current[Branchproof::Runtime::FRAME_STATE_KEY]&.fetch(:frames, nil)
+      return nil unless frame && frames&.last.equal?(frame)
+
+      leave(decision_id)
+    end
+
+    private
+
+    # `current_frame` deliberately latches a diagnostic when a helper probes
+    # while another decision is active. Iteration callbacks may be deferred or
+    # nested, so an absent matching frame is an ordinary state here.
+    def iteration_frame(decision_id)
+      frames = Thread.current[Branchproof::Runtime::FRAME_STATE_KEY]&.fetch(:frames, nil)
+      index = frames ? frames.length - 1 : -1
+      while index >= 0
+        frame = frames[index]
+        return frame if frame[:decision_id] == decision_id
+
+        index -= 1
+      end
+      nil
+    end
+
+    def iteration_select(frame, index, alternative_count)
+      frame[:observations] = if alternative_count == 1
+                               [[0, true]]
+                             else
+                               [[0, index.zero?], [1, index == 1]]
+                             end
+      frame[:outcome] = true
+      frame[:finished] = true
+    end
+  end
+end