e11y 0.2.0 → 1.0.0

data/lib/e11y/linters/slo/config_consistency_linter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/slo/config_loader"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for slo.yml custom_slos consistency with Event class definitions.
+      #
+      # Ensures every event referenced in slo.yml custom_slos:
+      # - Exists (constantize succeeds)
+      # - Has slo enabled (slo_enabled?)
+      # - Has contributes_to matching the slo_name in config
+      class ConfigConsistencyLinter
+        class << self
+          # Validate slo.yml custom_slos against Event class definitions.
+          #
+          # @param search_paths [Array<String>, nil] Optional search paths for ConfigLoader.
+          #   When nil, ConfigLoader uses default paths.
+          # @raise [E11y::Linters::LinterError] when any event fails validation
+          def validate!(search_paths: nil)
+            config = if search_paths
+                       E11y::SLO::ConfigLoader.load(search_paths: search_paths)
+                     else
+                       E11y::SLO::ConfigLoader.load
+                     end
+
+            return if config.nil?
+            return if config["custom_slos"].nil? || config["custom_slos"].empty?
+
+            errors = []
+
+            config["custom_slos"].each do |slo|
+              slo_name = slo["name"]
+              events = slo["events"] || []
+
+              events.each do |event_class_name|
+                error = validate_event(slo_name, event_class_name)
+                errors << error if error
+              end
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+
+          private
+
+          def validate_event(slo_name, event_class_name)
+            event_class = constantize_event(event_class_name)
+            return "Event class '#{event_class_name}' does not exist (constantize failed)" if event_class.nil?
+
+            unless event_class.respond_to?(:slo_enabled?) && event_class.slo_enabled?
+              return "Event #{event_class_name} is referenced in slo.yml (SLO '#{slo_name}') but has slo disabled"
+            end
+
+            contributes_to = event_class.slo_config&.contributes_to_value
+            unless contributes_to == slo_name
+              return "Event #{event_class_name} contributes_to '#{contributes_to}' but slo.yml defines SLO '#{slo_name}'"
+            end
+
+            nil
+          end
+
+          def constantize_event(event_class_name)
+            Object.const_get(event_class_name)
+          rescue NameError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/linters/slo/explicit_declaration_linter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/registry"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for explicit SLO declaration on Event classes.
+      #
+      # Ensures every registered event class has either `slo do ... end` or
+      # `slo false` — i.e. slo_enabled? or slo_disabled? must be true.
+      class ExplicitDeclarationLinter
+        class << self
+          # Validate all registered event classes have explicit SLO declaration.
+          #
+          # @raise [E11y::Linters::LinterError] when any event has neither slo_enabled? nor slo_disabled?
+          def validate!
+            errors = []
+
+            E11y::Registry.event_classes.each do |event_class|
+              next if event_class.slo_enabled? || event_class.slo_disabled?
+
+              name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+              errors << "Event #{name} missing explicit SLO declaration! Add `slo do ... end` or `slo false`"
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/linters/slo/slo_status_from_linter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "e11y/linters/base"
+require "e11y/registry"
+
+module E11y
+  module Linters
+    module SLO
+      # Linter for SLO-enabled events: requires slo_status_from and contributes_to.
+      #
+      # When an event has slo_enabled?, it must define:
+      # - slo_status_from (slo_config.slo_status_proc) — how to compute slo_status from payload
+      # - contributes_to (slo_config.contributes_to_value) — which custom SLO this event feeds
+      class SloStatusFromLinter
+        class << self
+          # Validate all SLO-enabled event classes have slo_status_from and contributes_to.
+          #
+          # @raise [E11y::Linters::LinterError] when any slo-enabled event is missing either
+          def validate!
+            errors = []
+
+            E11y::Registry.event_classes.each do |event_class|
+              next unless event_class.slo_enabled?
+
+              config = event_class.slo_config
+              name = event_class.respond_to?(:event_name) ? event_class.event_name : event_class.name
+
+              errors << "Event #{name} has slo enabled but missing slo_status_from" unless config&.slo_status_proc
+
+              errors << "Event #{name} has slo enabled but missing contributes_to" unless config&.contributes_to_value
+            end
+
+            return if errors.empty?
+
+            raise LinterError, errors.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/logger/bridge.rb

@@ -8,7 +8,7 @@ module E11y
     #
     # Transparent wrapper around Rails.logger that:
     # 1. Delegates all calls to the original logger (preserves Rails behavior)
-    # 2. Tracks log calls as E11y events (when logger_bridge.enabled = true)
+    # 2. Tracks log calls as E11y events (when logger_bridge_enabled = true)
     #
     # **Why SimpleDelegator instead of full replacement:**
     # - ✅ Simpler: No need to reimplement entire Logger API
@@ -17,12 +17,12 @@ module E11y
     # - ✅ Rails Way: Extends functionality without replacing core components
     #
     # @example Basic usage
-    #   # Automatically enabled by E11y::Railtie if config.logger_bridge.enabled = true
+    #   # Automatically enabled by E11y::Railtie if config.logger_bridge_enabled = true
     #   Rails.logger = E11y::Logger::Bridge.new(Rails.logger)
     #
     # @example Manual setup
     #   E11y.configure do |config|
-    #     config.logger_bridge.enabled = true  # Wrap Rails.logger and send logs to E11y
+    #     config.logger_bridge_enabled = true  # Wrap Rails.logger and send logs to E11y
     #   end
     #
     # @see ADR-008 §7 (Rails.logger Migration)
@@ -34,7 +34,7 @@ module E11y
       #
       # @return [void]
       def self.setup!
-        return unless E11y.config.logger_bridge&.enabled
+        return unless E11y.config.logger_bridge_enabled
         return unless defined?(::Rails)
 
         # Wrap Rails.logger (preserves original behavior)
@@ -53,6 +53,8 @@ module E11y
           ::Logger::FATAL => :fatal,
           ::Logger::UNKNOWN => :warn
         }
+        @track_severities_set = build_track_severities_set(E11y.config.logger_bridge_track_severities)
+        @ignore_patterns = build_compiled_patterns(E11y.config.logger_bridge_ignore_patterns)
       end
 
       # Intercept logger methods to track to E11y
@@ -124,18 +126,22 @@ module E11y
       # @param message [String, nil] Log message
       # @yield Block that returns log message
       # @return [void]
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       # Logger tracking requires message extraction, validation, event class lookup, and error handling
       def track_to_e11y(severity, message = nil)
         # Extract message
         msg = message || (block_given? ? yield : nil)
         return if msg.nil? || (msg.respond_to?(:empty?) && msg.empty?)
 
+        msg_str = msg.to_s
+
+        return if @track_severities_set && !@track_severities_set.include?(severity)
+        return if @ignore_patterns.any? { |re| re.match?(msg_str) }
+
         # Track to E11y using severity-specific class
         require "e11y/events/rails/log"
         event_class = event_class_for_severity(severity)
         event_class.track(
-          message: msg.to_s,
+          message: msg_str,
           caller_location: extract_caller_location
         )
       rescue StandardError => e
@@ -143,7 +149,6 @@ module E11y
         # In development/test, you might want to log this
         warn "E11y logger tracking failed: #{e.message}" if defined?(::Rails) && ::Rails.env.development?
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Get event class for severity
       # @param severity [Symbol] E11y severity
@@ -162,6 +167,20 @@ module E11y
       end
       # rubocop:enable Lint/DuplicateBranch
 
+      def build_track_severities_set(severities)
+        return nil if severities.nil? || (severities.respond_to?(:empty?) && severities.empty?)
+
+        Set.new(Array(severities).map(&:to_sym))
+      end
+
+      def build_compiled_patterns(patterns)
+        return [] if patterns.nil? || !patterns.respond_to?(:any?) || patterns.none?
+
+        Array(patterns).map do |p|
+          p.is_a?(Regexp) ? p : Regexp.new(Regexp.escape(p.to_s))
+        end.freeze
+      end
+
       # Extract caller location (first caller outside E11y)
       # @return [String, nil] Caller location string
       def extract_caller_location

data/lib/e11y/metrics/cardinality_protection.rb

@@ -7,11 +7,10 @@ module E11y
   module Metrics
     # Cardinality protection for metrics labels.
     #
-    # Implements 4-layer defense system to prevent cardinality explosions:
+    # Implements 3-layer defense system to prevent cardinality explosions:
     # 1. Universal Denylist - Block high-cardinality fields (user_id, order_id, etc.)
     # 2. Per-Metric Limits - Track unique values per metric, drop if exceeded
-    # 3. Dynamic Monitoring - Alert when approaching limits
-    # 4. Dynamic Actions - Auto-relabeling, alerting, or dropping on overflow
+    # 3. Dynamic Actions - Drop, alert, or relabel on overflow
     #
     # Now supports optional relabeling to reduce cardinality while preserving signal.
     #
@@ -37,7 +36,7 @@ module E11y
     # @see ADR-002 §4 (Cardinality Protection)
     # @see UC-013 (High Cardinality Protection)
     # rubocop:disable Metrics/ClassLength
-    # Cardinality protection is a cohesive 4-layer defense system against metric explosions
+    # Cardinality protection is a cohesive 3-layer defense system against metric explosions
     class CardinalityProtection
       # Universal denylist - high-cardinality fields that should NEVER be labels
       UNIVERSAL_DENYLIST = %i[
@@ -64,7 +63,7 @@ module E11y
       # Default per-metric cardinality limit
       DEFAULT_CARDINALITY_LIMIT = 1000
 
-      # Overflow strategies (Layer 4: Dynamic Actions)
+      # Overflow strategies (Layer 3: Dynamic Actions)
       OVERFLOW_STRATEGIES = %i[drop alert relabel].freeze
 
       # Default overflow strategy
@@ -85,7 +84,6 @@ module E11y
       # @option config [Float] :alert_threshold (0.8) Alert when cardinality reaches this ratio
       # @option config [Proc] :alert_callback Optional callback when alert triggered
       # @option config [Boolean] :auto_relabel (false) Auto-relabel to [OTHER] on overflow
-      # rubocop:disable Metrics/AbcSize
       # Cardinality protection initialization requires extracting multiple config options and setting up components
       def initialize(config = {})
         @cardinality_limit = config.fetch(:cardinality_limit, DEFAULT_CARDINALITY_LIMIT)
@@ -109,7 +107,6 @@ module E11y
         @overflow_counts = Hash.new(0)
         @overflow_mutex = Mutex.new
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Define relabeling rule for a label
       #
@@ -222,7 +219,6 @@ module E11y
 
       # Check if approaching alert threshold (Layer 3: Monitoring)
       # @param metric_name [String] Metric name
-      # rubocop:disable Metrics/MethodLength
       # Alert threshold checking requires calculating ratio, checking conditions, and sending detailed alerts
       def check_alert_threshold(metric_name)
         return unless @alert_threshold
@@ -252,7 +248,6 @@ module E11y
         # Track metric
         track_cardinality_metric(metric_name, :threshold_exceeded, current_cardinality)
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Handle overflow when cardinality limit exceeded (Layer 4: Dynamic Actions)
       # @param metric_name [String] Metric name
@@ -311,9 +306,11 @@ module E11y
           severity: :error
         )
 
-        # Also log warning
-        warn "E11y Metrics: Cardinality limit exceeded for #{metric_name}:#{key} " \
-             "(limit: #{@cardinality_limit}, current: #{current_cardinality})"
+        # Also log warning (via E11y.logger so it respects Rails.logger in test env)
+        E11y.logger&.warn(
+          "E11y Metrics: Cardinality limit exceeded for #{metric_name}:#{key} " \
+          "(limit: #{@cardinality_limit}, current: #{current_cardinality})"
+        )
       end
 
       # Handle relabel strategy - relabel to [OTHER]
@@ -385,7 +382,6 @@ module E11y
       # @param metric_name [String] Metric name
       # @param action [Symbol] Action type (:threshold_exceeded, :drop, :alert, :relabel)
       # @param value [Integer] Metric value
-      # rubocop:disable Metrics/MethodLength
       # Cardinality tracking requires incrementing overflow counters and updating gauge metrics
       def track_cardinality_metric(metric_name, action, value)
         return unless defined?(E11y::Metrics)
@@ -408,9 +404,8 @@ module E11y
         )
       rescue StandardError => e
         # Don't fail on metrics tracking errors
-        warn "E11y: Failed to track cardinality metric: #{e.message}"
+        E11y.logger&.warn("E11y: Failed to track cardinality metric: #{e.message}")
       end
-      # rubocop:enable Metrics/MethodLength
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/e11y/metrics/cardinality_tracker.rb

@@ -33,13 +33,15 @@ module E11y
       # Records unique label values per metric+label combination.
       # Thread-safe operation.
       #
-      # @param metric_name [String] Metric name
+      # @param metric_name [String, Symbol] Metric name
       # @param label_key [Symbol, String] Label key
       # @param label_value [Object] Label value to track
       # @return [Boolean] true if within limit, false if limit exceeded
       def track(metric_name, label_key, label_value)
         @mutex.synchronize do
-          value_set = @tracker[metric_name][label_key]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          value_set = @tracker[metric_key][label_key]
 
           # Allow if already tracked (existing value)
           return true if value_set.include?(label_value)
@@ -66,7 +68,9 @@ module E11y
       # @return [void]
       def force_track(metric_name, label_key, label_value)
         @mutex.synchronize do
-          value_set = @tracker[metric_name][label_key]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          value_set = @tracker[metric_key][label_key]
           value_set.add(label_value) unless value_set.include?(label_value)
         end
       end
@@ -78,7 +82,9 @@ module E11y
       # @return [Boolean] true if at or above limit
       def exceeded?(metric_name, label_key)
         @mutex.synchronize do
-          @tracker.dig(metric_name, label_key)&.size.to_i >= @limit
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          @tracker.dig(metric_key, label_key)&.size.to_i >= @limit
         end
       end
 
@@ -89,7 +95,9 @@ module E11y
       # @return [Integer] Number of unique values tracked
       def cardinality(metric_name, label_key)
         @mutex.synchronize do
-          @tracker.dig(metric_name, label_key)&.size || 0
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          @tracker.dig(metric_key, label_key)&.size || 0
         end
       end
 
@@ -99,7 +107,9 @@ module E11y
       # @return [Hash{Symbol => Integer}] Label key => cardinality
       def cardinalities(metric_name)
         @mutex.synchronize do
-          metric_data = @tracker[metric_name]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          metric_data = @tracker[metric_key]
           metric_data.transform_values(&:size)
         end
       end

data/lib/e11y/metrics/registry.rb

@@ -6,7 +6,7 @@ module E11y
   module Metrics
     # Registry for metric configurations.
     #
-    # Stores metric definitions and provides pattern-based matching.
+    # Stores metric definitions and provides event-name matching.
     # This is a singleton class - use Registry.instance to access it.
     # All metrics (global, event-level, preset) are registered here for validation.
     #
@@ -144,7 +144,6 @@ module E11y
       # Validate metric configuration
       # @param config [Hash] Metric configuration
       # @raise [ArgumentError] if configuration is invalid
-      # rubocop:disable Metrics/AbcSize
       def validate_config!(config)
         raise ArgumentError, "Metric type is required" unless config[:type]
         raise ArgumentError, "Invalid metric type: #{config[:type]}" unless %i[counter histogram
@@ -156,14 +155,13 @@ module E11y
 
         raise ArgumentError, "Value extractor is required for #{config[:type]} metrics"
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Validate that new metric doesn't conflict with existing one
       # @param existing [Hash] Existing metric configuration
       # @param new_config [Hash] New metric configuration
       # @raise [TypeConflictError] if types don't match
       # @raise [LabelConflictError] if labels don't match
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       # Conflict validation requires checking type and labels with detailed error messages
       def validate_no_conflicts!(existing, new_config)
         # Check 1: Type must match
@@ -215,7 +213,7 @@ module E11y
           Using existing buckets.
         WARNING
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Compile glob pattern to regex
       # @param pattern [String] Glob pattern (e.g., "order.*", "user.*.created")

data/lib/e11y/metrics/test_backend.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module E11y
+  module Metrics
+    # In-memory metrics backend for tests.
+    #
+    # Records all metric calls so test assertions can verify what was tracked
+    # without using mocks on E11y::Metrics directly.
+    #
+    # @example
+    #   backend = E11y::Metrics::TestBackend.new
+    #   E11y::Metrics.instance_variable_set(:@backend, backend)
+    #
+    #   MyService.call
+    #
+    #   expect(backend.increment_count(:orders_total)).to eq(1)
+    #   expect(backend.increments).to include(hash_including(name: :orders_total))
+    class TestBackend
+      attr_reader :increments, :histograms, :gauges
+
+      def initialize
+        reset!
+      end
+
+      # @param name [Symbol] Metric name
+      # @param labels [Hash] Metric labels
+      # @param value [Integer] Increment amount
+      def increment(name, labels = {}, value: 1)
+        @increments << { name: name, labels: labels, value: value }
+      end
+
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Observed value
+      # @param labels [Hash] Metric labels
+      def histogram(name, value, labels = {}, buckets: nil) # rubocop:todo Lint/UnusedMethodArgument
+        @histograms << { name: name, value: value, labels: labels }
+      end
+
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Gauge value
+      # @param labels [Hash] Metric labels
+      def gauge(name, value, labels = {})
+        @gauges << { name: name, value: value, labels: labels }
+      end
+
+      # Reset all recorded metrics.
+      def reset!
+        @increments = []
+        @histograms = []
+        @gauges     = []
+      end
+
+      # Count how many times a counter was incremented (any labels).
+      #
+      # @param name [Symbol] Metric name
+      # @return [Integer]
+      def increment_count(name)
+        @increments.count { |r| r[:name] == name }
+      end
+    end
+  end
+end

data/lib/e11y/metrics.rb

@@ -21,18 +21,41 @@ module E11y
   # @see ADR-002 §3 (Metrics Integration)
   # @see ADR-016 §3 (Self-Monitoring Metrics)
   module Metrics
+    # No-op metrics backend used when no real backend (e.g. Yabeda) is configured.
+    # Accepts all metric calls and silently discards them so callers never
+    # need to guard against a nil backend.
+    class NullBackend
+      def increment(_name, _labels = {}, value: 1); end
+      def histogram(_name, _value, _labels = {}, buckets: nil); end
+      def gauge(_name, _value, _labels = {}); end
+    end
+
     class << self
       # Track a counter metric (monotonically increasing value).
       #
-      # @param name [Symbol] Metric name (e.g., :http_requests_total)
+      # Accepts dotted names (e.g., "e11y.ephemeral_buffer.flushed") and normalizes to
+      # underscores. DLQ metrics get _total suffix. Labels[:events] is used as value if present.
+      # Safe: no-op when backend unavailable, rescues errors.
+      #
+      # @param name [Symbol, String] Metric name (e.g., :http_requests_total or "e11y.ephemeral_buffer.flushed")
       # @param labels [Hash] Metric labels (e.g., { method: 'GET', status: 200 })
-      # @param value [Integer] Increment value (default: 1)
+      # @param value [Integer] Increment value (default: 1, overridden by labels[:events] if present)
       # @return [void]
       #
       # @example
-      #   E11y::Metrics.increment(:e11y_events_tracked, { event_type: 'order.created' })
-      def increment(name, labels = {}, value: 1)
-        backend&.increment(name, labels, value: value)
+      #   E11y::Metrics.increment(:e11y_events_tracked, event_type: 'order.created')
+      #   E11y::Metrics.increment("e11y.ephemeral_buffer.flushed_on_error", value: 5)
+      def increment(name, labels = {}, value: 1, **labels_kw)
+        return unless backend
+
+        labels = labels.merge(labels_kw) unless labels_kw.empty?
+        value = labels.delete(:events) if labels.key?(:events)
+        value ||= 1
+
+        normalized = normalized_metric_name(name)
+        backend.increment(normalized, labels, value: value)
+      rescue StandardError => e
+        E11y.logger&.debug("E11y metrics: #{e.message}")
       end
 
       # Track a histogram metric (distribution of values).
@@ -44,9 +67,15 @@ module E11y
       # @return [void]
       #
       # @example
-      #   E11y::Metrics.histogram(:e11y_track_duration_seconds, 0.0005, { event_type: 'order.created' })
-      def histogram(name, value, labels = {}, buckets: nil)
-        backend&.histogram(name, value, labels, buckets: buckets)
+      #   E11y::Metrics.histogram(:e11y_track_duration_seconds, 0.0005, event_type: 'order.created')
+      def histogram(name, value, labels = {}, buckets: nil, **labels_kw)
+        return unless backend
+
+        labels = labels.merge(labels_kw) unless labels_kw.empty?
+        normalized = normalized_metric_name(name)
+        backend.histogram(normalized, value, labels, buckets: buckets)
+      rescue StandardError => e
+        E11y.logger&.debug("E11y metrics: #{e.message}")
       end
 
       # Track a gauge metric (current value that can go up or down).
@@ -81,10 +110,27 @@ module E11y
       # @api private
       def reset_backend!
         remove_instance_variable(:@backend) if defined?(@backend)
+        @name_cache = nil if defined?(@name_cache)
       end
 
       private
 
+      # Normalize metric name: dots to underscores, DLQ metrics get _total suffix.
+      # Cached to avoid repeated string allocations for hot-path metrics.
+      #
+      # @param name [Symbol, String] Raw metric name
+      # @return [Symbol] Normalized name for Prometheus (e.g., e11y_ephemeral_buffer_flushed_on_error)
+      def normalized_metric_name(name)
+        @name_cache ||= {}
+        @name_cache[name] ||= compute_normalized_name(name)
+      end
+
+      def compute_normalized_name(name)
+        s = name.to_s.tr(".", "_")
+        s = "#{s}_total" if s.include?("e11y_dlq_") && !s.end_with?("_total")
+        s.to_sym
+      end
+
       # Detect the metrics backend from configured adapters.
       #
       # @return [Object, nil] Metrics backend or nil
@@ -99,8 +145,8 @@ module E11y
         # rubocop:enable Style/ClassEqualityComparison
         return yabeda_adapter if yabeda_adapter
 
-        # No backend configured → noop
-        nil
+        # No Yabeda adapter configured — fall back to NullBackend
+        NullBackend.new
       end
     end
   end

data/lib/e11y/middleware/adapter_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Resolves target adapter names for an event (shared by PIIFilter and Routing).
+    #
+    # @api private
+    module AdapterResolver
+      # Resolve target adapters for event_data (explicit or routing rules).
+      #
+      # @param event_data [Hash] Event data with :adapters, :audit_event, :retention_until, etc.
+      # @return [Array<Symbol>] Target adapter names
+      def self.resolve(event_data)
+        if event_data[:adapters]&.any?
+          Array(event_data[:adapters]).map(&:to_sym)
+        else
+          apply_routing_rules(event_data)
+        end
+      end
+
+      def self.apply_routing_rules(event_data)
+        matched_adapters = []
+        rules = E11y.configuration.routing_rules || []
+
+        rules.each do |rule|
+          result = rule.call(event_data)
+          matched_adapters.concat(Array(result)) if result
+        rescue StandardError => e
+          warn "[E11y] Routing rule error: #{e.message}"
+        end
+
+        if matched_adapters.any?
+          matched_adapters.uniq
+        else
+          E11y.configuration.fallback_adapters || [:stdout]
+        end
+      end
+    end
+  end
+end