branchproof 0.7.0 → 0.9.0

data/lib/branchproof/evidence.rb

@@ -20,14 +20,21 @@ module Branchproof
       raise ArgumentError, "run_id is required" if run_id.nil? || run_id.to_s.empty?
 
       @inventory = inventory
+      @decisions_by_id = Array(fetch_value(@inventory, :decisions)).each_with_object({}) do |raw, index|
+        decision = symbolize(raw)
+        index[decision[:id].to_s] = decision
+      end
       @limits = normalize_limits(limits)
       @run_id = run_id.to_s
       @run_ids = [@run_id]
       @vectors = {}
+      @vector_counts_by_decision = Hash.new(0)
+      @owner_associations_count = 0
       @tests = {}
       @run_payloads = {}
       @abort_counts = Hash.new(0)
       @diagnostics = []
+      @repetition_cache = {}
       @limited = false
       @attribution_complete = true
     end
@@ -49,6 +56,10 @@ module Branchproof
     end
 
     def record(execution:)
+      if (cached = cached_execution(execution))
+        return record_cached(cached)
+      end
+
       value = symbolize(execution)
       reason = validate_execution(value)
       return reject_record(reason) if reason
@@ -68,12 +79,13 @@ module Branchproof
       end
       decision_id = value[:decision_id].to_s
       vector_values = condition_values(decision_id, value[:observations])
-      if new_vector?(decision_id, vector_values,
-                     value[:outcome]) && vector_count(decision_id) >= @limits[:vectors_per_decision]
+      outcome = value[:outcome] ? true : false
+      vector_id = Branchproof::Records.id([decision_id, vector_values, outcome])
+      if new_vector?(vector_id) && vector_count(decision_id) >= @limits[:vectors_per_decision]
         @limited = true
         return status("limited", "vectors_per_decision reached")
       end
-      vector = vector_for(decision_id, vector_values, value[:outcome] ? true : false)
+      vector = vector_for(decision_id, vector_values, outcome, vector_id)
       new_owner = if value[:test_id]
                     !vector[:test_ids].include?(value[:test_id].to_s)
                   else
@@ -89,11 +101,14 @@ module Branchproof
       phase_map << value[:phase].to_s if phase_map && !phase_map.include?(value[:phase].to_s)
       vector[:unattributed_count] += 1 unless value[:test_id]
       vector[:count] += 1
+      @owner_associations_count += 1 if new_owner
       if value[:test_id] && @tests.key?(value[:test_id].to_s)
         test = @tests[value[:test_id].to_s]
         phase = value[:phase].to_s
         test[:phase_counts][phase] = test[:phase_counts].fetch(phase, 0) + 1
       end
+      cache_key = execution_cache_key(value)
+      @repetition_cache[cache_key[1]] = { key: cache_key, vector_id: vector_id }
       status("recorded", nil)
     rescue StandardError => e
       diagnose(diagnostic: { code: "record_failure", severity: "error", message: e.message })
@@ -159,6 +174,7 @@ module Branchproof
       @abort_counts.merge!(incoming.fetch(:abort_counts, {})) { |_k, a, b| a.to_i + b.to_i }
       @limited ||= !incoming.dig(:completeness, :observation)
       @attribution_complete &&= incoming.dig(:completeness, :attribution) ? true : false
+      @repetition_cache.clear
       status("merged", nil)
     rescue StandardError => e
       restore_state(backup) if backup
@@ -194,18 +210,17 @@ module Branchproof
     def validate_execution(value)
       return "execution must be a hash" unless value.is_a?(Hash)
 
-      %i[run_id execution_id decision_id test_id phase owner observations outcome status].each do |key|
+      %i[run_id decision_id test_id phase observations outcome status].each do |key|
         return "missing #{key}" unless value.key?(key)
       end
       return "run mismatch" unless value[:run_id].to_s == @run_id
-      return "invalid owner" unless value[:owner].is_a?(Hash)
       return "invalid status" unless %w[completed aborted invalid].include?(value[:status].to_s)
       return "invalid phase" unless %w[setup body teardown suite unattributed].include?(value[:phase].to_s)
       return "invalid observations" unless value[:observations].is_a?(Array) && value[:observations].all? do |pair|
         pair.is_a?(Array) && pair.length == 2 && pair[0].is_a?(Integer) && [true, false].include?(pair[1])
       end
 
-      decision = decisions.find { |d| d[:id].to_s == value[:decision_id].to_s }
+      decision = @decisions_by_id[value[:decision_id].to_s]
       return "unknown decision" unless decision
 
       dimensions = alternative_decision?(decision) ? Array(decision[:alternatives]) : Array(decision[:conditions])
@@ -224,7 +239,7 @@ module Branchproof
     def valid_trace?(decision, observations, outcome)
       return valid_alternative_trace?(decision, observations, outcome) if alternative_decision?(decision)
 
-      tree = symbolize(decision[:tree])
+      tree = decision[:tree]
       unless tree
         return observations.map(&:first) == observations.map(&:first).sort &&
                (outcome ? true : false) == evaluate_fallback(observations)
@@ -239,7 +254,6 @@ module Branchproof
     end
 
     def replay_tree(node, observations, cursor)
-      node = symbolize(node)
       type = node[:type].to_s
       if type == "atom"
         pair = observations[cursor]
@@ -280,26 +294,42 @@ module Branchproof
       values
     end
 
-    def vector_for(decision_id, values, outcome)
-      id = Branchproof::Records.id([decision_id, values, outcome])
-      @vectors[id] ||= { id: id, decision_id: decision_id, values: values.dup, outcome: outcome,
-                         test_ids: [], phases_by_test: {}, unattributed_count: 0, count: 0 }
+    def vector_for(decision_id, values, outcome, id)
+      existing = @vectors[id]
+      return existing if existing
+
+      vector = { id: id, decision_id: decision_id, values: values.dup, outcome: outcome,
+                 test_ids: [], phases_by_test: {}, unattributed_count: 0, count: 0 }
+      @vectors[id] = vector
+      @vector_counts_by_decision[decision_id] += 1
+      vector
     end
 
     def merge_vector(raw)
       vector = symbolize(raw)
-      existing = @vectors[vector[:id].to_s]
+      id = vector[:id].to_s
+      existing = @vectors[id]
       if existing
-        existing[:test_ids] |= Array(vector[:test_ids]).map(&:to_s)
+        new_test_ids = Array(vector[:test_ids]).map(&:to_s) - existing[:test_ids]
+        existing[:test_ids] |= new_test_ids
         vector.fetch(:phases_by_test, {}).each do |test, phases|
           existing[:phases_by_test][test.to_s] = (existing[:phases_by_test][test.to_s] || []) | phases
         end
+        was_unattributed = existing[:unattributed_count].positive?
         existing[:count] += vector[:count].to_i
         existing[:unattributed_count] += vector[:unattributed_count].to_i
+        @owner_associations_count += new_test_ids.length
+        @owner_associations_count += 1 if !was_unattributed && existing[:unattributed_count].positive?
       else
-        @vectors[vector[:id].to_s] = { id: vector[:id].to_s, decision_id: vector[:decision_id].to_s,
-                                       values: Array(vector[:values]).dup, outcome: !!vector[:outcome], test_ids: Array(vector[:test_ids]).map(&:to_s),
-                                       phases_by_test: vector.fetch(:phases_by_test, {}).transform_keys(&:to_s), unattributed_count: vector[:unattributed_count].to_i, count: vector[:count].to_i }
+        decision_id = vector[:decision_id].to_s
+        test_ids = Array(vector[:test_ids]).map(&:to_s)
+        unattributed_count = vector[:unattributed_count].to_i
+        @vectors[id] = { id: id, decision_id: decision_id,
+                         values: Array(vector[:values]).dup, outcome: !!vector[:outcome], test_ids: test_ids,
+                         phases_by_test: vector.fetch(:phases_by_test, {}).transform_keys(&:to_s), unattributed_count: unattributed_count, count: vector[:count].to_i }
+        @vector_counts_by_decision[decision_id] += 1
+        @owner_associations_count += test_ids.length
+        @owner_associations_count += 1 if unattributed_count.positive?
       end
     end
 
@@ -314,14 +344,14 @@ module Branchproof
     end
 
     def condition_shapes
-      decisions.to_h do |decision|
+      @decisions_by_id.transform_values do |decision|
         shape = { conditions: Array(decision[:conditions]).map { |condition| symbolize(condition) },
                   tree: symbolize(decision[:tree]) }
         if alternative_decision?(decision)
           shape[:kind] = decision[:kind].to_s
           shape[:alternatives] = Array(decision[:alternatives]).map { |alternative| symbolize(alternative) }
         end
-        [decision[:id].to_s, shape]
+        shape
       end
     end
 
@@ -348,7 +378,7 @@ module Branchproof
         vector = symbolize(raw)
         return "invalid vector" unless vector[:id] && vector[:decision_id] && vector[:values].is_a?(Array)
 
-        decision = decisions.find { |item| item[:id].to_s == vector[:decision_id].to_s }
+        decision = @decisions_by_id[vector[:decision_id].to_s]
         return "unknown decision" unless decision
 
         expected_values = decision_dimension_count(decision)
@@ -396,7 +426,7 @@ module Branchproof
     end
 
     def decision_dimension_count(decision_or_id)
-      decision = decision_or_id.is_a?(Hash) ? decision_or_id : decisions.find { |item| item[:id].to_s == decision_or_id.to_s }
+      decision = decision_or_id.is_a?(Hash) ? decision_or_id : @decisions_by_id[decision_or_id.to_s]
       return 0 unless decision
 
       alternative_decision?(decision) ? Array(decision[:alternatives]).length : Array(decision[:conditions]).length
@@ -420,16 +450,11 @@ module Branchproof
       end
     end
 
-    def decisions = Array(fetch_value(@inventory, :decisions)).map { symbolize(_1) }
-    def decision_conditions(id) = (decisions.find { |d| d[:id].to_s == id.to_s } || {}).fetch(:conditions, [])
-    def vector_count(id) = @vectors.values.count { |v| v[:decision_id] == id.to_s }
-    def new_vector?(id, values, outcome) = !@vectors.key?(Branchproof::Records.id([id, values, outcome]))
+    def decision_conditions(id) = (@decisions_by_id[id.to_s] || {}).fetch(:conditions, [])
+    def vector_count(id) = @vector_counts_by_decision[id.to_s]
+    def new_vector?(id) = !@vectors.key?(id)
 
-    def owner_associations
-      @vectors.values.sum do |v|
-        v[:test_ids].length + (v[:unattributed_count].positive? ? 1 : 0)
-      end
-    end
+    def owner_associations = @owner_associations_count
 
     def incoming_owner_associations(incoming)
       owners = @vectors.each_with_object({}) do |(_id, vector), result|
@@ -500,7 +525,9 @@ module Branchproof
     def capture_state
       { vectors: deep_dup(@vectors), tests: deep_dup(@tests), run_ids: @run_ids.dup,
         run_payloads: @run_payloads.dup, diagnostics: deep_dup(@diagnostics),
-        abort_counts: @abort_counts.dup, limited: @limited, attribution_complete: @attribution_complete }
+        abort_counts: @abort_counts.dup, limited: @limited, attribution_complete: @attribution_complete,
+        vector_counts_by_decision: @vector_counts_by_decision.dup, owner_associations_count: @owner_associations_count,
+        repetition_cache: deep_dup(@repetition_cache) }
     end
 
     def restore_state(state)
@@ -510,10 +537,85 @@ module Branchproof
       @run_payloads = state[:run_payloads]
       @diagnostics = state[:diagnostics]
       @abort_counts = state[:abort_counts]
+      @vector_counts_by_decision = state[:vector_counts_by_decision]
+      @owner_associations_count = state[:owner_associations_count]
+      @repetition_cache = state[:repetition_cache]
       @limited = state[:limited]
       @attribution_complete = state[:attribution_complete]
     end
 
+    def cached_execution(execution)
+      return nil unless execution.is_a?(Hash)
+
+      key = raw_execution_cache_key(execution)
+      return nil unless key
+
+      entry = @repetition_cache[key[1]]
+      return nil unless entry && entry[:key] == key
+
+      vector = @vectors[entry[:vector_id]]
+      return nil unless vector
+
+      [key, vector, raw_execution_attribution(execution)]
+    end
+
+    def record_cached(cached)
+      _key, vector, value = cached
+      vector[:count] += 1
+      if value[:test_id] && @tests.key?(value[:test_id].to_s)
+        test = @tests[value[:test_id].to_s]
+        phase = value[:phase].to_s
+        test[:phase_counts][phase] = test[:phase_counts].fetch(phase, 0) + 1
+      end
+      vector[:unattributed_count] += 1 unless value[:test_id]
+      status("recorded", nil)
+    end
+
+    def raw_execution_cache_key(execution)
+      required = %i[run_id decision_id test_id phase observations outcome status]
+      return nil unless required.all? { |key| execution.key?(key) || execution.key?(key.to_s) }
+
+      status = raw_value(execution, :status)
+      outcome = raw_value(execution, :outcome)
+      return nil unless status.to_s == "completed" && [true, false].include?(outcome)
+
+      observations = raw_value(execution, :observations)
+      return nil unless observations.is_a?(Array)
+
+      test_id = raw_value(execution, :test_id)
+      [raw_value(execution, :run_id).to_s, raw_value(execution, :decision_id).to_s,
+       test_id_marker(test_id), test_id&.to_s, raw_value(execution, :phase).to_s,
+       observations, outcome, status.to_s]
+    end
+
+    def execution_cache_key(value)
+      key = [copy_string(value[:run_id]), copy_string(value[:decision_id]), test_id_marker(value[:test_id]),
+             copy_string(value[:test_id]),
+             copy_string(value[:phase]), deep_dup(value[:observations]), value[:outcome], copy_string(value[:status])]
+      deep_freeze(key)
+    end
+
+    def raw_execution_attribution(execution)
+      { test_id: raw_value(execution, :test_id), phase: raw_value(execution, :phase) }
+    end
+
+    def copy_string(value)
+      value.nil? ? nil : value.to_s.dup
+    end
+
+    def test_id_marker(value)
+      return :nil if value.nil?
+      return :false_test_id if value == false
+
+      :present
+    end
+
+    def raw_value(hash, key)
+      return hash[key] if hash.key?(key)
+
+      hash[key.to_s]
+    end
+
     def deep_freeze(value)
       case value
       when Hash then value.each do |key, item|

data/lib/branchproof/exception_instrumentation.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Style/ConditionalAssignment
+
+require_relative "flow_instrumentation"
+
+module Branchproof
+  # Textual edits for native rescue control flow.  The edits only add calls at
+  # Ruby's own protected-region and handler boundaries; exception matching,
+  # `$!`, retry, ensure ordering, and nonlocal transfers remain Ruby-owned.
+  module ExceptionInstrumentation
+    private
+
+    def render_flow(bytes, decision, nested, encloses)
+      metadata = decision.fetch(:instrumentation)
+      return super unless %w[exception rescue_modifier].include?(metadata[:type])
+
+      if metadata[:type] == "exception"
+        render_exception_flow(bytes, decision, nested, encloses)
+      else
+        render_rescue_modifier_flow(bytes, decision, nested, encloses)
+      end
+    end
+
+    def render_exception_flow(bytes, decision, nested, encloses)
+      identifier = decision[:id].inspect
+      runtime = self.class::RUNTIME
+      metadata = decision.fetch(:instrumentation)
+      replacements = []
+      if metadata[:normal_insert_at] && !metadata[:normal_empty]
+        replacements << { start: metadata.fetch(:normal_insert_at), length: 0,
+                          text: "; #{runtime}.exception_path(#{identifier}, 0); " }
+      elsif metadata[:normal_transfer]
+        transfer = metadata.fetch(:normal_transfer)
+        if transfer[:arguments]
+          replacements << flow_replacement(bytes, transfer.fetch(:arguments), nested, encloses) do |arguments|
+            value = transfer[:argument_mode] == :array ? "[#{arguments}]" : "(#{arguments})"
+            "#{runtime}.exception_value(#{identifier}, #{value}, 0)"
+          end
+        else
+          replacements << { start: transfer.fetch(:insert_at), length: 0,
+                            text: "#{runtime}.exception_path(#{identifier}, 0); " }
+        end
+      elsif metadata[:normal_body] && metadata[:normal_body][:byte_length].positive?
+        replacements << flow_replacement(bytes, metadata.fetch(:normal_body), nested, encloses) do |body|
+          "#{runtime}.exception_value(#{identifier}, (begin; #{body}; end), 0)"
+        end
+      end
+      metadata.fetch(:clauses).each do |clause|
+        replacements << { start: clause.fetch(:insert_at), length: 0,
+                          text: "; #{runtime}.exception_path(#{identifier}, #{clause.fetch(:index)}); " }
+      end
+      if metadata[:implicit]
+        entry = "begin; #{runtime}.exception_enter(#{identifier}, #{metadata.fetch(:unhandled_index)}); begin; "
+        entry += "#{runtime}.exception_path(#{identifier}, 0); " if metadata[:normal_empty]
+        entry += metadata[:iteration_callback].fetch(:text) if metadata[:iteration_callback]
+        exit = "; end; rescue ::Exception; #{runtime}.exception_unhandled(#{identifier}); raise; ensure; " \
+               "#{runtime}.exception_leave(#{identifier}); end; "
+        replacements << { start: metadata.fetch(:entry_insert_at), length: 0, text: entry }
+        replacements << { start: metadata.fetch(:exit_insert_at), length: 0, text: exit }
+        flow_fragments(bytes, decision, nested, replacements, encloses)
+      else
+        expression = flow_fragments(bytes, decision, nested, replacements, encloses)
+        exception_frame(decision[:id], expression, metadata.fetch(:unhandled_index))
+      end
+    end
+
+    def render_rescue_modifier_flow(bytes, decision, nested, encloses)
+      identifier = decision[:id].inspect
+      runtime = self.class::RUNTIME
+      metadata = decision.fetch(:instrumentation)
+      lhs = metadata.fetch(:expression)
+      rhs = metadata.fetch(:rescue_expression)
+      replacements = [
+        flow_replacement(bytes, lhs, nested, encloses) do |expression|
+          "#{runtime}.exception_value(#{identifier}, (#{expression}), 0)"
+        end,
+        flow_replacement(bytes, rhs, nested, encloses) do |expression|
+          "(begin; #{runtime}.exception_path(#{identifier}, 1); (#{expression}); end)"
+        end
+      ]
+      exception_frame(decision[:id], flow_fragments(bytes, decision, nested, replacements, encloses),
+                      metadata.fetch(:unhandled_index))
+    end
+
+    def exception_frame(decision_id, expression, unhandled_index)
+      runtime = self.class::RUNTIME
+      "(begin; #{runtime}.exception_enter(#{decision_id.inspect}, #{unhandled_index}); begin; " \
+        "#{expression}; " \
+        "rescue ::Exception; #{runtime}.exception_unhandled(#{decision_id.inspect}); raise; ensure; " \
+        "#{runtime}.exception_leave(#{decision_id.inspect}); end; end)"
+    end
+  end
+end
+
+# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Style/ConditionalAssignment

data/lib/branchproof/exception_runtime.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Record native clause selection and escaping exceptions. Generated wrappers
+  # re-raise the same exception; nonlocal transfers remain aborted observations.
+  module ExceptionRuntime
+    def exception_enter(decision_id, unhandled_index)
+      enter(decision_id)
+      frame = current_frame(decision_id)
+      frame[:exception_unhandled_index] = unhandled_index if frame
+      nil
+    end
+
+    def exception_path(decision_id, index)
+      frame = current_frame(decision_id)
+      flow_select(decision_id, index) if frame && !frame[:finished]
+      nil
+    end
+
+    def exception_value(decision_id, value, index)
+      exception_path(decision_id, index)
+      value
+    end
+
+    def exception_finish(decision_id, value)
+      frame = current_frame(decision_id)
+      exception_path(decision_id, 0) if frame && !frame[:finished]
+      value
+    end
+
+    def exception_unhandled(decision_id)
+      frame = current_frame(decision_id)
+      exception_path(decision_id, frame[:exception_unhandled_index]) if frame && !frame[:finished]
+      nil
+    end
+
+    def exception_leave(decision_id)
+      leave(decision_id)
+    end
+  end
+end

data/lib/branchproof/exception_syntax.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/ModuleLength
+
+require "prism"
+
+module Branchproof
+  # Replaces unsupported standalone rescue-clause records with decisions for
+  # Ruby's enclosing protected region.  Ruby chooses a rescue clause as part
+  # of executing BeginNode; a RescueNode by itself is not executable syntax.
+  module ExceptionSyntax
+    private
+
+    def flow_decision_node?(node)
+      return true if exception_region_node?(node)
+      return false if node.is_a?(Prism::RescueNode)
+
+      super
+    end
+
+    def flow_details(node, bytes, encoding)
+      return exception_region_details(node, bytes, encoding) if exception_region_node?(node)
+
+      super
+    end
+
+    def exception_region_node?(node)
+      (node.is_a?(Prism::BeginNode) && (node.rescue_clause || node.ensure_clause)) ||
+        node.is_a?(Prism::RescueModifierNode)
+    end
+
+    def exception_region_details(node, bytes, encoding)
+      return rescue_modifier_details(node, bytes, encoding) if node.is_a?(Prism::RescueModifierNode)
+
+      clauses = []
+      clause = node.rescue_clause
+      while clause
+        clauses << clause
+        clause = clause.child_nodes.find { |child| child.is_a?(Prism::RescueNode) }
+      end
+
+      alternatives = [{ expression: "normal", byte_start: node.location.start_offset,
+                        byte_length: node.location.length }]
+      clauses.each do |clause_node|
+        alternatives << { expression: rescue_label(clause_node, bytes, encoding),
+                          byte_start: clause_node.location.start_offset,
+                          byte_length: clause_node.location.length }
+      end
+      alternatives << { expression: "unhandled", byte_start: node.location.start_offset,
+                        byte_length: node.location.length }
+
+      instrumentation = {
+        type: "exception",
+        range: byte_range(node.location),
+        normal_insert_at: exception_normal_insert_at(node),
+        normal_body: node.statements && byte_range(node.statements.location),
+        normal_transfer: exception_transfer_metadata(node.statements),
+        implicit: node.begin_keyword_loc.nil?,
+        normal_empty: node.begin_keyword_loc.nil? && exception_body_empty?(node),
+        entry_insert_at: node.begin_keyword_loc.nil? && exception_entry_insert_at(node),
+        exit_insert_at: node.begin_keyword_loc.nil? && node.end_keyword_loc&.start_offset,
+        clauses: clauses.each_with_index.map do |clause_node, index|
+          { index: index + 1, insert_at: exception_clause_insert_at(clause_node, node) }
+        end,
+        unhandled_index: alternatives.length - 1
+      }
+      reasons = unsupported_reasons(node, bytes)
+      ["exception", "rescue", alternatives, instrumentation, reasons]
+    end
+
+    def rescue_modifier_details(node, bytes, _encoding)
+      lhs = node.expression
+      rhs = node.rescue_expression
+      alternatives = [
+        { expression: "normal", byte_start: lhs.location.start_offset, byte_length: lhs.location.length },
+        { expression: "rescue", byte_start: rhs.location.start_offset, byte_length: rhs.location.length },
+        { expression: "unhandled", byte_start: node.location.start_offset, byte_length: node.location.length }
+      ]
+      instrumentation = {
+        type: "rescue_modifier",
+        range: byte_range(node.location),
+        expression: byte_range(lhs.location),
+        rescue_expression: byte_range(rhs.location),
+        normal_index: 0,
+        rescue_index: 1,
+        unhandled_index: 2
+      }
+      ["exception", "rescue", alternatives, instrumentation, unsupported_reasons(node, bytes)]
+    end
+
+    def rescue_label(clause, bytes, encoding)
+      exceptions = Array(clause.exceptions)
+      return "rescue" if exceptions.empty?
+
+      names = exceptions.map do |exception|
+        text_value(bytes.byteslice(exception.location.start_offset, exception.location.length), encoding)
+      end
+      "rescue #{names.join(", ")}"
+    end
+
+    def exception_clause_insert_at(clause, node)
+      return clause.statements.location.start_offset unless statements_empty?(clause.statements)
+
+      next_clause = clause.child_nodes.find { |child| child.is_a?(Prism::RescueNode) }
+      return next_clause.keyword_loc.start_offset if next_clause
+      return node.else_clause.else_keyword_loc.start_offset if node.else_clause
+      return node.ensure_clause.ensure_keyword_loc.start_offset if node.ensure_clause
+
+      node.end_keyword_loc.start_offset
+    end
+
+    def exception_else_insert_at(node)
+      clause = node.else_clause
+      return clause.statements.location.start_offset unless statements_empty?(clause.statements)
+
+      node.ensure_clause&.ensure_keyword_loc&.start_offset || node.end_keyword_loc.start_offset
+    end
+
+    def exception_transfer_metadata(statements)
+      transfer = statements && Array(statements.body).last
+      return nil unless transfer_node?(transfer)
+
+      arguments = transfer.respond_to?(:arguments) ? transfer.arguments : nil
+      argument_nodes = arguments && Array(arguments.arguments)
+      scalar_argument = argument_nodes&.length == 1 && !argument_nodes.first.is_a?(Prism::SplatNode)
+      argument_mode = if scalar_argument
+                        :scalar
+                      elsif argument_nodes&.any?
+                        :array
+                      end
+      { insert_at: transfer.location.start_offset,
+        arguments: argument_mode ? byte_range(arguments.location) : nil,
+        argument_mode: argument_mode }
+    end
+
+    def transfer_node?(node)
+      [Prism::ReturnNode, Prism::BreakNode, Prism::NextNode, Prism::RedoNode].any? { |klass| node.is_a?(klass) }
+    end
+
+    def exception_body_empty?(node)
+      node.statements.nil? || statements_empty?(node.statements)
+    end
+
+    def exception_normal_insert_at(node)
+      return exception_else_insert_at(node) if node.else_clause
+      return nil unless exception_body_empty?(node)
+
+      node.rescue_clause&.keyword_loc&.start_offset || node.ensure_clause&.ensure_keyword_loc&.start_offset
+    end
+
+    def exception_entry_insert_at(node)
+      node.statements&.location&.start_offset || exception_normal_insert_at(node) || node.end_keyword_loc.start_offset
+    end
+  end
+end
+
+# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/ModuleLength

data/lib/branchproof/extended_alternative_runtime.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Runtime hooks for decisions whose native evaluation has a third path.
+  # Runtime includes this module explicitly; it is kept separate so the
+  # ordinary two-path helpers remain unchanged.
+  module ExtendedAlternativeRuntime
+    def flow_assignment_receiver(decision_id, receiver)
+      flow_select(decision_id, 0) if nil.equal?(receiver)
+      receiver
+    end
+
+    def flow_assignment_path(decision_id, index)
+      flow_select(decision_id, index)
+    end
+
+    def flow_assignment_finish(decision_id, value, default_path = nil)
+      frame = current_frame(decision_id)
+      flow_select(decision_id, default_path) if frame && !frame[:finished] && !default_path.nil?
+      value
+    end
+  end
+end