debugbundle 2.0.1 → 2.1.0

data/lib/debugbundle/exception_evidence.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'debugbundle/telemetry_privacy'
+require 'debugbundle/evidence_value'
+
+module DebugBundle
+  # Consume the existing protected native snapshots, never an Exception or its
+  # formatter. Even MRI's bound Exception#to_s converts a non-string message;
+  # new inspection must not introduce another such application callback.
+  module ExceptionEvidence
+    module_function
+
+    def native_type?(value, type)
+      EvidenceValue.type?(value, type)
+    end
+
+    def owned_text(value, limit, scrub: true, state: nil)
+      return nil unless Object.instance_method(:is_a?).bind_call(value, String)
+
+      copy = String.new(value)
+      state[:truncated] = true if state && (copy.bytesize > limit || !copy.valid_encoding?)
+      copy = copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub
+      # A split UTF-8 sequence can expand to a replacement character.
+      copy = copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub('')
+      copy = TelemetryPrivacy.protect(copy) if scrub
+      state[:truncated] = true if state && copy.bytesize > limit
+      copy.byteslice(0, limit).force_encoding(Encoding::UTF_8).scrub('')
+    end
+
+    def retained_snapshot(value, state)
+      return nil unless native_type?(value, Hash)
+      return nil if Hash.instance_method(:size).bind_call(value) > 32
+
+      keys = Hash.instance_method(:keys).bind_call(value)
+      return nil unless keys.all? { |key| native_type?(key, String) }
+
+      result = {}
+      { 'name' => 256, 'message' => 2048, 'stack' => 16_384 }.each do |key, limit|
+        source = Hash.instance_method(:fetch).bind_call(value, key, nil)
+        # Parse coordinates before a URL scrub can discard a fragment containing
+        # the native line suffix. Only scrubbed fields/text enter the graph.
+        result[key] = owned_text(source, limit, scrub: key != 'stack', state: state)
+        return nil if result[key].nil?
+      end
+      result['name'] = 'Exception' if result['name'].empty?
+      result['message'] = '[message unavailable]' if result['message'].empty?
+      result
+    end
+
+    def from_retained(root:, causes:, fatal: false, budget_bytes: 32_768)
+      maximum = [fatal ? 4096 : 32_768, budget_bytes].min
+      return nil if maximum < 512
+
+      state = { truncated: false }
+      outer = retained_snapshot(root, state)
+      return nil unless outer && native_type?(causes, Array)
+
+      limit = fatal ? 2 : 5 # A linear cause path has at most four edges.
+      count = Array.instance_method(:length).bind_call(causes)
+      snapshots = [outer]
+      [count, limit - 1].min.times do |index|
+        cause = retained_snapshot(Array.instance_method(:[]).bind_call(causes, index), state)
+        break unless cause
+
+        snapshots << cause
+      end
+      graph = build_graph(snapshots, count > snapshots.length - 1 || state[:truncated])
+      shrink_metadata(graph, maximum)
+      return nil if JSON.generate(graph).bytesize > maximum
+
+      append_traces(graph, snapshots, maximum, fatal ? 8 : 32)
+      graph
+    rescue StandardError
+      nil
+    end
+
+    def build_graph(snapshots, truncated)
+      nodes = snapshots.each_with_index.map do |snapshot, index|
+        {
+          'id' => index, 'name' => snapshot['name'], 'message' => snapshot['message'], 'stack' => nil,
+          'trace_origin' => snapshot['stack'].empty? ? 'unavailable' : 'runtime_reported',
+          'parsing_status' => snapshot['stack'].empty? ? 'unavailable' : 'unparsed', 'frames' => [],
+          'relationships' => index + 1 < snapshots.length ? [{ 'kind' => 'cause', 'target_id' => index + 1 }] : []
+        }
+      end
+      { 'version' => 1, 'runtime' => 'ruby', 'root_id' => 0, 'nodes' => nodes,
+        'truncated' => truncated, 'unavailable_reason' => nil }
+    end
+
+    def shrink_metadata(graph, maximum)
+      return if JSON.generate(graph).bytesize <= maximum - 32
+
+      mark_budget(graph)
+      graph['nodes'].each do |node|
+        node['name'] = owned_text(node['name'], 64)
+        node['message'] = owned_text(node['message'], 128)
+      end
+      while graph['nodes'].length > 1 && JSON.generate(graph).bytesize > maximum - 32
+        graph['nodes'].pop
+        graph['nodes'].last['relationships'] = []
+      end
+    end
+
+    def append_traces(graph, snapshots, maximum, frame_limit)
+      # Charge exact JSON fragments incrementally. Re-encoding the whole graph
+      # for every rejected frame would amplify work on adversarial long stacks.
+      used = JSON.generate(graph).bytesize + 32
+      # A bounded graph often repeats one file/function across many frames.
+      # Reuse protected text only within this projection; returned strings remain
+      # independently owned so a hook cannot mutate another frame through aliases.
+      text_cache = {}
+      graph['nodes'].each_with_index do |node, index|
+        stack = snapshots[index]['stack']
+        stack.each_line do |line|
+          frame = parse_frame(line, text_cache)
+          next unless frame
+
+          cost = JSON.generate(frame).bytesize + (node['frames'].empty? ? 0 : 1)
+          if node['frames'].length >= frame_limit || used + cost > maximum
+            node['parsing_status'] = 'truncated'
+            mark_budget(graph)
+            break
+          end
+          node['frames'] << frame
+          node['parsing_status'] = 'parsed'
+          used += cost
+        end
+        next unless node['parsing_status'] == 'unparsed'
+
+        retained = owned_text(stack, 16_384).gsub(%r{\bhttps?://[^\s<>"']+}i) { |url| frame_file(url) }
+        cost = JSON.generate(retained).bytesize - 4 # Replaces JSON null.
+        if used + cost <= maximum
+          node['stack'] = retained
+          used += cost
+        else
+          mark_budget(graph)
+        end
+      end
+    end
+
+    def parse_frame(line, text_cache = nil)
+      match = /\A(.+):([1-9]\d*)(?::in [`']([^`'\r\n]*)[`'])?\z/.match(line.strip)
+      return nil unless match
+
+      { 'function' => match[3] && frame_text(match[3], 256, text_cache),
+        'file' => frame_text(match[1], 2048, text_cache),
+        'line' => match[2].to_i, 'column' => nil, 'classification' => 'unknown' }
+    end
+
+    def frame_text(value, limit, cache)
+      return limit == 2048 ? frame_file(value) : owned_text(value, limit) unless cache
+
+      key = [limit, value]
+      cache[key] ||= (limit == 2048 ? frame_file(value) : owned_text(value, limit)).freeze
+      cache[key].dup
+    end
+
+    def frame_file(value)
+      result = owned_text(value, 2048)
+      return result unless result.match?(%r{\Ahttps?://}i)
+
+      uri = URI.parse(result)
+      uri.password = nil
+      uri.user = nil
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      '[withheld]'
+    end
+
+    def mark_budget(graph)
+      graph['truncated'] = true
+      graph['unavailable_reason'] = 'budget_exceeded'
+    end
+  end
+end

data/lib/debugbundle/framework_operation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  module FrameworkOperation
+    def self.run(client, ...)
+      # Custom clients implementing the older injection surface keep their
+      # established application behavior without claiming scoped evidence.
+      return yield unless client.respond_to?(:with_operation_context)
+
+      client.with_operation_context(...)
+    end
+  end
+end

data/lib/debugbundle/operation_context.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'debugbundle/evidence_wire'
+require 'debugbundle/telemetry_privacy'
+
+module DebugBundle
+  # Thread#[] is Fiber-local on the supported Ruby floor. New Fibers and threads
+  # do not inherit request ownership; completed/closed generations are revoked.
+  class OperationContext
+    def initialize
+      @key = :"__debugbundle_operation_#{object_id}"
+      @generation = 0
+    end
+
+    def current
+      lease = Thread.current[@key]
+      return nil unless lease && lease[:generation] == @generation && lease[:active]
+      return nil unless lease[:parents].all? { |parent| parent[:active] }
+
+      lease
+    end
+
+    def begin_scope(kind:, name: nil, limit_ms: nil, correlation: nil)
+      previous = current
+      parents = previous ? previous[:parents] + [previous] : []
+      return nil if parents.length > 15
+
+      owned_kind = EvidenceValue.options(kind)
+      owned_name = EvidenceValue.copy(name)
+      owned_limit = EvidenceValue.copy(limit_ms)
+      owned_kind = 'unknown' unless %w[request command job unknown].include?(owned_kind)
+      unless EvidenceWire.text(owned_name,
+                               128) && !owned_name.empty? && TelemetryPrivacy.protect(owned_name) == owned_name
+        owned_name = nil
+      end
+      owned_limit = nil unless EvidenceWire.number(owned_limit)
+      lease = { generation: @generation, active: true, parents: parents, previous: previous,
+                scope: { 'kind' => 'operation', 'operation_id' => SecureRandom.uuid },
+                kind: owned_kind, name: owned_name, limit: owned_limit,
+                correlation: scoped_correlation(previous, correlation),
+                started: Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      Thread.current[@key] = lease
+      lease
+    rescue StandardError
+      nil
+    end
+
+    def end_scope(lease)
+      return unless lease
+
+      lease[:active] = false
+      return unless Thread.current[@key].equal?(lease)
+
+      Thread.current[@key] = lease[:generation] == @generation ? lease[:previous] : nil
+    rescue StandardError
+      nil
+    end
+
+    def snapshot
+      lease = current
+      return nil unless lease
+
+      { 'version' => 1, 'kind' => lease[:kind], 'name' => lease[:name], 'limit_ms' => lease[:limit],
+        'elapsed_ms' => [(Process.clock_gettime(Process::CLOCK_MONOTONIC) - lease[:started]) * 1000, 0].max }
+    end
+
+    def scope = current&.fetch(:scope)&.dup
+
+    def scoped_correlation(previous, input)
+      owned = EvidenceValue.options(input)
+      selected = {}
+      if owned.is_a?(Hash)
+        %w[request_id trace_id session_id user_id_hash].each do |field|
+          value = owned[field]
+          next unless EvidenceWire.text(value, 256) && !value.strip.empty?
+          next unless TelemetryPrivacy.protect(value) == value
+
+          selected[field] = value
+        end
+      end
+      (previous ? previous[:correlation] : {}).merge(selected)
+    end
+
+    def clear
+      @generation += 1
+      Thread.current[@key] = nil
+    end
+  end
+end

data/lib/debugbundle/rack/middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'uri'
+require 'debugbundle/framework_operation'
 
 module DebugBundle
   module Rack
@@ -13,30 +14,32 @@ module DebugBundle
       def call(env)
         request_context = build_request_context(env)
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @client.with_request_trigger(request_context.fetch(:request)) do
-          status, headers, body = @app.call(env)
-          duration_ms = elapsed_ms(started_at)
+        FrameworkOperation.run(@client, kind: 'request', correlation: request_context.slice(:request_id, :trace_id)) do
+          @client.with_request_trigger(request_context.fetch(:request)) do
+            status, headers, body = @app.call(env)
+            duration_ms = elapsed_ms(started_at)
 
-          @client.capture_request(
-            request_context.fetch(:request),
-            { status_code: status, headers: headers.to_h },
-            context: request_context.merge(duration_ms: duration_ms, route_template: route_template(env))
-          )
+            @client.capture_request(
+              request_context.fetch(:request),
+              { status_code: status, headers: headers.to_h },
+              context: request_context.merge(duration_ms: duration_ms, route_template: route_template(env))
+            )
 
-          [status, headers, body]
+            [status, headers, body]
+          end
+        rescue StandardError => e
+          duration_ms = elapsed_ms(started_at)
+          @client.capture_exception(
+            e,
+            context: request_context.merge(
+              response: { status_code: 500, headers: {} },
+              duration_ms: duration_ms,
+              route_template: route_template(env)
+            ),
+            handled: false
+          )
+          raise
         end
-      rescue StandardError => e
-        duration_ms = elapsed_ms(started_at)
-        @client.capture_exception(
-          e,
-          context: request_context.merge(
-            response: { status_code: 500, headers: {} },
-            duration_ms: duration_ms,
-            route_template: route_template(env)
-          ),
-          handled: false
-        )
-        raise
       end
 
       private

data/lib/debugbundle/rack/relay_middleware.rb

@@ -11,10 +11,13 @@ module DebugBundle
       end
 
       def call(env)
+        limit = @handler.respond_to?(:max_body_bytes) ? @handler.max_body_bytes : Relay::DEFAULT_MAX_BODY_BYTES
+        limit = Relay::DEFAULT_MAX_BODY_BYTES unless limit.is_a?(Integer) && limit.positive?
         response = @handler.handle(
           method: env['REQUEST_METHOD'],
+          url: "#{env['PATH_INFO']}?#{env['QUERY_STRING']}",
           headers: relay_headers(env),
-          body: env.fetch('rack.input', StringIO.new).read,
+          body: env.fetch('rack.input', StringIO.new).read(limit + 1),
           ip_address: env['REMOTE_ADDR']
         )
 

data/lib/debugbundle/rails/railtie.rb

@@ -17,7 +17,10 @@ if defined?(Rails::Railtie)
             project_mode: options.project_mode || :connected,
             local_events_dir: options.local_events_dir || DebugBundle::Config::DEFAULT_LOCAL_EVENTS_DIR,
             endpoint: options.endpoint || DebugBundle::Config::DEFAULT_ENDPOINT,
-            redact_fields: Array(options.redact_fields) + Array(app.config.filter_parameters)
+            redact_fields: Array(options.redact_fields) + Array(app.config.filter_parameters),
+            capture_exception_evidence: options.capture_exception_evidence != false,
+            capture_recovery_observations: options.capture_recovery_observations == true,
+            evidence_capabilities: options.evidence_capabilities
           )
 
           app.middleware.use(DebugBundle::Rack::Middleware, client: client)

data/lib/debugbundle/rails/relay_endpoint.rb

@@ -36,7 +36,8 @@ module DebugBundle
         max_body_bytes: relay_option(options, :relay_max_body_bytes, Relay::DEFAULT_MAX_BODY_BYTES),
         rate_limit_per_minute: relay_rate_limit(options),
         rate_limit_store: relay_option(options, :relay_rate_limit_store, nil),
-        forward_transport: relay_option(options, :relay_forward_transport, nil)
+        forward_transport: relay_option(options, :relay_forward_transport, nil),
+        evidence_capabilities: relay_option(options, :relay_evidence_capabilities, nil)
       )
     end
 

data/lib/debugbundle/relay/forwarder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'debugbundle/evidence_delivery'
+require 'debugbundle/event_batch'
+
+module DebugBundle
+  module Relay
+    class Forwarder
+      def initialize(transport, token, evidence)
+        @transport = transport
+        @token = token
+        @evidence = evidence
+      end
+
+      # The second result permits marking a spool delivered only after complete
+      # canonical acceptance. Legacy custom-transport acceptance stays compatible.
+      def send(events, discover:)
+        return [false, false] unless @token.is_a?(String) && !@token.empty?
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+        complete = true
+        features = EvidenceWire::FEATURES.dup
+        owned = events.map { |event| event.merge('project_token' => @token) }
+        EventBatch.chunks(owned).each do |chunk|
+          chunk = chunk.map { |event| EvidenceWire.supported(event, @evidence.features) }
+          return [false, false] if chunk.any?(&:nil?)
+
+          return [false, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          success, canonical = send_chunk(chunk, discover: discover, deadline: deadline)
+          features &= @evidence.features
+          @evidence.restrict(features)
+          return [false, false] unless success && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+
+          complete &&= canonical
+        end
+        [true, complete]
+      rescue StandardError
+        [false, false]
+      end
+
+      def send_chunk(events, discover:, deadline:)
+        required = discover || @transport.is_a?(Transport::HttpTransport)
+        response, ack, lost = forward(events, required, deadline)
+        return [false, false] unless response && ack
+        return [true, false] if ack[:kind] == :legacy
+        return [false, false] unless ack[:kind] == :acknowledged
+        return [true, true] if ack[:accepted] == events.length
+        return [false, false] unless lost
+
+        retry_events = ack.fetch(:terminal_errors).filter_map do |index, reason|
+          original = events.fetch(index)
+          next unless reason == 'invalid_event' && original['event_type'] == 'frontend_exception'
+
+          reduced = EvidenceWire.supported(original, @evidence.features)
+          reduced if reduced != original
+        end
+        return [false, false] if retry_events.empty?
+
+        _reply, retry_ack, = forward(retry_events, true, deadline)
+        complete = retry_ack && retry_ack[:kind] == :acknowledged &&
+                   ack[:accepted] + retry_ack[:accepted] == events.length
+        [!!complete, !!complete]
+      rescue StandardError
+        [false, false]
+      end
+
+      def forward(events, required, deadline)
+        return [nil, nil, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        owned = events.map { |event| event.merge('project_token' => @token) }
+        request = { project_token: @token, events: owned }
+        request[:deadline] = deadline if @transport.is_a?(Transport::HttpTransport)
+        response = Transport.coerce_result(@transport.call(request))
+        return [nil, nil, false] unless response.status_code.between?(200, 299)
+
+        ack = Acknowledgement.decide(response.body, events.length, required: required)
+        lost = @evidence.observe(response.body, required: required, valid: ack[:kind] == :acknowledged)
+        [response, ack, lost]
+      end
+    end
+  end
+end

data/lib/debugbundle/relay/handler.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'uri'
+require 'debugbundle/relay/forwarder'
 
 module DebugBundle
   module Relay
@@ -12,6 +13,7 @@ module DebugBundle
       request_event
       probe_event
       analytics_event
+      diagnostic_context
     ].freeze
     BROWSER_SDK_NAME = '@debugbundle/sdk-browser'
     DEFAULT_MAX_BODY_BYTES = 262_144
@@ -20,6 +22,8 @@ module DebugBundle
     Response = Struct.new(:status, :body, :headers, keyword_init: true)
 
     class Handler
+      attr_reader :max_body_bytes
+
       def initialize(
         project_mode: :connected,
         project_token: nil,
@@ -33,7 +37,8 @@ module DebugBundle
         max_body_bytes: DEFAULT_MAX_BODY_BYTES,
         rate_limit_per_minute: DEFAULT_RATE_LIMIT_PER_MINUTE,
         rate_limit_store: nil,
-        forward_transport: nil
+        forward_transport: nil,
+        evidence_capabilities: nil
       )
         @project_mode = project_mode.to_sym
         @project_token = project_token
@@ -48,16 +53,24 @@ module DebugBundle
         @rate_limit_per_minute = rate_limit_per_minute
         @rate_limit_store = rate_limit_store
         @forward_transport = forward_transport || Transport::HttpTransport.new(@endpoint)
+        @evidence = EvidenceDelivery.new(evidence_capabilities)
+        @forwarder = Forwarder.new(@forward_transport, @project_token, @evidence)
         @rate_limit_state = Hash.new { |hash, key| hash[key] = [] }
       end
 
       def handle(request)
         method = request.fetch(:method, 'POST').to_s.upcase
         headers = normalize_headers(request[:headers] || {})
+        discover = requests_evidence?(request, headers)
         raw_body = request[:body].to_s
         return Response.new(status: 403, body: nil, headers: {}) unless origin_allowed?(headers)
 
-        response_headers = source_origin(headers) ? cors_headers(source_origin(headers)) : {}
+        response_headers = if source_origin(headers)
+                             cors_headers(source_origin(headers),
+                                          headers['access-control-request-headers'])
+                           else
+                             {}
+                           end
         early_response = request_validation_response(
           method: method,
           headers: headers,
@@ -66,11 +79,17 @@ module DebugBundle
         )
         return with_headers(early_response, response_headers) if early_response
 
-        accepted, errors = sanitize_batch(raw_body)
+        accepted, errors, indexed = sanitize_batch(raw_body)
 
-        deliver(accepted) unless accepted.empty?
+        deliver(accepted, discover: discover) unless accepted.empty?
 
-        with_headers(batch_response(accepted, errors), response_headers)
+        response = batch_response(accepted, errors)
+        if discover
+          response.status = 202
+          response.body['evidence_capabilities'] = @evidence.descriptor
+          response.body['evidence_errors'] = indexed unless indexed.empty?
+        end
+        with_headers(response, response_headers)
       rescue JSON::ParserError
         with_headers(invalid_json_response, response_headers || {})
       rescue KeyError
@@ -130,27 +149,44 @@ module DebugBundle
         )
       end
 
-      def cors_headers(origin)
+      def cors_headers(origin, requested = nil)
+        allow_evidence = requested.to_s.downcase.split(',').map(&:strip).include?('x-debugbundle-evidence')
         {
           'Access-Control-Allow-Origin' => origin,
           'Access-Control-Allow-Methods' => 'POST, OPTIONS',
-          'Access-Control-Allow-Headers' => 'content-type',
+          'Access-Control-Allow-Headers' => allow_evidence ? 'content-type, x-debugbundle-evidence' : 'content-type',
           'Access-Control-Max-Age' => '600',
-          'Vary' => 'Origin'
+          'Vary' => allow_evidence ? 'Origin, Access-Control-Request-Headers' : 'Origin'
         }
       end
 
-      def deliver(events)
+      def requests_evidence?(request, headers)
+        return true if headers['x-debugbundle-evidence'] == '1'
+
+        url = request[:url]
+        return false unless url.is_a?(String) && url.bytesize <= 4096
+
+        URI.decode_www_form(URI.parse(url).query || '').include?(%w[debugbundle_evidence 1])
+      rescue URI::InvalidURIError, ArgumentError
+        false
+      end
+
+      def deliver(events, discover:)
         service_name = @service || events.first.dig('service', 'name') || 'service'
 
         case @project_mode
         when :local_only
-          Transport::FileTransport.new(@local_events_dir).call(service_name: service_name, events: events)
+          result = Transport::FileTransport.new(@local_events_dir).call(service_name: service_name, events: events)
+          raise 'relay_write_failed' unless result.status_code == 202
         when :connected
-          Transport::FileTransport.new(@spool_dir).call(service_name: service_name, events: events) if @durable_write
-
-          result = Transport.coerce_result(@forward_transport.call(project_token: @project_token, events: events))
-          raise 'relay_forward_failed' unless result.status_code.between?(200, 299)
+          if @durable_write
+            spool = Transport::FileTransport.new(@spool_dir)
+            written = spool.call(service_name: service_name, events: events)
+            raise 'relay_write_failed' unless written.status_code == 202
+          end
+          success, complete = @forwarder.send(events, discover: discover)
+          spool.mark_delivered(written.written_file_path) if complete && spool && written.written_file_path
+          raise 'relay_forward_failed' unless success || @durable_write
         else
           raise ArgumentError, 'unsupported relay project mode'
         end
@@ -161,12 +197,16 @@ module DebugBundle
         batch = decoded.fetch('batch')
         raise KeyError unless batch.is_a?(Array)
 
-        batch.each_with_index.with_object([[], []]) do |(candidate, index), (accepted, errors)|
+        batch.each_with_index.with_object([[], [], []]) do |(candidate, index), (accepted, errors, indexed)|
           sanitized = sanitize_event(candidate)
+          if sanitized && sanitized['event_type'] != 'analytics_event'
+            sanitized = EvidenceWire.supported(sanitized, @evidence.features)
+          end
           if sanitized
             accepted << sanitized
           else
             errors << "batch[#{index}]: Invalid browser relay event payload."
+            indexed << { 'index' => index, 'reason' => 'invalid_event' }
           end
         end
       end
@@ -194,19 +234,43 @@ module DebugBundle
             'environment' => @environment || service['environment'].to_s
           },
           'correlation' => sanitize_correlation(correlation, event_type),
-          'payload' => payload,
-          'project_token' => @project_token
+          'payload' => payload
         }
+        sanitized['project_token'] = @project_token if @project_token.is_a?(String) && !@project_token.empty?
+        sanitized['context'] = candidate['context'] if candidate['context'].is_a?(Hash)
+        return nil unless EvidenceWire.valid_optional?(sanitized)
+
+        new_contract = uses_evidence_contract?(sanitized)
+        return nil if new_contract && !BeforeSend.valid?(sanitized)
+
+        protect_relay_event(sanitized, new_contract)
+      rescue StandardError
+        nil
+      end
+
+      def protect_relay_event(sanitized, new_contract)
         return nil unless TelemetryPrivacy.safe_event_identity?(sanitized)
 
-        fields = TelemetryPrivacy.protect({ 'service' => sanitized['service'], 'payload' => sanitized['payload'] })
+        fields = TelemetryPrivacy.protect(sanitized.slice('service', 'payload', 'context'))
         return nil unless fields['service'].is_a?(Hash) && fields['payload'].is_a?(Hash)
 
-        sanitized.merge('service' => fields['service'], 'payload' => fields['payload'])
+        protected = sanitized.merge(fields)
+        if EvidenceWire.valid_optional?(protected) && (!new_contract || BeforeSend.valid?(protected))
+          return EventBatch.fit(protected)
+        end
+
+        reduced = EvidenceWire.without_optional(protected)
+        EventBatch.fit(reduced) if reduced && BeforeSend.valid?(reduced)
       rescue StandardError
         nil
       end
 
+      def uses_evidence_contract?(event)
+        event['event_type'] == 'diagnostic_context' ||
+          %w[exception_evidence resource_observations execution].any? { |field| event['payload'].key?(field) } ||
+          !EvidenceWire.reference(event.dig('context', 'evidence_reference')).nil?
+      end
+
       def sanitize_correlation(value, event_type)
         correlation = value.is_a?(Hash) ? value : {}
         keys = if event_type == 'analytics_event'