datadog 2.38.0 → 2.40.0

data/lib/datadog/open_feature/component.rb

@@ -1,32 +1,36 @@
 # frozen_string_literal: true
 
-require_relative 'transport'
-require_relative 'evaluation_engine'
-require_relative 'exposures/buffer'
-require_relative 'exposures/worker'
-require_relative 'exposures/deduplicator'
-require_relative 'exposures/reporter'
-require_relative 'metrics/flag_eval_metrics'
+require_relative "transport"
+require_relative "evaluation_engine"
+require_relative "exposures/buffer"
+require_relative "exposures/worker"
+require_relative "exposures/deduplicator"
+require_relative "exposures/reporter"
+require_relative "metrics/flag_eval_metrics"
+require_relative "flag_evaluation/writer"
+require_relative "hooks/flag_eval_metrics_hook"
+require_relative "hooks/flag_eval_evp_hook"
+require_relative "hooks/span_enrichment_hook"
 
 module Datadog
   module OpenFeature
     # This class is the entry point for the OpenFeature component
     class Component
-      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_hook
+      attr_reader :engine, :flag_eval_metrics_hook, :flag_eval_evp_hook, :span_enrichment_hook
 
       def self.build(settings, agent_settings, logger:, telemetry:)
         return unless settings.respond_to?(:open_feature) && settings.open_feature.enabled
 
         unless settings.respond_to?(:remote) && settings.remote.enabled
-          message = 'OpenFeature could not be enabled as Remote Configuration is currently disabled. ' \
-            'To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/.'
+          message = "OpenFeature could not be enabled as Remote Configuration is currently disabled. " \
+            "To enable Remote Configuration, see https://docs.datadoghq.com/remote_configuration/."
 
           logger.warn(message)
           return
         end
 
-        if RUBY_ENGINE != 'ruby'
-          message = 'OpenFeature could not be enabled as MRI is required, ' \
+        if RUBY_ENGINE != "ruby"
+          message = "OpenFeature could not be enabled as MRI is required, " \
             "but running on #{RUBY_ENGINE.inspect}"
 
           logger.warn(message)
@@ -34,9 +38,9 @@ module Datadog
         end
 
         if (libdatadog_api_failure = Core::LIBDATADOG_API_FAILURE)
-          message = 'OpenFeature could not be enabled as `libdatadog` is not loaded: ' \
+          message = "OpenFeature could not be enabled as `libdatadog` is not loaded: " \
             "#{libdatadog_api_failure.inspect}. For help solving this issue, " \
-            'please contact Datadog support at https://docs.datadoghq.com/help/.'
+            "please contact Datadog support at https://docs.datadoghq.com/help/."
 
           logger.warn(message)
           return
@@ -58,42 +62,47 @@ module Datadog
         @agent_settings = agent_settings
         @flag_eval_metrics_hook = create_flag_eval_metrics_hook
         @flag_eval_evp_hook = create_flag_eval_evp_hook
+        @span_enrichment_hook = create_span_enrichment_hook
       end
 
       def shutdown!
         @worker.graceful_shutdown
         @flag_eval_evp_writer&.stop
+        # Symmetric teardown: drop any accumulated span-enrichment state and
+        # subscriptions (Ruby CLAUDE.md mandates closing resources).
+        @span_enrichment_hook&.shutdown
       end
 
       private
 
       def create_flag_eval_metrics_hook
-        require_relative 'hooks/flag_eval_metrics_hook'
         return unless Hooks::FlagEvalMetricsHook.available?
 
         metrics = Metrics::FlagEvalMetrics.new(telemetry: @telemetry, logger: @logger)
         Hooks::FlagEvalMetricsHook.new(metrics)
-      rescue LoadError
-        nil
       end
 
       # Killswitch: DD_FLAGGING_EVALUATION_COUNTS_ENABLED (default on) gates only the EVP path.
       # Read through the datadog config registry, not raw ENV.
       def create_flag_eval_evp_hook
         return unless @settings.open_feature.evaluation_counts_enabled
-
-        require_relative 'hooks/flag_eval_evp_hook'
         return unless Hooks::FlagEvalEVPHook.available?
 
         evp_transport = Transport::HTTP.build_flagevaluations(
           agent_settings: @agent_settings,
           logger: @logger,
         )
-        require_relative 'flag_evaluation/writer'
         @flag_eval_evp_writer = FlagEvaluation::Writer.new(transport: evp_transport, logger: @logger, telemetry: @telemetry)
         Hooks::FlagEvalEVPHook.new(@flag_eval_evp_writer)
-      rescue LoadError
-        nil
+      end
+
+      # Construct the span-enrichment hook only when the opt-in gate is on, so
+      # there is no idle per-span overhead when disabled.
+      def create_span_enrichment_hook
+        return unless @settings.open_feature.span_enrichment_enabled
+
+        store = Hooks::SpanEnrichmentHook::SpanEnrichmentStateStore.new
+        Hooks::SpanEnrichmentHook.new(store, logger: @logger)
       end
     end
   end

data/lib/datadog/open_feature/configuration.rb

@@ -17,7 +17,20 @@ module Datadog
             settings :open_feature do
               option :enabled do |o|
                 o.type :bool
-                o.env 'DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED'
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED"
+                o.default false
+              end
+
+              # Opt-in gate for APM feature-flag span enrichment. When enabled,
+              # the provider attaches `ffe_*` tags to the local root APM span on
+              # finish. Distinct from `:enabled` (the provider gate) and off by
+              # default so it can be rolled out independently.
+              #
+              # TODO: benchmark the per-span-finish overhead on a high-span-count
+              # trace with this gate on before enabling it by default.
+              option :span_enrichment_enabled do |o|
+                o.type :bool
+                o.env "DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED"
                 o.default false
               end
 
@@ -25,7 +38,7 @@ module Datadog
               # disabled the existing OTel `feature_flag.evaluations` metric is unaffected.
               option :evaluation_counts_enabled do |o|
                 o.type :bool
-                o.env 'DD_FLAGGING_EVALUATION_COUNTS_ENABLED'
+                o.env "DD_FLAGGING_EVALUATION_COUNTS_ENABLED"
                 o.default true
               end
             end

data/lib/datadog/open_feature/evaluation_engine.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require_relative 'noop_evaluator'
-require_relative 'native_evaluator'
-require_relative 'resolution_details'
+require_relative "ext"
+require_relative "noop_evaluator"
+require_relative "native_evaluator"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
@@ -39,7 +39,7 @@ module Datadog
 
         result
       rescue => e
-        @telemetry.report(e, description: 'OpenFeature: Failed to fetch flag value')
+        @telemetry.report(e, description: "OpenFeature: Failed to fetch flag value")
 
         ResolutionDetails.build_error(
           value: default_value, error_code: Ext::GENERAL, error_message: "#{e.class}: #{e.message}"
@@ -51,14 +51,14 @@ module Datadog
       #       in the format expected by `libdatadog` without any modifications
       def reconfigure!(configuration)
         if configuration.nil?
-          @logger.debug('OpenFeature: Removing configuration')
+          @logger.debug("OpenFeature: Removing configuration")
 
           return @evaluator = NoopEvaluator.new(configuration)
         end
 
         @evaluator = NativeEvaluator.new(configuration)
       rescue => e
-        message = 'OpenFeature: Failed to reconfigure, reverting to the previous configuration'
+        message = "OpenFeature: Failed to reconfigure, reverting to the previous configuration"
 
         @logger.error("#{message}, #{e.class}: #{e.message}")
         @telemetry.report(e, description: "#{message} (#{e.class})")

data/lib/datadog/open_feature/exposures/buffer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../core/buffer/cruby'
+require_relative "../../core/buffer/cruby"
 
 module Datadog
   module OpenFeature

data/lib/datadog/open_feature/exposures/deduplicator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/lru_cache'
+require_relative "../../core/utils/lru_cache"
 
 module Datadog
   module OpenFeature

data/lib/datadog/open_feature/exposures/event.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/time'
+require_relative "../../core/utils/time"
 
 module Datadog
   module OpenFeature
     module Exposures
       # A data model for an exposure event
       module Event
-        TARGETING_KEY_FIELD = 'targeting_key'
+        TARGETING_KEY_FIELD = "targeting_key"
         ALLOWED_FIELD_TYPES = [String, Integer, Float, TrueClass, FalseClass].freeze
 
         class << self

data/lib/datadog/open_feature/exposures/reporter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'event'
-require_relative 'deduplicator'
+require_relative "event"
+require_relative "deduplicator"
 
 module Datadog
   module OpenFeature
@@ -30,7 +30,7 @@ module Datadog
           @worker.enqueue(event)
         rescue => e
           @logger.debug { "OpenFeature: Failed to report resolution details: #{e.class}: #{e.message}" }
-          @telemetry.report(e, description: 'OpenFeature: Failed to report resolution details')
+          @telemetry.report(e, description: "OpenFeature: Failed to report resolution details")
 
           false
         end

data/lib/datadog/open_feature/exposures/worker.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils/time'
-require_relative '../../core/workers/queue'
-require_relative '../../core/workers/polling'
+require_relative "../../core/utils/time"
+require_relative "../../core/workers/queue"
+require_relative "../../core/workers/polling"
 
-require_relative 'buffer'
-require_relative 'batch_builder'
+require_relative "buffer"
+require_relative "batch_builder"
 
 module Datadog
   module OpenFeature
@@ -106,7 +106,7 @@ module Datadog
           response
         rescue => e
           @logger.debug { "OpenFeature: Failed to flush resolution details events: #{e.class}: #{e.message}" }
-          @telemetry.report(e, description: 'OpenFeature: Failed to flush resolution details events')
+          @telemetry.report(e, description: "OpenFeature: Failed to flush resolution details events")
 
           nil
         end

data/lib/datadog/open_feature/ext.rb

@@ -3,14 +3,19 @@
 module Datadog
   module OpenFeature
     module Ext
-      ERROR = 'ERROR'
-      DEFAULT = 'DEFAULT'
-      INITIALIZING = 'INITIALIZING'
-      UNKNOWN_TYPE = 'UNKNOWN_TYPE'
-      PARSE_ERROR = 'PARSE_ERROR'
-      GENERAL = 'GENERAL'
-      PROVIDER_FATAL = 'PROVIDER_FATAL'
-      PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
+      ERROR = "ERROR"
+      DEFAULT = "DEFAULT"
+      INITIALIZING = "INITIALIZING"
+      UNKNOWN_TYPE = "UNKNOWN_TYPE"
+      PARSE_ERROR = "PARSE_ERROR"
+      GENERAL = "GENERAL"
+      PROVIDER_FATAL = "PROVIDER_FATAL"
+      PROVIDER_NOT_READY = "PROVIDER_NOT_READY"
+
+      # Flag-metadata key under which the provider threads the assignment's
+      # allocation key to the flag-evaluation hooks. The wire string is the
+      # value so the writer (provider) and readers (EVP/metrics hooks) can't drift.
+      METADATA_ALLOCATION_KEY = "__dd_allocation_key"
     end
   end
 end

data/lib/datadog/open_feature/flag_evaluation/aggregator.rb

@@ -18,11 +18,11 @@ module Datadog
         MAX_CONTEXT_DEPTH = 32
 
         # Type tags so values of different Ruby types never collide in the canonical key.
-        CTX_TAG_STRING = 's'
-        CTX_TAG_BOOL = 'b'
-        CTX_TAG_INTEGER = 'i'
-        CTX_TAG_FLOAT = 'f'
-        CTX_TAG_OTHER = 'o'
+        CTX_TAG_STRING = "s"
+        CTX_TAG_BOOL = "b"
+        CTX_TAG_INTEGER = "i"
+        CTX_TAG_FLOAT = "f"
+        CTX_TAG_OTHER = "o"
 
         EVAL_SCALE_TARGET_FLAGS = 2_500
         EVAL_SCALE_FULL_BUCKETS_PER_FLAG = 50
@@ -176,9 +176,9 @@ module Datadog
         #                8-byte big-endian value length + value bytes.
         # No hash digest — the key IS the full encoding (collision-free, no FNV).
         def canonical_context_key(attrs)
-          return '' if attrs.nil? || attrs.empty?
+          return "" if attrs.nil? || attrs.empty?
 
-          buffer = String.new('', encoding: Encoding::BINARY)
+          buffer = String.new("", encoding: Encoding::BINARY)
           attrs.keys.sort.each do |key|
             value = attrs[key]
             buffer << length_delimited(key.to_s)
@@ -233,7 +233,7 @@ module Datadog
           bytes = string.encode(Encoding::BINARY, invalid: :replace, undef: :replace)
           byte_length = bytes.bytesize
           # Build 8-byte big-endian length
-          length_bytes = String.new('', encoding: Encoding::BINARY)
+          length_bytes = String.new("", encoding: Encoding::BINARY)
           8.times do |index|
             length_bytes.prepend(((byte_length >> (8 * index)) & 0xFF).chr(Encoding::BINARY))
           end

data/lib/datadog/open_feature/flag_evaluation/writer.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require_relative 'aggregator'
-require_relative '../../core/encoding'
-require_relative '../../core/evp'
-require_relative '../../core/utils/time'
-require_relative '../../core/workers/async'
+require_relative "aggregator"
+require_relative "../../core/encoding"
+require_relative "../../core/evp"
+require_relative "../../core/utils/time"
+require_relative "../../core/workers/async"
 
 module Datadog
   module OpenFeature
@@ -29,15 +29,15 @@ module Datadog
         QUEUE_SIZE = 4_096
         MAX_DRAIN_EVENTS_PER_CYCLE = 1_024
         PAYLOAD_SIZE_LIMIT_BYTES = Core::EVP::PAYLOAD_SIZE_LIMIT_BYTES
-        TELEMETRY_NAMESPACE = 'tracers'
-        ROWS_DROPPED_METRIC = 'flagevaluation.rows.dropped'
-        ROWS_DEGRADED_METRIC = 'flagevaluation.rows.degraded'
-        PAYLOAD_SPLITS_METRIC = 'flagevaluation.payload.splits'
+        TELEMETRY_NAMESPACE = "tracers"
+        ROWS_DROPPED_METRIC = "flagevaluation.rows.dropped"
+        ROWS_DEGRADED_METRIC = "flagevaluation.rows.degraded"
+        PAYLOAD_SPLITS_METRIC = "flagevaluation.payload.splits"
 
-        REASON_QUEUE_OVERFLOW = 'queue_overflow'
-        REASON_DEGRADED_CAP = 'degraded_cap'
-        REASON_CARDINALITY_CAP = 'cardinality_cap'
-        REASON_PAYLOAD_LIMIT = 'payload_limit'
+        REASON_QUEUE_OVERFLOW = "queue_overflow"
+        REASON_DEGRADED_CAP = "degraded_cap"
+        REASON_CARDINALITY_CAP = "cardinality_cap"
+        REASON_PAYLOAD_LIMIT = "payload_limit"
 
         # Service context fields for the batch wrapper.
         attr_reader :service_context
@@ -98,7 +98,7 @@ module Datadog
 
           return true if join(SHUTDOWN_TIMEOUT_SECONDS)
 
-          @logger.debug { 'OpenFeature EVP: writer did not stop gracefully; terminating worker thread' }
+          @logger.debug { "OpenFeature EVP: writer did not stop gracefully; terminating worker thread" }
           terminate
         end
 
@@ -117,9 +117,9 @@ module Datadog
 
         def build_service_context
           config = Datadog.configuration
-          ctx = {'service' => config.service.to_s}
-          ctx['env'] = config.env if config.env && !config.env.empty?
-          ctx['version'] = config.version if config.version && !config.version.empty?
+          ctx = {"service" => config.service.to_s}
+          ctx["env"] = config.env if config.env && !config.env.empty?
+          ctx["version"] = config.version if config.version && !config.version.empty?
           ctx
         end
 
@@ -261,7 +261,7 @@ module Datadog
           record_telemetry_count(ROWS_DROPPED_METRIC, dropped_overflow, reason: REASON_DEGRADED_CAP)
 
           @logger.debug do
-            'OpenFeature EVP: dropped events ' \
+            "OpenFeature EVP: dropped events " \
               "queue_overflow=#{dropped_queue} degraded_overflow=#{dropped_overflow}"
           end
         end
@@ -300,27 +300,27 @@ module Datadog
         def build_event(flag_key:, variant:, allocation_key:, targeting_key:, entry:, flush_time_ms:, tier:)
           # @type var event: ::Hash[::String, untyped]
           event = {
-            'timestamp' => flush_time_ms,
-            'flag' => {'key' => flag_key},
-            'first_evaluation' => entry[:first_evaluation],
-            'last_evaluation' => entry[:last_evaluation],
-            'evaluation_count' => entry[:count],
+            "timestamp" => flush_time_ms,
+            "flag" => {"key" => flag_key},
+            "first_evaluation" => entry[:first_evaluation],
+            "last_evaluation" => entry[:last_evaluation],
+            "evaluation_count" => entry[:count],
           }
 
-          event['runtime_default_used'] = true if entry[:runtime_default]
-          event['error'] = {'message' => entry[:error_message]} if entry[:error_message] && !entry[:error_message].empty?
+          event["runtime_default_used"] = true if entry[:runtime_default]
+          event["error"] = {"message" => entry[:error_message]} if entry[:error_message] && !entry[:error_message].empty?
 
           # variant + allocation are present in both tiers (omitempty per schema).
-          event['variant'] = {'key' => variant} if variant && !variant.empty?
-          event['allocation'] = {'key' => allocation_key} if allocation_key && !allocation_key.empty?
+          event["variant"] = {"key" => variant} if variant && !variant.empty?
+          event["allocation"] = {"key" => allocation_key} if allocation_key && !allocation_key.empty?
 
           # Full-tier additionally carries targeting_key + the pruned evaluation context;
           # the degraded tier omits both.
           if tier == :full
-            event['targeting_key'] = targeting_key if targeting_key && !targeting_key.empty?
+            event["targeting_key"] = targeting_key if targeting_key && !targeting_key.empty?
 
             if entry[:context_attrs] && !entry[:context_attrs].empty?
-              event['context'] = {'evaluation' => entry[:context_attrs]}
+              event["context"] = {"evaluation" => entry[:context_attrs]}
             end
           end
 
@@ -330,7 +330,7 @@ module Datadog
         def send_payload_batches(events)
           context_json = Core::Encoding::JSONEncoder.encode(@service_context)
           payload_prefix = "{\"context\":#{context_json},\"flagEvaluations\":["
-          payload_suffix = ']}'
+          payload_suffix = "]}"
           base_payload_size = payload_prefix.bytesize + payload_suffix.bytesize
 
           batch = []
@@ -372,8 +372,8 @@ module Datadog
         def send_payload_batch(events)
           response = @transport.send_flag_evaluations(
             {
-              'context' => @service_context,
-              'flagEvaluations' => events,
+              "context" => @service_context,
+              "flagEvaluations" => events,
             }
           )
           if response.respond_to?(:ok?) && !response.ok?
@@ -402,11 +402,11 @@ module Datadog
         end
 
         def degrade_event_for_payload_limit(event)
-          return unless event.key?('targeting_key') || event.key?('context')
+          return unless event.key?("targeting_key") || event.key?("context")
 
           degraded = event.dup
-          degraded.delete('targeting_key')
-          degraded.delete('context')
+          degraded.delete("targeting_key")
+          degraded.delete("context")
           degraded
         end
 
@@ -415,7 +415,7 @@ module Datadog
         end
 
         def event_count(event)
-          count = event['evaluation_count'].to_i
+          count = event["evaluation_count"].to_i
           count.positive? ? count : 1
         end
 

data/lib/datadog/open_feature/hooks/flag_eval_evp_hook.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../ext"
+
 module Datadog
   module OpenFeature
     module Hooks
@@ -13,7 +15,7 @@ module Datadog
       # stay on the OTel path. This hook is registered as a provider hook so it receives
       # the SDK-final EvaluationDetails after hook failures and type validation.
       class FlagEvalEVPHook
-        TYPE_MISMATCH_ERROR_CODE = 'TYPE_MISMATCH'
+        TYPE_MISMATCH_ERROR_CODE = "TYPE_MISMATCH"
 
         # Include the Hook module if available (SDK >= 0.5.0) for interface documentation
         # and default implementations of other hook methods (before, after, error)
@@ -37,7 +39,7 @@ module Datadog
           # Eval-time stamped by the provider at eval-entry time; fall back to hook-fire time.
           # Metadata key: 'dd.eval.timestamp_ms' (int, ms since epoch) — stamped at eval entry.
           metadata = evaluation_details.flag_metadata
-          eval_time_ms = metadata.is_a?(Hash) ? metadata['dd.eval.timestamp_ms'] : nil
+          eval_time_ms = metadata.is_a?(Hash) ? metadata["dd.eval.timestamp_ms"] : nil
           eval_time_ms ||= (Core::Utils::Time.now.to_f * 1000).to_i
 
           writer.enqueue(
@@ -75,12 +77,11 @@ module Datadog
           fields.reject { |k, _| k.to_s == ::OpenFeature::SDK::EvaluationContext::TARGETING_KEY }
         end
 
-        # Same key as OTel hook ('__dd_allocation_key') — do not diverge.
         def extract_allocation_key(evaluation_details)
           metadata = evaluation_details.flag_metadata
           return unless metadata.is_a?(Hash)
 
-          metadata['__dd_allocation_key']
+          metadata[Ext::METADATA_ALLOCATION_KEY]
         end
 
         def extract_error_message(evaluation_details)

data/lib/datadog/open_feature/hooks/flag_eval_metrics_hook.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../ext"
+
 module Datadog
   module OpenFeature
     module Hooks
@@ -41,7 +43,7 @@ module Datadog
           metadata = evaluation_details.flag_metadata
           return unless metadata.is_a?(Hash)
 
-          metadata['__dd_allocation_key']
+          metadata[Ext::METADATA_ALLOCATION_KEY]
         end
       end
     end

data/lib/datadog/open_feature/hooks/span_enrichment_hook/codec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Encoding/crypto helpers implementing the fixed cross-SDK wire format.
+        module Codec
+          module_function
+
+          # ULEB128 stores 7 bits per byte; the high bit flags that more bytes follow.
+          LOW_7_BITS_MASK = 0x7F
+          CONTINUATION_BIT = 0x80
+
+          # The `bytes` buffer built below MUST be binary (ASCII-8BIT): `String#<<`
+          # with an Integer on a UTF-8 string appends a Unicode *codepoint*, so any
+          # byte >= 0x80 would be re-encoded as a 2-byte UTF-8 sequence and corrupt
+          # the varint (e.g. serial 2312 -> bytes 88 12, but UTF-8 would emit
+          # C2 88 12 = 296002 on decode). `(+'').b` gives a mutable binary string.
+          def encode_varint(value)
+            bytes = (+"").b
+            while value > LOW_7_BITS_MASK
+              bytes << ((value & LOW_7_BITS_MASK) | CONTINUATION_BIT)
+              value >>= 7
+            end
+            bytes << (value & LOW_7_BITS_MASK)
+            bytes
+          end
+
+          # Encode a Set of serial ids as base64(ULEB128 delta-varint).
+          # Empty set -> empty string (the caller omits the tag).
+          def encode_delta_varint(serial_ids)
+            sorted = serial_ids.to_a.sort
+            return "" if sorted.empty?
+
+            bytes = (+"").b
+            prev = 0
+            sorted.each do |id|
+              bytes << encode_varint(id - prev)
+              prev = id
+            end
+            # `pack('m0')` is RFC 4648 base64 with no newlines (== strict_encode64)
+            # and needs no `base64` gem, which stopped being a default gem in Ruby 3.4.
+            [bytes].pack("m0")
+          end
+
+          # Lowercase hex SHA256 of the targeting key: it is hashed before
+          # emission so raw user identifiers never leave the process.
+          def hash_targeting_key(targeting_key)
+            Digest::SHA256.hexdigest(targeting_key)
+          end
+        end
+      end
+    end
+  end
+end