e11y 0.2.0 → 1.1.0

data/docs/{ADR-008-rails-integration.md → architecture/ADR-008-rails-integration.md}

@@ -184,164 +184,17 @@ sequenceDiagram
 
 ## 3. Railtie & Initialization
 
-### 3.1. Railtie Implementation
+### 3.1. Railtie implementation
 
-```ruby
-# lib/e11y/railtie.rb
-module E11y
-  class Railtie < Rails::Railtie
-    # Run before framework initialization
-    config.before_initialize do
-      # Set up basic configuration
-      E11y.configure do |config|
-        config.environment = Rails.env
-        config.service_name = Rails.application.class.module_parent_name.underscore
-      end
-    end
-    
-    # Run after framework initialization
-    config.after_initialize do
-      next unless E11y.config.enabled
-      
-      # Setup instruments (each can be enabled/disabled separately)
-      if E11y.config.instruments.active_support_notifications.enabled
-        E11y::Instruments::ActiveSupportNotifications.setup!
-      end
-      
-      if E11y.config.instruments.sidekiq.enabled
-        E11y::Instruments::Sidekiq.setup!
-      end
-      
-      if E11y.config.instruments.active_job.enabled
-        E11y::Instruments::ActiveJob.setup!
-      end
-      
-      if E11y.config.instruments.rack_middleware.enabled
-        E11y::Instruments::RackMiddleware.setup!
-      end
-      
-      # Setup logger bridge
-      E11y::Logger::Bridge.setup! if E11y.config.logger_bridge.enabled
-      
-      # Setup development tools
-      E11y::Console.setup! if Rails.env.development?
-    end
-    
-    # Middleware insertion
-    initializer 'e11y.middleware' do |app|
-      app.middleware.insert_before(
-        Rails::Rack::Logger,
-        E11y::Middleware::Request
-      )
-    end
-    
-    # ActiveSupport::Notifications subscribers
-    initializer 'e11y.notifications' do
-      ActiveSupport::Notifications.subscribe(/.*/) do |name, start, finish, id, payload|
-        E11y::Instruments::NotificationSubscriber.handle(
-          name: name,
-          started_at: start,
-          finished_at: finish,
-          transaction_id: id,
-          payload: payload
-        )
-      end
-    end
-    
-    # Sidekiq integration
-    initializer 'e11y.sidekiq' do
-      if defined?(Sidekiq)
-        require 'e11y/instruments/sidekiq'
-        
-        Sidekiq.configure_server do |config|
-          config.server_middleware do |chain|
-            chain.add E11y::Instruments::Sidekiq::ServerMiddleware
-          end
-        end
-        
-        Sidekiq.configure_client do |config|
-          config.client_middleware do |chain|
-            chain.add E11y::Instruments::Sidekiq::ClientMiddleware
-          end
-        end
-      end
-    end
-    
-    # ActiveJob integration
-    initializer 'e11y.active_job' do
-      ActiveSupport.on_load(:active_job) do
-        require 'e11y/instruments/active_job'
-        
-        include E11y::Instruments::ActiveJob::Callbacks
-      end
-    end
-    
-    # Console helpers
-    console do
-      E11y::Console.enable!
-      
-      puts "E11y loaded. Try: E11y.stats"
-    end
-    
-    # Rake task helpers
-    rake_tasks do
-      load 'e11y/tasks.rake'
-    end
-  end
-end
-```
+**Source of truth:** `lib/e11y/railtie.rb` (read the file in the repo; do not paste stale excerpts).
 
-### 3.2. Configuration Loading
+Shipped behavior in short: `before_initialize` sets `environment`, `service_name`, and default `enabled`; after `load_config_initializers`, `e11y.setup_instrumentation` wires Rails instrumentation, optional logger bridge, and optional Sidekiq / Active Job when the corresponding **boolean** flags are set; `e11y.middleware` inserts `E11y::Middleware::Request`; development/test may register the DevLog adapter and `DevLogSource` middleware; optional `e11y.http_tracing` patches Net::HTTP; console loads `E11y::Console`; Rake tasks load the `lib/e11y/tasks/*.rake` files.
 
-```ruby
-# lib/e11y/configuration/rails.rb
-module E11y
-  module Configuration
-    class Rails < Base
-      def initialize
-        super
-        
-        # Rails-specific defaults
-        @environment = ::Rails.env
-        @service_name = derive_service_name
-        @enabled = !::Rails.env.test?  # Disabled in tests by default
-        
-        # Auto-detect adapters
-        @adapters = auto_detect_adapters
-        
-        # Rails logger bridge
-        @logger_bridge = LoggerBridgeConfig.new
-      end
-      
-      private
-      
-      def derive_service_name
-        ::Rails.application.class.module_parent_name.underscore
-      rescue
-        'rails_app'
-      end
-      
-      def auto_detect_adapters
-        adapters = []
-        
-        # Always include stdout in development
-        adapters << :stdout if ::Rails.env.development?
-        
-        # Auto-detect file logging
-        adapters << :file if ::Rails.root.join('log').directory?
-        
-        # Auto-detect Sentry
-        adapters << :sentry if defined?(Sentry)
-        
-        # Auto-detect Loki
-        adapters << :loki if ENV['LOKI_URL'].present?
-        
-        adapters
-      end
-    end
-  end
-end
-```
+Older drafts of this ADR showed extra initializers (e.g. a global `ActiveSupport::Notifications.subscribe(/.*/)`, unconditional Sidekiq registration, `lib/e11y/configuration/rails.rb`, `LoggerBridgeConfig` as a nested type). **Those are not in the codebase.**
+
+### 3.2. Configuration
+
+All tunables live on **`E11y::Configuration`** in `lib/e11y/configuration.rb`. There is no separate `E11y::Configuration::Rails` class.
 
 ---
 
@@ -400,7 +253,7 @@ module E11y
       # ========================================
       
       def self.setup!
-        return unless E11y.config.instruments.rails_instrumentation.enabled
+        return unless E11y.config.rails_instrumentation_enabled
         
         # Subscribe to Rails events
         event_mapping.each do |asn_pattern, e11y_event_class|
@@ -421,19 +274,20 @@ module E11y
       
       # Built-in event mappings (can be overridden in config!)
       DEFAULT_RAILS_EVENT_MAPPING = {
-        'sql.active_record' => Events::Rails::Database::Query,
-        'process_action.action_controller' => Events::Rails::Http::Request,
-        'render_template.action_view' => Events::Rails::View::Render,
-        'send_file.action_controller' => Events::Rails::Http::SendFile,
-        'redirect_to.action_controller' => Events::Rails::Http::Redirect,
-        'start_processing.action_controller' => Events::Rails::Http::StartProcessing,
-        'cache_read.active_support' => Events::Rails::Cache::Read,
-        'cache_write.active_support' => Events::Rails::Cache::Write,
-        'cache_delete.active_support' => Events::Rails::Cache::Delete,
-        'enqueue.active_job' => Events::Rails::Job::Enqueued,
-        'enqueue_at.active_job' => Events::Rails::Job::Scheduled,
-        'perform_start.active_job' => Events::Rails::Job::Started,
-        'perform.active_job' => Events::Rails::Job::Completed
+        'sql.active_record' => E11y::Events::Rails::Database::Query,
+        'process_action.action_controller' => E11y::Events::Rails::Http::Request,
+        'render_template.action_view' => E11y::Events::Rails::View::Render,
+        'send_file.action_controller' => E11y::Events::Rails::Http::SendFile,
+        'redirect_to.action_controller' => E11y::Events::Rails::Http::Redirect,
+        'start_processing.action_controller' => E11y::Events::Rails::Http::StartProcessing,
+        'cache_read.active_support' => E11y::Events::Rails::Cache::Read,
+        'cache_write.active_support' => E11y::Events::Rails::Cache::Write,
+        'cache_delete.active_support' => E11y::Events::Rails::Cache::Delete,
+        'enqueue.active_job' => E11y::Events::Rails::Job::Enqueued,
+        'enqueue_at.active_job' => E11y::Events::Rails::Job::Scheduled,
+        'perform_start.active_job' => E11y::Events::Rails::Job::Started,
+        # perform.active_job: Completed on success; Failed when payload has exception
+        'perform.active_job' => E11y::Events::Rails::Job::Completed
       }.freeze
       
       # Get final event mapping (after config overrides)
@@ -442,7 +296,7 @@ module E11y
           mapping = DEFAULT_RAILS_EVENT_MAPPING.dup
           
           # Apply custom mappings from config (Devise-style overrides)
-          custom_mappings = E11y.config.instruments.rails_instrumentation.custom_mappings || {}
+          custom_mappings = E11y.config.rails_instrumentation_custom_mappings || {}
           mapping.merge!(custom_mappings)
           
           mapping
@@ -450,7 +304,7 @@ module E11y
       end
       
       def self.ignored?(pattern)
-        ignore_list = E11y.config.instruments.rails_instrumentation.ignore_events || []
+        ignore_list = E11y.config.rails_instrumentation_ignore_events || []
         ignore_list.include?(pattern)
       end
       
@@ -464,81 +318,32 @@ module E11y
 end
 ```
 
-### 4.2. Configuration: Overridable Event Classes (Devise-Style)
+### 4.2. Configuration (Rails integration)
 
-**Design Decision (Updated 2026-01-17):** Built-in event classes can be overridden in config (Devise-style pattern).
+**As implemented:** flags and hashes on `E11y::Configuration` (`lib/e11y/configuration.rb`). There is **no** nested `config.rails_instrumentation do`, `config.sidekiq do`, or `config.active_job do` DSL—those snippets were design sketches and must not be copied into apps.
 
-**Rationale:**
-- ✅ **Flexibility**: Custom schema, PII rules, adapters per event type
-- ✅ **Familiar pattern**: Developers know Devise controller overrides
-- ✅ **Opt-in**: Defaults work for 90% of cases, override only when needed
-- ✅ **No monkey-patching**: Clean override mechanism
+**Rails → E11y:** enable `rails_instrumentation_enabled`, optionally set `rails_instrumentation_custom_mappings` (String ASN pattern → event class) and `rails_instrumentation_ignore_events` (Array of patterns to skip). Instrumentation is wired in `E11y::Instruments::RailsInstrumentation` and invoked from `E11y::Railtie`.
+
+**Jobs:** `sidekiq_enabled` and `active_job_enabled` are booleans. **Logger bridge:** `logger_bridge_enabled`, `logger_bridge_track_severities`, `logger_bridge_ignore_patterns`.
 
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments do
-    # ========================================
-    # Rails Instrumentation (ActiveSupport::Notifications → E11y)
-    # ========================================
-    rails_instrumentation do
-      # Enable/disable entire ASN integration
-      enabled true  # Set to false to completely disable
-      
-      # Built-in event classes (auto-created by E11y)
-      # Located in Events::Rails namespace
-      use_built_in_events true  # If false, no auto-mapping
-      
-      # ========================================
-      # OVERRIDE EVENT CLASSES (Devise-style)
-      # ========================================
-      
-      # Override default event class for specific ASN pattern
-      event_class_for 'sql.active_record', MyApp::Events::CustomDatabaseQuery
-      event_class_for 'process_action.action_controller', MyApp::Events::CustomHttpRequest
-      
-      # Disable specific events (too noisy or not needed)
-      ignore_event 'cache_read.active_support'
-      ignore_event 'render_partial.action_view'
-      ignore_event 'SCHEMA'  # Schema queries
-      
-      # ========================================
-      # SELECTIVE INSTRUMENTATION
-      # ========================================
-      
-      # Which Rails events to track (glob patterns)
-      track_patterns [
-        'sql.active_record',
-        'process_action.action_controller',
-        'render_template.action_view',
-        'cache_*.active_support'
-      ]
-      
-      # Sampling for high-volume events
-      sample_patterns do
-        pattern 'sql.active_record', sample_rate: 0.1  # 10% of SQL queries
-        pattern 'cache_read.active_support', sample_rate: 0.01  # 1% of cache reads
-      end
-      
-      # Enrich with custom data
-      enrich do |asn_event|
-        {
-          controller: asn_event.payload[:controller],
-          action: asn_event.payload[:action],
-          format: asn_event.payload[:format],
-          user_id: Current.user&.id  # Add context
-        }
-      end
-    end
-    
-    # (Other integrations: Sidekiq, ActiveJob, etc.)
-  end
+  config.rails_instrumentation_enabled = true
+
+  config.rails_instrumentation_custom_mappings["sql.active_record"] =
+    MyApp::Events::CustomDatabaseQuery
+  config.rails_instrumentation_ignore_events << "cache_read.active_support"
+
+  config.sidekiq_enabled = true
+  config.active_job_enabled = true
+  config.ephemeral_buffer_enabled = true
 end
 ```
 
 ### 4.2.1. Custom Event Class Example
 
-**Use Case:** Override default `Events::Rails::Database::Query` with custom schema and PII rules.
+**Use Case:** Override default `E11y::Events::Rails::Database::Query` with custom schema and PII rules.
 
 ```ruby
 # app/events/custom_database_query.rb
@@ -580,153 +385,11 @@ end
 
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments.rails_instrumentation do
-    # Override default event class
-    event_class_for 'sql.active_record', MyApp::Events::CustomDatabaseQuery
-  end
+  config.rails_instrumentation_custom_mappings["sql.active_record"] =
+    MyApp::Events::CustomDatabaseQuery
 end
 
-# Now all sql.active_record events will use CustomDatabaseQuery!
-```
-
-### 4.2.2. Implementation (Configuration DSL)
-
-```ruby
-# lib/e11y/configuration/rails_instrumentation.rb
-module E11y
-  module Configuration
-    class RailsInstrumentation
-      attr_accessor :enabled, :use_built_in_events
-      
-      def initialize
-        @enabled = true
-        @use_built_in_events = true
-        @custom_event_classes = {}
-        @ignored_events = []
-        @track_patterns = []
-        @sample_patterns = {}
-        @enrich_block = nil
-      end
-      
-      # Override event class (Devise-style)
-      def event_class_for(asn_pattern, custom_event_class)
-        unless custom_event_class < E11y::Event::Base
-          raise ArgumentError, "#{custom_event_class} must inherit from E11y::Event::Base"
-        end
-        
-        @custom_event_classes[asn_pattern] = custom_event_class
-      end
-      
-      # Disable specific event
-      def ignore_event(asn_pattern)
-        @ignored_events << asn_pattern
-      end
-      
-      # Track only specific patterns
-      def track_patterns(*patterns)
-        @track_patterns = patterns.flatten
-      end
-      
-      # Sampling configuration
-      def sample_patterns(&block)
-        @sample_patterns_builder ||= SamplePatternsBuilder.new
-        @sample_patterns_builder.instance_eval(&block) if block_given?
-        @sample_patterns_builder
-      end
-      
-      # Enrich ASN events before conversion
-      def enrich(&block)
-        @enrich_block = block
-      end
-      
-      # Get final event mapping (after overrides)
-      def event_mapping
-        mapping = E11y::Instruments::RailsInstrumentation::DEFAULT_RAILS_EVENT_MAPPING.dup
-        mapping.merge!(@custom_event_classes)
-        mapping.except(*@ignored_events)
-      end
-      
-      # Check if event should be tracked
-      def track?(asn_pattern)
-        return false if @ignored_events.include?(asn_pattern)
-        return true if @track_patterns.empty?
-        
-        @track_patterns.any? do |pattern|
-          File.fnmatch(pattern, asn_pattern)
-        end
-      end
-    end
-  end
-end
-```
-    
-    # ========================================
-    # Sidekiq
-    # ========================================
-    sidekiq do
-      enabled true  # Set to false to disable Sidekiq integration
-      
-      # Server middleware (job execution)
-      server_middleware do
-        enabled true
-        track_start true
-        track_complete true
-        track_failure true
-      end
-      
-      # Client middleware (job enqueuing)
-      client_middleware do
-        enabled true
-        track_enqueue true
-      end
-      
-      # Trace propagation
-      propagate_trace_context true
-      trace_context_keys ['e11y_trace_id', 'e11y_span_id', 'e11y_sampled']
-    end
-    
-    # ========================================
-    # ActiveJob
-    # ========================================
-    active_job do
-      enabled true  # Set to false to disable ActiveJob integration
-      
-      track_enqueue true
-      track_start true
-      track_complete true
-      track_failure true
-      
-      # Trace propagation
-      propagate_trace_context true
-      
-      # Job-scoped buffer (like request-scoped buffer for HTTP)
-      use_job_buffer true
-      
-      job_buffer do
-        buffer_severities [:debug]
-        flush_on do
-          error true       # Flush debug events if job fails
-          success false    # Discard debug events if job succeeds
-        end
-        max_events 1000
-      end
-    end
-    
-    # ========================================
-    # Rack Middleware
-    # ========================================
-    rack_middleware do
-      enabled true  # Set to false to disable Rack middleware
-      
-      track_request_start true
-      track_request_complete true
-      track_request_failure true
-      
-      # Request-scoped buffer
-      use_request_buffer true
-    end
-  end
-end
+# Now sql.active_record uses CustomDatabaseQuery (see RailsInstrumentation.event_mapping).
 ```
 
 **Example: Disable specific instruments:**
@@ -734,19 +397,16 @@ end
 ```ruby
 # Disable ASN but keep Sidekiq
 E11y.configure do |config|
-  config.instruments.active_support_notifications.enabled = false
-  config.instruments.sidekiq.enabled = true
-  config.instruments.active_job.enabled = true
+  config.rails_instrumentation_enabled = false
+  config.sidekiq_enabled = true
+  config.active_job_enabled = true
 end
 
 # Minimal setup: only Sidekiq
 E11y.configure do |config|
-  config.instruments do
-    active_support_notifications { enabled false }
-    sidekiq { enabled true }
-    active_job { enabled false }
-    rack_middleware { enabled false }
-  end
+  config.rails_instrumentation_enabled = false
+  config.sidekiq_enabled = true
+  config.active_job_enabled = false
 end
 ```
 
@@ -756,7 +416,7 @@ end
 
 **Design Decision:** E11y provides built-in event classes for standard Rails events.
 
-**Location:** `Events::Rails` namespace (auto-loaded by gem)
+**Location:** `E11y::Events::Rails` namespace (auto-loaded by gem)
 
 ```ruby
 # app/events/rails/ (provided by E11y gem)
@@ -855,28 +515,14 @@ module Events
 end
 ```
 
-**User can override:**
-
-```ruby
-# config/initializers/e11y.rb
-E11y.configure do |config|
-  config.instruments.active_support_notifications do
-    # Disable built-in events
-    use_built_in_events false
-    
-    # Use custom events instead
-    custom_mappings do
-      map 'sql.active_record', to: MyApp::Events::DatabaseQuery
-      map 'process_action.action_controller', to: MyApp::Events::HttpRequest
-    end
-  end
-end
-```
+**User can override** built-in ASN → event class mappings with `rails_instrumentation_custom_mappings` and skip patterns with `rails_instrumentation_ignore_events` (see §4.2).
 
 ---
 
 ## 5. Sidekiq Integration
 
+**Implementation Note:** Sidekiq middleware emits `E11y::Events::Rails::Job::Enqueued`, `Started`, `Completed`, `Failed` for **raw Sidekiq jobs only** (`include Sidekiq::Worker`). When Sidekiq is the queue adapter for ActiveJob, jobs use `ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper`; we skip event emission in Sidekiq middleware to avoid double emission — ActiveJob events come from RailsInstrumentation (ASN).
+
 ### 5.1. Server Middleware (Job Execution)
 
 ```ruby
@@ -886,26 +532,29 @@ module E11y
     module Sidekiq
       class ServerMiddleware
         def call(worker, job, queue)
-          # Extract trace context from job metadata
-          trace_id = job['e11y_trace_id'] || E11y::TraceContext.generate_id
+          # C17 Hybrid: Job gets NEW trace_id, parent_trace_id links to enqueuing request
+          parent_trace_id = job['e11y_parent_trace_id']
+          trace_id = E11y::TraceContext.generate_id  # NEW trace per job
           parent_span_id = job['e11y_span_id']
           
-          # Restore trace context
           E11y::Current.set(
             trace_id: trace_id,
+            parent_trace_id: parent_trace_id,
             parent_span_id: parent_span_id,
             job_id: job['jid'],
             job_class: worker.class.name,
             queue: queue
           )
           
-          # Start job-scoped buffer (optional, configurable)
-          if E11y.config.instruments.sidekiq.use_job_buffer
-            E11y::JobBuffer.start!
+          # Start request-scoped buffer (same as HTTP; config.ephemeral_buffer_enabled)
+          if E11y.config.ephemeral_buffer_enabled
+            limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                    E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+            E11y::Buffers::EphemeralBuffer.initialize!(buffer_limit: limit)
           end
           
           # Track job start
-          Events::Rails::Job::Started.track(
+          E11y::Events::Rails::Job::Started.track(
             job_class: worker.class.name,
             job_id: job['jid'],
             queue: queue,
@@ -919,20 +568,20 @@ module E11y
             result = yield
             
             # Track job success
-            Events::Rails::Job::Completed.track(
+            E11y::Events::Rails::Job::Completed.track(
               job_class: worker.class.name,
               job_id: job['jid'],
               duration: (Time.now - start_time) * 1000,
               queue: queue
             )
             
-            # Flush job buffer (success case)
-            E11y::JobBuffer.flush! if E11y.config.instruments.sidekiq.use_job_buffer
+            # Discard buffer on success (same as HTTP)
+            E11y::Buffers::EphemeralBuffer.discard if E11y.config.ephemeral_buffer_enabled
             
             result
           rescue => error
             # Track job failure
-            Events::Rails::Job::Failed.track(
+            E11y::Events::Rails::Job::Failed.track(
               job_class: worker.class.name,
               job_id: job['jid'],
               duration: (Time.now - start_time) * 1000,
@@ -942,8 +591,8 @@ module E11y
               backtrace: error.backtrace&.first(10)
             )
             
-            # Flush job buffer on error (includes debug events)
-            E11y::JobBuffer.flush_on_error! if E11y.config.instruments.sidekiq.use_job_buffer
+            # Flush buffer on error (includes debug events)
+            E11y::Buffers::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer_enabled
             
             raise
           ensure
@@ -976,13 +625,13 @@ module E11y
     module Sidekiq
       class ClientMiddleware
         def call(worker_class, job, queue, redis_pool)
-          # Propagate trace context to job
-          job['e11y_trace_id'] = E11y::Current.trace_id
+          # C17 Hybrid: Propagate parent trace (job will create NEW trace_id)
+          job['e11y_parent_trace_id'] = E11y::Current.trace_id if E11y::Current.trace_id
           job['e11y_span_id'] = E11y::TraceContext.generate_span_id
           job['e11y_sampled'] = E11y::Current.sampled  # Trace-consistent sampling
           
           # Track job enqueued
-          Events::Rails::Job::Enqueued.track(
+          E11y::Events::Rails::Job::Enqueued.track(
             job_class: worker_class.to_s,
             job_id: job['jid'],
             queue: queue,
@@ -997,89 +646,22 @@ module E11y
 end
 ```
 
-### 5.3. Job-Scoped Buffer (Optional Feature)
+### 5.3. Buffer for Jobs
 
-**Design Decision:** Similar to request-scoped buffer, jobs can have their own buffer for debug events.
+**Design Decision:** Jobs reuse the same `EphemeralBuffer` as HTTP requests. Same semantics: buffer debug events, flush on error, discard on success. Optional job-specific config allows tuning for longer-running jobs.
 
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments.sidekiq do
-    # Enable job-scoped buffer (like request-scoped buffer)
-    use_job_buffer true
-    
-    job_buffer do
-      # Buffer debug events during job execution
-      buffer_severities [:debug]
-      
-      # Flush conditions
-      flush_on do
-        error true           # Flush debug events if job fails
-        success false        # Discard debug events if job succeeds
-        interval 5.seconds   # Or flush every 5 seconds
-      end
-      
-      # Max buffer size per job
-      max_events 1000
-    end
-  end
-end
-```
-
-**How it works:**
-
-```ruby
-class InvoiceGenerationWorker
-  include Sidekiq::Worker
+  # Shared buffer for HTTP and jobs
+  config.ephemeral_buffer_enabled = true
   
-  def perform(order_id)
-    # Debug events are buffered
-    Events::Debug::FetchOrder.track(order_id: order_id)
-    
-    order = Order.find(order_id)
-    
-    Events::Debug::ValidateOrder.track(order_id: order_id, valid: order.valid?)
-    
-    if order.invalid?
-      # Job fails → debug events are flushed to adapters
-      raise "Invalid order"
-    end
-    
-    # Job succeeds → debug events are discarded
-    Events::InvoiceGenerated.track(order_id: order_id)
-  end
+  # Optional: job-specific overrides (jobs can run longer → more debug events)
+  config.ephemeral_buffer_job_buffer_limit = 500  # nil = use default (100)
 end
 ```
 
-**Job Buffer Lifecycle:**
-
-```mermaid
-sequenceDiagram
-    participant Worker as Sidekiq Worker
-    participant JobBuffer as Job Buffer
-    participant MainBuffer as Main Buffer
-    participant Adapters as Adapters
-    
-    Worker->>JobBuffer: Start job buffer
-    
-    Note over Worker: Job execution starts
-    
-    Worker->>JobBuffer: Track debug event
-    JobBuffer->>JobBuffer: Buffer (not flushed)
-    
-    Worker->>MainBuffer: Track info event
-    MainBuffer->>Adapters: Flush immediately (normal flow)
-    
-    alt Job succeeds
-        Worker->>JobBuffer: flush! (success)
-        JobBuffer->>JobBuffer: Discard debug events
-        Note over JobBuffer: Debug events never sent
-    else Job fails
-        Worker->>JobBuffer: flush_on_error!
-        JobBuffer->>MainBuffer: Move debug events to main buffer
-        MainBuffer->>Adapters: Flush all events (including debug)
-    end
-```
+**Rationale:** Single buffer implementation, single config. Jobs may need higher `job_buffer_limit` when they process many items and emit more debug events than a typical HTTP request.
 
 ---
 
@@ -1100,21 +682,21 @@ sequenceDiagram
     ClientMW->>ClientMW: Extract trace_id from Current
     ClientMW->>Redis: Store job + trace metadata
     
-    Note over Redis: job['e11y_trace_id'] = 'abc123'<br/>job['e11y_span_id'] = 'span002'<br/>job['e11y_sampled'] = true
+    Note over Redis: job['e11y_parent_trace_id'] = 'abc123'<br/>job['e11y_span_id'] = 'span002'<br/>job['e11y_sampled'] = true
     
     ClientMW->>E11y: Track Enqueued event
     
     Note over ServerMW: Later... job dequeued
     
     Redis->>ServerMW: Fetch job
-    ServerMW->>ServerMW: Extract trace_id from job
+    ServerMW->>ServerMW: C17: new trace_id, parent_trace_id from job
     ServerMW->>E11y: Restore Current context
     
-    Note over E11y: Current.trace_id = 'abc123'<br/>Current.parent_span_id = 'span002'
+    Note over E11y: Current.trace_id = NEW<br/>Current.parent_trace_id = 'abc123'<br/>Current.parent_span_id = 'span002'
     
     ServerMW->>E11y: Track Started event
     ServerMW->>Worker: perform
-    Worker->>E11y: Track custom events (same trace_id!)
+    Worker->>E11y: Track events (linked via parent_trace_id!)
     ServerMW->>E11y: Track Completed event
 ```
 
@@ -1122,6 +704,13 @@ sequenceDiagram
 
 ## 6. ActiveJob Integration
 
+**Implementation Note:** Job lifecycle events (`Enqueued`, `Started`, `Completed`, `Failed`) come from **RailsInstrumentation** (ASN), not from ActiveJob callbacks. ActiveJob callbacks handle trace context propagation, request-scoped buffer, and SLO tracking only. This design:
+- Uses ASN as single source for all queue adapters (Sidekiq, Resque, Solid Queue, etc.)
+- Avoids duplicate emission when ActiveJob uses Sidekiq as adapter
+- Keeps callbacks focused on context/buffer/SLO
+
+**perform.active_job routing:** When payload contains `exception`, RailsInstrumentation routes to `E11y::Events::Rails::Job::Failed` (with `error_class`, `error_message`); otherwise to `Completed`.
+
 ### 6.1. Callbacks Integration
 
 ```ruby
@@ -1140,23 +729,27 @@ module E11y
         private
         
         def e11y_track_job_execution
-          # Extract trace context
-          trace_id = job_metadata['e11y_trace_id'] || E11y::TraceContext.generate_id
+          # C17 Hybrid: Job gets NEW trace_id, parent_trace_id links to enqueuer
+          parent_trace_id = job_metadata['e11y_parent_trace_id']
+          trace_id = E11y::TraceContext.generate_id
           parent_span_id = job_metadata['e11y_span_id']
           
           E11y::Current.set(
             trace_id: trace_id,
+            parent_trace_id: parent_trace_id,
             parent_span_id: parent_span_id,
             job_id: job_id,
             job_class: self.class.name
           )
           
-          # Start job-scoped buffer (optional, configurable)
-          if E11y.config.instruments.active_job.use_job_buffer
-            E11y::JobBuffer.start!
+          # Start request-scoped buffer (same as HTTP; config.ephemeral_buffer_enabled)
+          if E11y.config.ephemeral_buffer_enabled
+            limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                    E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+            E11y::Buffers::EphemeralBuffer.initialize!(buffer_limit: limit)
           end
           
-          Events::Rails::Job::Started.track(
+          E11y::Events::Rails::Job::Started.track(
             job_class: self.class.name,
             job_id: job_id,
             queue_name: queue_name,
@@ -1168,16 +761,16 @@ module E11y
           begin
             yield
             
-            Events::Rails::Job::Completed.track(
+            E11y::Events::Rails::Job::Completed.track(
               job_class: self.class.name,
               job_id: job_id,
               duration: (Time.now - start_time) * 1000
             )
             
-            # Flush job buffer (success case)
-            E11y::JobBuffer.flush! if E11y.config.instruments.active_job.use_job_buffer
+            # Discard buffer on success (same as HTTP)
+            E11y::Buffers::EphemeralBuffer.discard if E11y.config.ephemeral_buffer_enabled
           rescue => error
-            Events::Rails::Job::Failed.track(
+            E11y::Events::Rails::Job::Failed.track(
               job_class: self.class.name,
               job_id: job_id,
               duration: (Time.now - start_time) * 1000,
@@ -1185,8 +778,8 @@ module E11y
               error_message: error.message
             )
             
-            # Flush job buffer on error (includes debug events)
-            E11y::JobBuffer.flush_on_error! if E11y.config.instruments.active_job.use_job_buffer
+            # Flush buffer on error (includes debug events)
+            E11y::Buffers::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer_enabled
             
             raise
           ensure
@@ -1195,12 +788,12 @@ module E11y
         end
         
         def e11y_track_job_enqueued
-          # Store trace context in job metadata
-          job_metadata['e11y_trace_id'] = E11y::Current.trace_id
+          # C17 Hybrid: Store parent trace (job will create NEW trace_id)
+          job_metadata['e11y_parent_trace_id'] = E11y::Current.trace_id if E11y::Current.trace_id
           job_metadata['e11y_span_id'] = E11y::TraceContext.generate_span_id
           job_metadata['e11y_sampled'] = E11y::Current.sampled
           
-          Events::Rails::Job::Enqueued.track(
+          E11y::Events::Rails::Job::Enqueued.track(
             job_class: self.class.name,
             job_id: job_id,
             queue_name: queue_name,
@@ -1235,7 +828,7 @@ module E11y
   module Logger
     class Bridge
       def self.setup!
-        return unless E11y.config.logger_bridge.enabled
+        return unless E11y.config.logger_bridge_enabled
         
         # Replace Rails.logger
         Rails.logger = Bridge.new(Rails.logger)
@@ -1304,17 +897,10 @@ module E11y
         # Extract message
         msg = message || (block_given? ? block.call : nil)
         
-        # Track via E11y
-        Events::RailsLogger.track(
-          severity: severity,
-          message: msg.to_s,
-          caller_location: extract_caller_location
-        )
+        # Track via E11y (filtered by track_severities, ignore_patterns)
+        event_class_for_severity(severity).track(message: msg.to_s, caller_location: extract_caller_location)
         
-        # Also log to original logger (dual logging)
-        if @original_logger && E11y.config.logger_bridge.dual_logging
-          @original_logger.public_send(severity, msg)
-        end
+        # Always delegate to original logger (SimpleDelegator super)
       end
       
       def extract_caller_location
@@ -1330,50 +916,39 @@ module E11y
 end
 ```
 
-### 7.2. Migration Strategy
+### 7.2. Configuration
 
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.logger_bridge do
-    enabled true
-    
-    # Dual logging (E11y + original Rails.logger)
-    dual_logging true  # Keep writing to log/production.log
-    
-    # Which severities to track
-    track_severities [:info, :warn, :error, :fatal]
-    
-    # Skip noisy log messages
-    ignore_patterns [
-      /Started GET/,
-      /Completed \d+ OK/,
-      /CACHE/
-    ]
-    
-    # Sample high-volume logs
-    sample_rate 0.1  # 10% of logs
-    
-    # Enrich with Rails context
-    enrich_with_context true
-    context_fields [:controller, :action, :request_id]
-  end
+  config.logger_bridge_enabled = true
+  
+  # Which severities to track (nil = all)
+  config.logger_bridge_track_severities = [:info, :warn, :error, :fatal]
+  
+  # Skip noisy log messages (regex or string)
+  config.logger_bridge_ignore_patterns = [
+    /Started GET/,
+    /Completed \d+ OK/,
+    /CACHE/
+  ]
 end
 ```
 
+**Context:** Events are enriched with `trace_id`, `request_id`, `span_id`, `user_id` from `E11y::Current` via `Event::Base.build_context` — no separate config needed.
+
 ---
 
 ## 8. Middleware Integration
 
-### 8.0. Three Buffer Types (Summary)
+### 8.0. Buffer Types (Summary)
 
-**E11y has 3 independent buffer types:**
+**E11y uses a single EphemeralBuffer for both HTTP and jobs:**
 
-| Buffer Type | Purpose | Lifecycle | Use Case |
-|-------------|---------|-----------|----------|
-| **Main Buffer** | All events (info+) | Global, flush every 200ms | Normal event tracking |
-| **Request Buffer** | Debug events in HTTP requests | Per-request, flush on error | HTTP request debugging |
-| **Job Buffer** | Debug events in background jobs | Per-job, flush on error | Background job debugging |
+| Buffer | Purpose | Lifecycle | Config |
+|--------|---------|-----------|--------|
+| **Request Buffer** | Debug events (HTTP + jobs) | Per-request/job, flush on error, discard on success | `config.ephemeral_buffer_enabled`, `ephemeral_buffer_job_buffer_limit` |
+| **Main Buffer** | All events (info+) | Global, flush every 200ms | — |
 
 **Diagram:**
 
@@ -1381,20 +956,20 @@ end
 graph TB
     subgraph "HTTP Request"
         HTTPEvent[Event tracked] --> Decision1{Severity?}
-        Decision1 -->|:debug| RequestBuffer[Request Buffer]
+        Decision1 -->|:debug| [Request Buffer]
         Decision1 -->|:info+| MainBuffer[Main Buffer]
         
-        RequestBuffer --> OnError1{Request failed?}
+         --> OnError1{Request failed?}
         OnError1 -->|Yes| MainBuffer
         OnError1 -->|No| Discard1[Discard]
     end
     
     subgraph "Background Job"
         JobEvent[Event tracked] --> Decision2{Severity?}
-        Decision2 -->|:debug| JobBuffer[Job Buffer]
+        Decision2 -->|:debug| 
         Decision2 -->|:info+| MainBuffer2[Main Buffer]
         
-        JobBuffer --> OnError2{Job failed?}
+         --> OnError2{Job failed?}
         OnError2 -->|Yes| MainBuffer2
         OnError2 -->|No| Discard2[Discard]
     end
@@ -1405,8 +980,7 @@ graph TB
         Interval --> Adapters[Flush to Adapters]
     end
     
-    style RequestBuffer fill:#fff3cd
-    style JobBuffer fill:#d4edda
+    style  fill:#fff3cd
     style MainBuffer fill:#d1ecf1
     style MainBuffer2 fill:#d1ecf1
 ```
@@ -1415,134 +989,17 @@ graph TB
 
 ```ruby
 E11y.configure do |config|
-  # Main buffer (always enabled)
-  config.buffer.flush_interval = 200.milliseconds
-  config.buffer.max_size = 10_000
-  
-  # Request-scoped buffer (HTTP only)
-  config.instruments.rack_middleware.use_request_buffer = true
-  
-  # Job-scoped buffer (Sidekiq + ActiveJob)
-  config.instruments.sidekiq.use_job_buffer = true
-  config.instruments.active_job.use_job_buffer = true
+  # Request-scoped buffer (shared for HTTP and jobs)
+  config.ephemeral_buffer_enabled = true
+  config.ephemeral_buffer_job_buffer_limit = 500  # Optional: higher limit for jobs (nil = default 100)
 end
 ```
 
 ---
 
-### 8.1. Request Middleware
+### 8.1. Request middleware
 
-```ruby
-# lib/e11y/middleware/request.rb
-module E11y
-  module Middleware
-    class Request
-      def initialize(app)
-        @app = app
-      end
-      
-      def call(env)
-        request = Rack::Request.new(env)
-        
-        # Extract or generate trace_id
-        trace_id = extract_trace_id(request) || TraceContext.generate_id
-        span_id = TraceContext.generate_span_id
-        
-        # Set context
-        Current.set(
-          trace_id: trace_id,
-          span_id: span_id,
-          request_id: request_id(env),
-          user_id: extract_user_id(env),
-          ip_address: request.ip,
-          user_agent: request.user_agent
-        )
-        
-        # Start request-scoped buffer (for debug events)
-        # Note: This is ONLY for HTTP requests, not for jobs
-        # Jobs have their own JobBuffer (see Sidekiq/ActiveJob sections)
-        if E11y.config.instruments.rack_middleware.use_request_buffer
-          E11y::RequestBuffer.start!
-        end
-        
-        # Track request start
-        start_time = Time.now
-        
-        Events::Http::RequestStarted.track(
-          method: request.request_method,
-          path: request.path,
-          query: request.query_string,
-          format: request.format
-        )
-        
-        begin
-          status, headers, body = @app.call(env)
-          
-          # Track request completed
-          Events::Http::RequestCompleted.track(
-            method: request.request_method,
-            path: request.path,
-            status: status,
-            duration: (Time.now - start_time) * 1000
-          )
-          
-          # Add trace headers to response
-          headers['X-E11y-Trace-Id'] = trace_id
-          headers['X-E11y-Span-Id'] = span_id
-          
-          [status, headers, body]
-        rescue => error
-          # Track request failed
-          Events::Http::RequestFailed.track(
-            method: request.request_method,
-            path: request.path,
-            duration: (Time.now - start_time) * 1000,
-            error_class: error.class.name,
-            error_message: error.message
-          )
-          
-          # Flush request buffer (includes debug events on error)
-          if E11y.config.instruments.rack_middleware.use_request_buffer
-            E11y::RequestBuffer.flush_on_error!
-          end
-          
-          raise
-        ensure
-          # Flush request buffer (success case)
-          if E11y.config.instruments.rack_middleware.use_request_buffer && !error
-            E11y::RequestBuffer.flush!
-          end
-          
-          # Reset context
-          Current.reset
-        end
-      end
-      
-      private
-      
-      def extract_trace_id(request)
-        # W3C Trace Context
-        request.get_header('HTTP_TRACEPARENT')&.split('-')&.[](1) ||
-        # X-Request-ID
-        request.get_header('HTTP_X_REQUEST_ID') ||
-        # X-Trace-Id
-        request.get_header('HTTP_X_TRACE_ID')
-      end
-      
-      def request_id(env)
-        env['action_dispatch.request_id'] || SecureRandom.uuid
-      end
-      
-      def extract_user_id(env)
-        # Try to extract from Warden (Devise)
-        env['warden']&.user&.id ||
-        # Try to extract from session
-        env['rack.session']&.[]('user_id')
-      end
-    end
-  end
-end
-```
+**Source of truth:** `lib/e11y/middleware/request.rb`. Earlier ADR excerpts used `Current.set`, non-existent `Events::Http::*` events, and a simplified error path—the real middleware wires W3C / fallback trace IDs, `E11y::Current`, optional `E11y::Buffers::EphemeralBuffer`, response status–based buffer flush, optional HTTP SLO tracking, and response headers.
 
 ---
 
@@ -1563,10 +1020,10 @@ module E11y
       # E11y.stats
       def E11y.stats
         {
-          events_tracked: Registry.all_events.sum { |e| e.track_count },
+          events_tracked: Registry.event_classes.sum { |e| e.track_count },
           events_in_buffer: Buffer.size,
-          adapters: Adapters::Registry.all.map { |a| 
-            { name: a.name, healthy: a.healthy? }
+          adapters: config.adapters.map { |name, a|
+            { name: name, healthy: a.respond_to?(:healthy?) ? a.healthy? : true }
           },
           rate_limiter: {
             current_rate: RateLimiter.current_rate,
@@ -1588,17 +1045,17 @@ module E11y
       
       # E11y.events
       def E11y.events
-        Registry.all_events.map(&:name).sort
+        Registry.event_classes.map(&:name).sort
       end
       
       # E11y.adapters
       def E11y.adapters
-        Adapters::Registry.all.map do |adapter|
+        config.adapters.map do |name, adapter|
           {
-            name: adapter.name,
+            name: name,
             class: adapter.class.name,
-            healthy: adapter.healthy?,
-            capabilities: adapter.capabilities
+            healthy: adapter.respond_to?(:healthy?) ? adapter.healthy? : true,
+            capabilities: adapter.respond_to?(:capabilities) ? adapter.capabilities : {}
           }
         end
       end
@@ -1606,7 +1063,7 @@ module E11y
       # E11y.reset!
       def E11y.reset!
         Buffer.clear!
-        RequestBuffer.clear!
+        .clear!
         puts "✅ Buffers cleared"
       end
     end
@@ -1621,7 +1078,7 @@ module E11y
         )
         
         # Disable rate limiting in console
-        config.rate_limiting.enabled = false
+        config.rate_limiting_enabled = false
         
         # Show all severities
         config.severity_threshold = :debug
@@ -1772,7 +1229,7 @@ RSpec.describe OrdersController, type: :controller do
       }.to have_enqueued_job(SendOrderEmailJob)
       
       job = ActiveJob::Base.queue_adapter.enqueued_jobs.last
-      expect(job[:args].first['e11y_trace_id']).to be_present
+      expect(job[:args].first['e11y_parent_trace_id']).to be_present
     end
   end
 end
@@ -1819,90 +1276,72 @@ end
 
 ```ruby
 E11y.configure do |config|
-  config.instruments.active_support_notifications.enabled = false  # Disable ASN
-  config.instruments.sidekiq.enabled = true                       # Keep Sidekiq
-  config.instruments.active_job.enabled = true                    # Keep ActiveJob
-  config.instruments.rack_middleware.enabled = true               # Keep HTTP tracking
+  config.rails_instrumentation_enabled = false  # Disable ASN
+  config.sidekiq_enabled = true                # Keep Sidekiq
+  config.active_job_enabled = true              # Keep ActiveJob
+  config.logger_bridge_enabled = true          # Keep logger bridge
 end
 ```
 
 ### Q2: Do you provide built-in event classes for Rails?
 
-**Yes!** E11y includes `Events::Rails` namespace with common Rails events:
+**Yes!** E11y includes the `E11y::Events::Rails` namespace with common Rails events:
 
-- `Events::Rails::Database::Query` (sql.active_record)
-- `Events::Rails::Http::Request` (process_action.action_controller)
-- `Events::Rails::Cache::Read/Write/Delete`
-- `Events::Rails::Job::Enqueued/Started/Completed/Failed`
+- `E11y::Events::Rails::Database::Query` (sql.active_record)
+- `E11y::Events::Rails::Http::Request` (process_action.action_controller)
+- `E11y::Events::Rails::Cache::Read/Write/Delete`
+- `E11y::Events::Rails::Job::Enqueued/Started/Completed/Failed`
 
 **You can:**
 - Use them as-is (default)
-- Override them with `custom_mappings`
-- Disable them with `use_built_in_events false`
+- Override selected patterns via `config.rails_instrumentation_custom_mappings`
+- Skip patterns via `config.rails_instrumentation_ignore_events`
+- Turn the whole subscriber off with `config.rails_instrumentation_enabled = false`
 
 ### Q3: Is ActiveSupport::Notifications integration always on?
 
-**No!** It's configurable:
+**No.** Toggle `rails_instrumentation_enabled`. Ignore individual ASN names by appending to `rails_instrumentation_ignore_events` (exact string match to the subscription key, e.g. `"render_template.action_view"`).
 
 ```ruby
-config.instruments.active_support_notifications do
-  enabled false  # Completely disable ASN integration
+E11y.configure do |config|
+  config.rails_instrumentation_enabled = false
 end
-```
 
-You can also filter which ASN events to track:
-
-```ruby
-config.instruments.active_support_notifications do
-  track_patterns ['sql.active_record', 'process_action.*']
-  ignore_patterns ['render_partial.*', 'SCHEMA']
+E11y.configure do |config|
+  config.rails_instrumentation_ignore_events << "render_template.action_view"
 end
 ```
 
 ### Q4: Does request-scoped buffer work for Sidekiq/ActiveJob?
 
-**No, they have their own job-scoped buffer!**
+**Yes. HTTP and jobs share the same EphemeralBuffer.**
 
-- **Request Buffer** → HTTP requests only (Rack middleware)
-- **Job Buffer** → Sidekiq + ActiveJob (separate buffer per job)
+- **Request Buffer** → HTTP requests and jobs (same buffer, same semantics)
 - **Main Buffer** → Global buffer for all info+ events
 
-All 3 buffers are independent and configurable:
+Config:
 
 ```ruby
-config.instruments.rack_middleware.use_request_buffer = true   # HTTP
-config.instruments.sidekiq.use_job_buffer = true              # Sidekiq
-config.instruments.active_job.use_job_buffer = true           # ActiveJob
+config.ephemeral_buffer_enabled = true
+config.ephemeral_buffer_job_buffer_limit = 500  # Optional: higher limit for jobs (nil = default 100)
 ```
 
 ### Q5: How do I customize built-in Rails events?
 
-**Option A: Override with custom event class:**
+**Override one mapping:**
 
 ```ruby
-config.instruments.active_support_notifications do
-  custom_mappings do
-    map 'sql.active_record', to: MyApp::Events::CustomDatabaseQuery
-  end
+E11y.configure do |config|
+  config.rails_instrumentation_custom_mappings["sql.active_record"] =
+    MyApp::Events::CustomDatabaseQuery
 end
 ```
 
-**Option B: Disable built-in events entirely:**
-
-```ruby
-config.instruments.active_support_notifications do
-  use_built_in_events false  # No automatic mapping
-  
-  # Manually handle ASN events
-  enrich do |asn_event|
-    MyCustomHandler.call(asn_event)
-  end
-end
-```
+**Disable automatic ASN → E11y conversion:** set `rails_instrumentation_enabled = false` and subscribe to `ActiveSupport::Notifications` yourself if you need a custom pipeline.
 
 ### Q6: Can I use E11y without Rails?
 
-**No.** E11y requires Rails 8.0+ and Ruby 3.3+. For non-Rails apps, consider other telemetry solutions.
+The supported path is **Rails 7.0+** (see gemspec). Non-Rails usage is not a supported integration surface today.
 
 ---