branchproof 0.2.0

data/lib/branchproof/evidence.rb

@@ -0,0 +1,484 @@
+# frozen_string_literal: true
+
+# rubocop:disable Layout/LineLength
+require "digest"
+require "json"
+require_relative "version" unless defined?(Branchproof::VERSION)
+require_relative "records" unless defined?(Branchproof::Records)
+require_relative "limits" unless defined?(Branchproof::Limits)
+module Branchproof
+  # Validates, groups, and merges adapter-neutral execution evidence.
+  # Stores validated observations and merges compatible worker snapshots.
+  class Evidence
+    SCHEMA_VERSION = "1.0"
+    CRITERION_VERSION = "masking_occurrence_v1"
+    TOOL_VERSION = Branchproof::VERSION
+    attr_reader :inventory, :run_id
+
+    def initialize(inventory:, limits:, run_id:)
+      raise ArgumentError, "inventory is required" if inventory.nil?
+      raise ArgumentError, "run_id is required" if run_id.nil? || run_id.to_s.empty?
+
+      @inventory = inventory
+      @limits = normalize_limits(limits)
+      @run_id = run_id.to_s
+      @run_ids = [@run_id]
+      @vectors = {}
+      @tests = {}
+      @run_payloads = {}
+      @abort_counts = Hash.new(0)
+      @diagnostics = []
+      @limited = false
+      @attribution_complete = true
+    end
+
+    def register_test(test:)
+      value = symbolize(test)
+      id = (value[:id] || test_id(value)).to_s
+      if !@tests.key?(id) && @tests.length >= @limits[:tests_per_run]
+        @attribution_complete = false
+        @limited = true
+        return status("limited", "tests_per_run reached")
+      end
+      current = @tests[id] || { id: id, adapter: "unknown", name: id, source: nil, class_name: nil,
+                                method_name: nil, status: "unknown", phase_counts: {} }
+      merged = current.merge(value).merge(id: id)
+      merged[:phase_counts] = (current[:phase_counts] || {}).merge(value[:phase_counts] || {})
+      @tests[id] = deep_dup(merged)
+      status("registered", nil)
+    end
+
+    def record(execution:)
+      value = symbolize(execution)
+      reason = validate_execution(value)
+      return reject_record(reason) if reason
+
+      if value[:status].to_s == "invalid"
+        diagnose(diagnostic: { code: "invalid_execution", severity: "error", message: "invalid execution trace",
+                               decision_id: value[:decision_id] })
+        return reject_record("invalid execution")
+      end
+      if value[:status].to_s == "completed" && ![true, false].include?(value[:outcome])
+        return reject_record("completed outcome must be boolean")
+      end
+
+      if value[:status].to_s != "completed"
+        @abort_counts[value[:decision_id].to_s] += 1
+        return status("recorded", nil)
+      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]
+        @limited = true
+        return status("limited", "vectors_per_decision reached")
+      end
+      vector = vector_for(decision_id, vector_values, value[:outcome] ? true : false)
+      new_owner = if value[:test_id]
+                    !vector[:test_ids].include?(value[:test_id].to_s)
+                  else
+                    vector[:unattributed_count].zero?
+                  end
+      if new_owner && owner_associations >= @limits[:owner_associations_per_run]
+        @attribution_complete = false
+        @limited = true
+        return status("limited", "owner_associations_per_run reached")
+      end
+      vector[:test_ids] << value[:test_id].to_s if value[:test_id] && !vector[:test_ids].include?(value[:test_id].to_s)
+      phase_map = (vector[:phases_by_test][value[:test_id].to_s] ||= []) if value[:test_id]
+      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
+      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
+      status("recorded", nil)
+    rescue StandardError => e
+      diagnose(diagnostic: { code: "record_failure", severity: "error", message: e.message })
+      status("rejected", e.message)
+    end
+
+    def diagnose(diagnostic:)
+      @diagnostics << deep_freeze(symbolize(diagnostic))
+      nil
+    end
+
+    def snapshot
+      deep_freeze(deep_dup({ schema_version: SCHEMA_VERSION, tool_version: TOOL_VERSION,
+                             criterion_version: CRITERION_VERSION,
+                             runtime: RUBY_DESCRIPTION, run_ids: @run_ids.dup, inventory_digest: inventory_digest,
+                             source_digests: source_digests, condition_shapes: condition_shapes,
+                             tests: @tests.values, vectors: @vectors.values,
+                             abort_counts: @abort_counts.dup, diagnostics: @diagnostics.map(&:dup),
+                             completeness: { observation: !@limited, attribution: @attribution_complete,
+                                             analysis: true } }))
+    end
+
+    def merge(snapshot:)
+      backup = nil
+      incoming = symbolize(snapshot)
+      shape_error = validate_snapshot_shape(incoming)
+      return status("rejected", shape_error) if shape_error
+
+      reason = merge_error(incoming)
+      return status("rejected", reason) if reason
+
+      incoming_runs = Array(incoming[:run_ids]).map(&:to_s)
+      return status("rejected", "run_ids must be non-empty") if incoming_runs.empty? || incoming_runs.any?(&:empty?)
+
+      reason = validate_snapshot_vectors(incoming)
+      return status("rejected", reason) if reason
+
+      payload = canonical(incoming)
+      existing = incoming_runs.select { |id| @run_payloads.key?(id) }
+      if existing.any? && existing.any? { |id| @run_payloads[id] != Branchproof::Records.id(payload) }
+        return status("rejected", "ambiguous overlapping run IDs")
+      end
+      return status("merged", nil) if existing.length == incoming_runs.length
+      return status("rejected", "ambiguous overlapping run IDs") if existing.any?
+
+      if incoming_owner_associations(incoming) > @limits[:owner_associations_per_run]
+        @limited = true
+        @attribution_complete = false
+        return status("limited", "owner_associations_per_run reached")
+      end
+      backup = capture_state
+      incoming_runs.each do |id|
+        next if @run_payloads.key?(id)
+
+        # All validation is complete before this first mutation, so a malformed
+        # vector cannot leave a half-merged worker snapshot behind.
+        @run_payloads[id] = Branchproof::Records.id(payload)
+      end
+      @run_ids |= incoming_runs
+      incoming.fetch(:tests, []).each { register_test(test: _1) }
+      incoming.fetch(:vectors, []).each { merge_vector(_1) }
+      @diagnostics.concat(incoming.fetch(:diagnostics, []))
+      @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
+      status("merged", nil)
+    rescue StandardError => e
+      restore_state(backup) if backup
+      status("rejected", e.message)
+    end
+
+    private
+
+    def validate_snapshot_shape(incoming)
+      return "snapshot must be a hash" unless incoming.is_a?(Hash)
+
+      required = %i[schema_version tool_version criterion_version runtime run_ids inventory_digest source_digests
+                    condition_shapes tests vectors abort_counts diagnostics completeness]
+      missing = required.reject { |key| incoming.key?(key) }
+      return "missing snapshot field: #{missing.first}" unless missing.empty?
+
+      valid_run_ids = incoming[:run_ids].is_a?(Array) && incoming[:run_ids].all?(String)
+      return "invalid run_ids" unless valid_run_ids
+      return "invalid source_digests" unless incoming[:source_digests].is_a?(Hash)
+      return "invalid condition_shapes" unless incoming[:condition_shapes].is_a?(Hash)
+      return "invalid diagnostics" unless incoming[:diagnostics].is_a?(Array)
+
+      completeness = incoming[:completeness]
+      valid_completeness = completeness.is_a?(Hash)
+      valid_completeness &&= %i[observation attribution analysis].all? do |key|
+        [true, false].include?(completeness[key])
+      end
+      return "invalid completeness" unless valid_completeness
+
+      nil
+    end
+
+    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|
+        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 }
+      return "unknown decision" unless decision
+
+      conditions = Array(decision[:conditions])
+      return "condition count exceeds limit" if conditions.length > @limits[:conditions_per_decision]
+      return "invalid condition index" unless value[:observations].map(&:first).uniq == value[:observations].map(&:first) && value[:observations].all? do |index, _|
+        conditions.any? do |c|
+          c[:index].to_i == index
+        end
+      end
+      return "invalid trace" unless value[:status].to_s != "completed" || valid_trace?(decision, value[:observations],
+                                                                                       value[:outcome])
+
+      nil
+    end
+
+    def valid_trace?(decision, observations, outcome)
+      tree = symbolize(decision[:tree])
+      unless tree
+        return observations.map(&:first) == observations.map(&:first).sort &&
+               (outcome ? true : false) == evaluate_fallback(observations)
+      end
+
+      cursor = 0
+      result = replay_tree(tree, observations, cursor)
+      return false unless result
+
+      value, consumed = result
+      consumed == observations.length && value == (outcome ? true : false)
+    end
+
+    def replay_tree(node, observations, cursor)
+      node = symbolize(node)
+      type = node[:type].to_s
+      if type == "atom"
+        pair = observations[cursor]
+        return nil unless pair && pair[0].to_i == node[:index].to_i
+
+        return [pair[1], cursor + 1]
+      end
+      left = replay_tree(node.fetch(:left), observations, cursor)
+      return nil unless left
+
+      left_value, next_cursor = left
+      return [left_value, next_cursor] if (type == "and" && !left_value) || (type == "or" && left_value)
+
+      right = replay_tree(node.fetch(:right), observations, next_cursor)
+      return nil unless right
+
+      right_value, right_cursor = right
+      [type == "and" ? (left_value && right_value) : (left_value || right_value), right_cursor]
+    rescue KeyError
+      nil
+    end
+
+    def evaluate_fallback(observations)
+      observations.last&.last
+    end
+
+    def condition_values(decision_id, observations)
+      count = decision_conditions(decision_id).length
+      values = Array.new(count)
+      observations.each { |index, value| values[index] = value }
+      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 }
+    end
+
+    def merge_vector(raw)
+      vector = symbolize(raw)
+      existing = @vectors[vector[:id].to_s]
+      if existing
+        existing[:test_ids] |= Array(vector[:test_ids]).map(&:to_s)
+        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
+        existing[:count] += vector[:count].to_i
+        existing[:unattributed_count] += vector[:unattributed_count].to_i
+      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 }
+      end
+    end
+
+    def merge_error(incoming)
+      return "unsupported schema" unless incoming[:schema_version].to_s == SCHEMA_VERSION
+      return "criterion mismatch" unless incoming[:criterion_version].to_s == CRITERION_VERSION
+      return "inventory mismatch" unless incoming[:inventory_digest].to_s == inventory_digest
+      return "source mismatch" unless normalize_mapping(incoming[:source_digests]) == normalize_mapping(source_digests)
+      return "condition shape mismatch" unless canonical(incoming[:condition_shapes]) == canonical(condition_shapes)
+
+      nil
+    end
+
+    def condition_shapes
+      decisions.to_h do |decision|
+        [decision[:id].to_s, { conditions: Array(decision[:conditions]).map do |condition|
+          symbolize(condition)
+        end, tree: symbolize(decision[:tree]) }]
+      end
+    end
+
+    def validate_snapshot_vectors(incoming)
+      vectors = incoming.fetch(:vectors, [])
+      return "vectors must be an array" unless vectors.is_a?(Array)
+
+      tests = incoming.fetch(:tests, [])
+      return "tests must be an array" unless tests.is_a?(Array)
+      return "tests_per_run reached" if (@tests.keys | tests.filter_map do |item|
+        symbolize(item)[:id]
+      end).length > @limits[:tests_per_run]
+      return "invalid test record" unless tests.all? do |raw|
+        test = symbolize(raw)
+        test[:id] && test[:adapter] && test[:name] && test[:phase_counts].is_a?(Hash) &&
+        test[:phase_counts].all? do |phase, count|
+          %w[setup body teardown suite unattributed].include?(phase.to_s) && count.is_a?(Integer) && count >= 0
+        end
+      end
+
+      counts = Hash.new(0)
+      seen_ids = {}
+      vectors.each do |raw|
+        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 }
+        return "unknown decision" unless decision
+        return "invalid vector shape" unless vector[:values].length == Array(decision[:conditions]).length &&
+                                             vector[:values].all? { |item| item.nil? || item == true || item == false }
+
+        expected = Branchproof::Records.id([vector[:decision_id].to_s, vector[:values], vector[:outcome] ? true : false])
+        return "invalid vector id" unless vector[:id].to_s == expected
+        return "invalid vector outcome" unless [true, false].include?(vector[:outcome])
+        return "invalid vector count" unless vector[:count].is_a?(Integer) && vector[:count].positive?
+        unless vector[:unattributed_count].is_a?(Integer) && vector[:unattributed_count] >= 0 && vector[:unattributed_count] <= vector[:count]
+          return "invalid unattributed count"
+        end
+        unless vector[:test_ids].is_a?(Array) && vector[:test_ids].uniq.length == vector[:test_ids].length && vector[:phases_by_test].is_a?(Hash)
+          return "invalid vector provenance"
+        end
+        return "invalid vector provenance" unless vector[:phases_by_test].all? do |test, phases|
+          test && phases.is_a?(Array) && phases.all? do |phase|
+            %w[setup body teardown suite unattributed].include?(phase.to_s)
+          end
+        end
+        return "invalid vector trace" unless valid_trace?(decision, vector[:values].each_with_index.filter_map do |item, index|
+          [index, item] if [true, false].include?(item)
+        end, vector[:outcome])
+        return "duplicate vector id" if seen_ids.key?(vector[:id].to_s)
+
+        seen_ids[vector[:id].to_s] = true
+        counts[vector[:decision_id].to_s] += 1 unless @vectors.key?(vector[:id].to_s)
+      end
+      return "vectors_per_decision reached" if counts.any? do |id, count|
+        vector_count(id) + count > @limits[:vectors_per_decision]
+      end
+
+      abort_counts = incoming.fetch(:abort_counts, {})
+      return "invalid abort counts" unless abort_counts.is_a?(Hash) && abort_counts.all? do |_id, count|
+        count.is_a?(Integer) && count >= 0
+      end
+
+      nil
+    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 owner_associations
+      @vectors.values.sum do |v|
+        v[:test_ids].length + (v[:unattributed_count].positive? ? 1 : 0)
+      end
+    end
+
+    def incoming_owner_associations(incoming)
+      owners = @vectors.each_with_object({}) do |(_id, vector), result|
+        vector[:test_ids].each { |test_id| result[[vector[:id], test_id]] = true }
+        result[[vector[:id], :unattributed]] = true if vector[:unattributed_count].positive?
+      end
+      incoming.fetch(:vectors, []).each do |raw|
+        vector = symbolize(raw)
+        vector.fetch(:test_ids, []).each { |test_id| owners[[vector[:id], test_id.to_s]] = true }
+        owners[[vector[:id], :unattributed]] = true if vector.fetch(:unattributed_count, 0).to_i.positive?
+      end
+      owners.length
+    end
+
+    def inventory_digest = Branchproof::Records.id({ sources: source_digests, condition_shapes: condition_shapes })
+
+    def source_digests
+      explicit = fetch_value(@inventory, :source_digests)
+      return normalize_mapping(explicit) unless explicit.nil? || explicit.empty?
+
+      units = Array(fetch_value(@inventory, :source_units))
+      units.each_with_object({}) do |unit, result|
+        item = symbolize(unit)
+        key = item[:relative_path] || item[:source_id] || item[:absolute_path]
+        result[key.to_s] = item[:digest].to_s if key && item[:digest]
+      end
+    end
+
+    def fetch_value(object, key) = object.respond_to?(key) ? object.public_send(key) : object[key] || object[key.to_s]
+    def status(name, reason) = { status: name.to_s, reason: reason, diagnostics: @diagnostics.map(&:dup) }
+
+    def reject_record(reason)
+      @limited = true
+      diagnose(diagnostic: { code: "invalid_execution", severity: "error", message: reason.to_s })
+      status("rejected", reason.to_s)
+    end
+
+    def test_id(value) = Branchproof::Records.id(value)
+
+    def normalize_limits(value)
+      return Branchproof::Limits.default if value.nil? || value == {}
+      return Branchproof::Limits.normalize(value.to_h) if value.respond_to?(:to_h)
+
+      raise ArgumentError, "limits must be a Hash"
+    end
+
+    def symbolize(value)
+      return value.map { symbolize(_1) } if value.is_a?(Array)
+      return value.transform_keys(&:to_sym).transform_values { symbolize(_1) } if value.is_a?(Hash)
+
+      value
+    end
+
+    def canonical(value) = Branchproof::Records.canonical(value)
+
+    def normalize_mapping(value)
+      (value || {}).each_with_object({}) { |(key, item), result| result[key.to_s] = item.to_s }
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, item), copy| copy[deep_dup(key)] = deep_dup(item) }
+      when Array then value.map { deep_dup(_1) }
+      else value
+      end
+    end
+
+    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 }
+    end
+
+    def restore_state(state)
+      @vectors = state[:vectors]
+      @tests = state[:tests]
+      @run_ids = state[:run_ids]
+      @run_payloads = state[:run_payloads]
+      @diagnostics = state[:diagnostics]
+      @abort_counts = state[:abort_counts]
+      @limited = state[:limited]
+      @attribution_complete = state[:attribution_complete]
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each do |key, item|
+        deep_freeze(key)
+        deep_freeze(item)
+      end
+      when Array then value.each { deep_freeze(_1) }
+      end
+      value.freeze
+    end
+  end
+end
+# rubocop:enable Layout/LineLength

data/lib/branchproof/instrumenter.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Applies the smallest possible source edits around inventoried expressions.
+  # The edits are deliberately textual: Prism owns the ranges, while this class
+  # never evaluates application code or introduces a Ruby scope.
+  class Instrumenter
+    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
+
+      decisions = Array(unit[:decisions]).select { |decision| supported?(decision) }
+      edits = decisions.filter_map do |decision|
+        next if decisions.any? do |outer|
+          outer != decision && contains?(outer[:byte_start], outer[:byte_length], decision[:byte_start],
+                                         decision[:byte_length])
+        end
+
+        decision_edit(bytes, decision, decisions)
+      end
+      if decisions.any? && edits.empty?
+        return result(bytes,
+                      diagnostics: [diagnostic("invalid_range",
+                                               "no valid decision ranges")])
+      end
+
+      rewritten = apply_edits(bytes, edits)
+      begin
+        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)])
+      end
+      result(rewritten.force_encoding(unit[:original_bytes].encoding), changed: rewritten != bytes)
+    end
+
+    private
+
+    def supported_unit?(unit, _reasons)
+      status = unit[: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?
+    end
+
+    def decision_edit(bytes, decision, all_decisions)
+      start = decision[:byte_start]
+      length = decision[:byte_length]
+      return nil unless valid_range?(bytes, start, length)
+
+      nested = all_decisions.select do |candidate|
+        candidate != decision && contains?(start, length, candidate[:byte_start], candidate[:byte_length])
+      end
+      expression = render_range(bytes, start, length, decision, nested)
+      {
+        start: start,
+        finish: start + length,
+        text: frame(decision[:id], expression)
+      }
+    end
+
+    def render_range(bytes, start, length, decision, nested)
+      conditions = Array(decision[:conditions]).sort_by { |condition| condition[:byte_start] }
+      cursor = start
+      chunks = []
+      conditions.each do |condition|
+        cstart = condition[:byte_start]
+        clen = condition[:byte_length]
+        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)
+        cursor = cstart + clen
+      end
+      chunks << render_children(bytes, cursor, length - (cursor - start), nested)
+      chunks.join
+    end
+
+    def render_children(bytes, start, length, nested)
+      children = nested.select do |child|
+        contains?(start, length, child[:byte_start], child[:byte_length])
+      end
+      children = children.reject do |child|
+        nested.any? do |candidate|
+          candidate != child && contains?(candidate[:byte_start], candidate[:byte_length], child[:byte_start],
+                                          child[:byte_length])
+        end
+      end
+      children.sort_by! { |child| -child[:byte_start] }
+      output = bytes.byteslice(start, length)
+      children.each do |child|
+        child_text = render_range(bytes, child[:byte_start], child[:byte_length], child, nested.reject do |item|
+          item.equal?(child)
+        end)
+        child_text = frame(child[:id], child_text)
+        offset = child[:byte_start] - start
+        output[offset, child[:byte_length]] = child_text
+      end
+      output
+    end
+
+    def condition_wrapper(decision_id, index, expression)
+      "#{RUNTIME}.condition(#{decision_id.inspect}, #{index}, (#{expression}))"
+    end
+
+    def frame(decision_id, expression)
+      "(begin; #{RUNTIME}.enter(#{decision_id.inspect}); begin; " \
+        "#{RUNTIME}.finish(#{decision_id.inspect}, (#{expression})); ensure; " \
+        "#{RUNTIME}.leave(#{decision_id.inspect}); end; end)"
+    end
+
+    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]
+      end
+    end
+
+    def valid_range?(bytes, start, length)
+      start.is_a?(Integer) && length.is_a?(Integer) && start >= 0 && length >= 0 && start + length <= bytes.bytesize
+    end
+
+    def contains?(outer_start, outer_length, inner_start, inner_length)
+      valid_integer_range?(inner_start,
+                           inner_length) && inner_start >= outer_start &&
+        inner_start + inner_length <= outer_start + outer_length
+    end
+
+    def valid_integer_range?(start, length)
+      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
+    end
+
+    def diagnostic(code, message)
+      { code: code.to_s, severity: "warning", message: message, source_id: nil, decision_id: nil,
+        execution_id: nil, test_id: nil, details: {} }.freeze
+    end
+  end
+end

data/lib/branchproof/limits.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Branchproof
+  # Defines bounded storage and search limits for one analysis.
+  module Limits
+    KEYS = %i[
+      conditions_per_decision vectors_per_decision owner_associations_per_run
+      tests_per_run exact_candidates exact_search_nodes constraint_search_states
+    ].freeze
+    DEFAULTS = {
+      conditions_per_decision: 64,
+      vectors_per_decision: 8192,
+      owner_associations_per_run: 200_000,
+      tests_per_run: 50_000,
+      exact_candidates: 32,
+      exact_search_nodes: 100_000,
+      constraint_search_states: 10_000
+    }.freeze
+
+    module_function
+
+    def default
+      Records.build(DEFAULTS)
+    end
+
+    def normalize(overrides = {})
+      raise ArgumentError, "limits must be a Hash" unless overrides.is_a?(Hash)
+
+      normalized_overrides = overrides.each_with_object({}) do |(key, value), result|
+        raise ArgumentError, "limit keys must be Symbols or Strings" unless key.is_a?(String) || key.is_a?(Symbol)
+
+        result[key.to_sym] = value
+      end
+      values = DEFAULTS.merge(normalized_overrides)
+      unknown = values.keys - KEYS
+      raise ArgumentError, "unknown limit: #{unknown.first}" unless unknown.empty?
+
+      values.each do |key, value|
+        raise ArgumentError, "#{key} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+      end
+      Records.build(values)
+    end
+  end
+end