e11y 0.2.0 → 1.1.0

data/docs/{ADR-004-adapter-architecture.md → architecture/ADR-004-adapter-architecture.md}

@@ -12,7 +12,7 @@
 - ✅ §4.3: Loki Adapter - Implemented (34 tests)
 - ✅ §4.4: Sentry Adapter - Implemented (39 tests)
 - ❌ §4.5: Elasticsearch Adapter - Cancelled (not needed now)
-- ✅ §5: Adapter Registry - Implemented (26 tests)
+- ✅ §5: Adapter storage (config.adapters)
 - ✅ §9.1: InMemory Test Adapter - Implemented (51 tests)
 - ✅ AuditEncrypted Adapter - Updated to new contract (13 tests)
 
@@ -31,7 +31,7 @@
    - 4.3. [Loki Adapter](#43-loki-adapter)
    - 4.4. [Sentry Adapter](#44-sentry-adapter)
    - 4.5. [Elasticsearch Adapter](#45-elasticsearch-adapter)
-5. [Adapter Registry](#5-adapter-registry)
+5. [Adapter Storage (config.adapters)](#5-adapter-storage-configadapters)
 6. [Connection Management](#6-connection-management)
 7. [Error Handling & Retry](#7-error-handling--retry)
 8. [Performance & Batching](#8-performance--batching)
@@ -1064,17 +1064,17 @@ end
 
 ---
 
-## 5. Adapter Registry
+## 5. Adapter Storage (config.adapters)
 
-### 5.1. Registry Architecture
+### 5.1. Architecture
 
 ```mermaid
 graph TB
     subgraph "Configuration Phase (Boot Time)"
-        Config[Configuration] --> Register[Registry.register]
-        Register --> Instance1[Loki Instance]
-        Register --> Instance2[Sentry Instance]
-        Register --> Instance3[File Instance]
+        Config[Configuration] --> Adapters[config.adapters]
+        Adapters --> Instance1[Loki Instance]
+        Adapters --> Instance2[Sentry Instance]
+        Adapters --> Instance3[File Instance]
         
         Instance1 --> Pool1[Connection Pool]
         Instance2 --> Pool2[Connection Pool]
@@ -1082,79 +1082,33 @@ graph TB
     end
     
     subgraph "Runtime Phase"
-        Event[Event.track] --> Resolve[Registry.resolve]
+        Event[Event.track] --> Resolve[config.adapters[name]]
         Resolve -->|:loki| Instance1
         Resolve -->|:sentry| Instance2
         Resolve -->|:file| Instance3
     end
     
-    style Register fill:#d1ecf1
+    style Adapters fill:#d1ecf1
     style Resolve fill:#fff3cd
     style Pool1 fill:#d4edda
     style Pool2 fill:#d4edda
     style Pool3 fill:#d4edda
 ```
 
-### 5.2. Registry Implementation
+### 5.2. config.adapters (Adapter Storage)
+
+Adapters are stored in `E11y.configuration.adapters` (Hash). Routing middleware resolves by name: `config.adapters[adapter_name]`.
 
 ```ruby
-module E11y
-  module Adapters
-    class Registry
-      class << self
-        def register(name, adapter_instance)
-          validate_adapter!(adapter_instance)
-          
-          adapters[name] = adapter_instance
-          
-          # Register cleanup hook
-          at_exit { adapter_instance.close }
-        end
-        
-        def resolve(name)
-          adapters.fetch(name) do
-            raise AdapterNotFoundError, "Adapter not found: #{name}"
-          end
-        end
-        
-        def resolve_all(names)
-          names.map { |name| resolve(name) }
-        end
-        
-        def all
-          adapters.values
-        end
-        
-        def names
-          adapters.keys
-        end
-        
-        def clear!
-          adapters.each_value(&:close)
-          adapters.clear
-        end
-        
-        private
-        
-        def adapters
-          @adapters ||= {}
-        end
-        
-        def validate_adapter!(adapter)
-          unless adapter.respond_to?(:write)
-            raise ArgumentError, "Adapter must respond to #write"
-          end
-          
-          unless adapter.respond_to?(:write_batch)
-            raise ArgumentError, "Adapter must respond to #write_batch"
-          end
-        end
-      end
-    end
-    
-    class AdapterNotFoundError < StandardError; end
-  end
+# Registration (config phase)
+E11y.configure do |config|
+  config.adapters[:loki] = E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
+  config.adapters[:sentry] = E11y::Adapters::Sentry.new(dsn: ENV["SENTRY_DSN"])
 end
+
+# Resolution (runtime, in Routing middleware)
+adapter = E11y.configuration.adapters[:loki]
+adapter.write(event_data)
 ```
 
 ### 5.3. Usage in Events
@@ -1714,20 +1668,20 @@ E11y.configure do |config|
   # Register adapters (infrastructure)
   config.register_adapter :loki, Loki.new(url: ENV['LOKI_URL'])
   config.register_adapter :sentry, Sentry.new(dsn: ENV['SENTRY_DSN'])
-  config.register_adapter :s3, S3Adapter.new(bucket: 'events-archive')
+  # Archival: external jobs filter by retention_until
   config.register_adapter :audit_encrypted, AuditAdapter.new(...)
   
   # ❌ PROBLEM: Routing for EVERY event in global config
   config.events do
     # Payment events → multiple adapters
     event 'Events::PaymentSucceeded' do
-      adapters [:loki, :sentry, :s3]
+      adapters [:loki, :sentry]
     end
     event 'Events::PaymentFailed' do
-      adapters [:loki, :sentry, :s3]
+      adapters [:loki, :sentry]
     end
     event 'Events::PaymentRefunded' do
-      adapters [:loki, :sentry, :s3]
+      adapters [:loki, :sentry]
     end
     
     # Audit events → encrypted adapter
@@ -1764,7 +1718,7 @@ E11y.configure do |config|
   # ONLY infrastructure (adapter registration)
   config.register_adapter :loki, Loki.new(url: ENV['LOKI_URL'])
   config.register_adapter :sentry, Sentry.new(dsn: ENV['SENTRY_DSN'])
-  config.register_adapter :s3, S3Adapter.new(bucket: 'events-archive')
+  # Archival: external jobs filter by retention_until
   config.register_adapter :audit_encrypted, AuditAdapter.new(...)
   
   # Optional: default adapters (convention)
@@ -1777,7 +1731,7 @@ module Events
     schema do; required(:transaction_id).filled(:string); end
     
     # ✅ Adapters right next to schema!
-    adapters [:loki, :sentry, :s3]
+    adapters [:loki, :sentry]
   end
 end
 
@@ -1817,7 +1771,7 @@ end
 module Events
   class BasePaymentEvent < E11y::Event::Base
     # Common adapters for ALL payment events
-    adapters [:loki, :sentry, :s3]
+    adapters [:loki, :sentry]
     
     # Common config
     severity :success
@@ -1829,18 +1783,18 @@ end
 # Inherit from base (1-2 lines per event!)
 class Events::PaymentSucceeded < Events::BasePaymentEvent
   schema do; required(:transaction_id).filled(:string); end
-  # ← Inherits: adapters [:loki, :sentry, :s3]
+  # ← Inherits: adapters [:loki, :sentry]
 end
 
 class Events::PaymentFailed < Events::BasePaymentEvent
   severity :error  # ← Override severity
   schema do; required(:error_code).filled(:string); end
-  # ← Inherits: adapters [:loki, :sentry, :s3]
+  # ← Inherits: adapters [:loki, :sentry]
 end
 
 class Events::PaymentRefunded < Events::BasePaymentEvent
   schema do; required(:refund_id).filled(:string); end
-  # ← Inherits: adapters [:loki, :sentry, :s3]
+  # ← Inherits: adapters [:loki, :sentry]
 end
 ```
 
@@ -1882,7 +1836,7 @@ module E11y
     module HighValueEvent
       extend ActiveSupport::Concern
       included do
-        adapters [:loki, :sentry, :s3_archive]
+        adapters [:loki, :sentry]
         sample_rate 1.0
         retention 7.years
       end
@@ -1936,7 +1890,7 @@ end
 # Override convention:
 class Events::OrderCreated < E11y::Event::Base
   severity :success
-  adapters [:loki, :elasticsearch, :s3]  # ← Override
+  adapters [:loki, :elasticsearch]  # ← Override
   schema do; required(:order_id).filled(:string); end
 end
 ```
@@ -1946,13 +1900,13 @@ end
 ```ruby
 # Replace strategy (default): Override parent/convention
 class Events::PaymentSucceeded < Events::BasePaymentEvent
-  adapters [:loki, :sentry]  # ← Replaces base [:loki, :sentry, :s3]
+  adapters [:loki, :sentry]  # ← Replaces base
 end
 
 # Append strategy: Add to parent/convention
 class Events::PaymentSucceeded < Events::BasePaymentEvent
   adapters_strategy :append
-  adapters [:slack_business]  # ← Adds to base (result: [:loki, :sentry, :s3, :slack_business])
+  adapters [:slack_business]  # ← Adds to base (result: [:loki, :sentry, :slack_business])
 end
 ```
 
@@ -1976,7 +1930,7 @@ class Events::BasePaymentEvent < E11y::Event::Base
 end
 
 class Events::PaymentSucceeded < Events::BasePaymentEvent
-  include E11y::Presets::HighValueEvent  # 2. Preset (adds :s3)
+  include E11y::Presets::HighValueEvent  # 2. Preset
   adapters [:loki, :sentry, :pagerduty]  # 1. Event-level (WINS!)
 end
 
@@ -2009,7 +1963,7 @@ end
 ```ruby
 # Migrate high-value events first:
 class Events::PaymentSucceeded < E11y::Event::Base
-  adapters [:loki, :sentry, :s3]  # ← Migrated
+  adapters [:loki, :sentry]  # ← Migrated
 end
 
 # Keep others in global config (temporary):
@@ -2124,7 +2078,7 @@ class Events::PaymentFailed < E11y::Event::Base
   
   # Multi-environment routing
   adapters case Rails.env
-           when 'production' then [:loki, :sentry, :s3_archive]
+           when 'production' then [:loki, :sentry]
            when 'staging' then [:loki, :sentry]
            else [:file]
            end
@@ -2164,7 +2118,7 @@ end
 module E11y::Presets::HighValueEvent
   extend ActiveSupport::Concern
   included do
-    adapters [:loki, :sentry, :s3_archive]  # Add S3
+    adapters [:loki, :sentry]
   end
 end
 
@@ -2172,9 +2126,9 @@ end
 class Events::CriticalPayment < Events::BasePaymentEvent
   include E11y::Presets::HighValueEvent
   
-  adapters [:loki, :sentry, :s3_archive, :datadog]  # Add Datadog
+  adapters [:loki, :sentry, :datadog]
   
-  # Final: [:loki, :sentry, :s3_archive, :datadog] (event-level wins)
+  # Final: [:loki, :sentry, :datadog] (event-level wins)
 end
 ```
 
@@ -2189,64 +2143,40 @@ end
 require 'e11y'
 
 E11y.configure do |config|
-  # Register Loki for centralized logging
-  E11y::Adapters::Registry.register(
-    :loki,
-    E11y::Adapters::Loki.new(
-      url: ENV['LOKI_URL'] || 'http://loki:3100',
-      labels: {
-        app: 'my_app',
-        env: Rails.env,
-        host: Socket.gethostname
-      },
-      batch_size: 100,
-      batch_timeout: 5,
-      compress: true,
-      tenant_id: ENV['LOKI_TENANT_ID']
-    )
+  # Loki for centralized logging
+  config.adapters[:loki] = E11y::Adapters::Loki.new(
+    url: ENV['LOKI_URL'] || 'http://loki:3100',
+    labels: { app: 'my_app', env: Rails.env, host: Socket.gethostname },
+    batch_size: 100,
+    batch_timeout: 5,
+    compress: true,
+    tenant_id: ENV['LOKI_TENANT_ID']
   )
 
-  # Register Sentry for error tracking
-  E11y::Adapters::Registry.register(
-    :sentry,
-    E11y::Adapters::Sentry.new(
-      dsn: ENV['SENTRY_DSN'],
-      environment: Rails.env,
-      severity_threshold: :warn,
-      breadcrumbs: true
-    )
+  # Sentry for error tracking
+  config.adapters[:sentry] = E11y::Adapters::Sentry.new(
+    dsn: ENV['SENTRY_DSN'],
+    environment: Rails.env,
+    severity_threshold: :warn,
+    breadcrumbs: true
   )
 
-  # Register File adapter for local development
-  E11y::Adapters::Registry.register(
-    :file,
-    E11y::Adapters::File.new(
-      path: Rails.root.join('log', 'e11y.log'),
-      rotation: :daily,
-      max_size: 100 * 1024 * 1024, # 100MB
-      compress: true
-    )
+  # File adapter for local development
+  config.adapters[:file] = E11y::Adapters::File.new(
+    path: Rails.root.join('log', 'e11y.log'),
+    rotation: :daily,
+    max_size: 100 * 1024 * 1024,
+    compress: true
   )
 
-  # Register Stdout for console output
-  E11y::Adapters::Registry.register(
-    :stdout,
-    E11y::Adapters::Stdout.new(
-      pretty: Rails.env.development?,
-      colorize: true
-    )
+  # Stdout for console output
+  config.adapters[:stdout] = E11y::Adapters::Stdout.new(
+    pretty: Rails.env.development?,
+    colorize: true
   )
 
-  # Register InMemory for testing
-  if Rails.env.test?
-    E11y::Adapters::Registry.register(
-      :test,
-      E11y::Adapters::InMemory.new(
-        max_events: 1000,
-        max_batches: 100
-      )
-    )
-  end
+  # InMemory for testing
+  config.adapters[:test] = E11y::Adapters::InMemory.new(max_events: 1000, max_batches: 100) if Rails.env.test?
 end
 ```
 
@@ -2307,7 +2237,7 @@ Events::PaymentFailed.track(
 ```ruby
 # spec/events/order_placed_spec.rb
 RSpec.describe Events::OrderPlaced do
-  let(:adapter) { E11y::Adapters::Registry.resolve(:test) }
+  let(:adapter) { E11y.config.adapters[:test] }
 
   before do
     adapter.clear!
@@ -2342,7 +2272,7 @@ end
 
 ```ruby
 # Check adapter capabilities before using
-loki = E11y::Adapters::Registry.resolve(:loki)
+loki = E11y.config.adapters[:loki]
 puts loki.capabilities
 # => {
 #   batching: true,
@@ -2366,8 +2296,8 @@ end
 # config/initializers/health_check.rb
 HealthCheck.setup do |config|
   config.add_custom_check('e11y_adapters') do
-    adapters = E11y::Adapters::Registry.all
-    unhealthy = adapters.reject { |name, adapter| adapter.healthy? }
+    adapters = E11y.config.adapters
+    unhealthy = adapters.select { |_name, adapter| !adapter.respond_to?(:healthy?) || !adapter.healthy? }
 
     if unhealthy.any?
       "Unhealthy adapters: #{unhealthy.keys.join(', ')}"
@@ -2416,7 +2346,7 @@ E11y.configure do |config|
     ->(event) { :audit_encrypted if event[:audit_event] },
     ->(event) {
       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      days > 90 ? :s3_glacier : :loki
+      days > 90 ? :archive : :loki
     }
   ]
 end
@@ -2495,6 +2425,93 @@ module E11y
 end
 ```
 
+### 14.4.1. Routing Decision Matrix
+
+What happens to an event based on its type and configuration:
+
+```mermaid
+flowchart TD
+    Start{What type of event?}
+    
+    Start -->|Regular Event| R1{Has explicit adapters?}
+    Start -->|Audit Event| A1{Has explicit adapters?}
+    
+    R1 -->|YES| R2[Use explicit adapters]
+    R1 -->|NO| R3[Use severity mapping]
+    
+    R3 --> R4[info → logs]
+    R3 --> R5[error → logs + errors_tracker]
+    
+    R2 --> R6[Write to adapters]
+    R4 --> R6
+    R5 --> R6
+    R6 --> R7[SUCCESS]
+    
+    A1 -->|YES| A2[Use explicit adapters]
+    A1 -->|NO| A3[Return empty array]
+    
+    A3 --> A4{Routing rule matches?}
+    A4 -->|YES| A5[Use rule result]
+    A4 -->|NO| A6[Would use fallback]
+    
+    A2 --> A7[Validation: PASS explicit]
+    A5 --> A8[Validation: PASS rule matched]
+    A6 --> A9[Validation: FAIL]
+    
+    A7 --> A10[Write to adapters]
+    A8 --> A10
+    A9 --> A11[RAISE ERROR]
+    
+    A10 --> A12[SUCCESS encrypted + signed]
+    A11 --> A13[FAILURE event not stored]
+    
+    style R7 fill:#c8e6c9
+    style A12 fill:#c8e6c9
+    style A13 fill:#ffcdd2
+    style A11 fill:#ef5350
+```
+
+**Note:** Audit events without explicit adapters return `[]` so routing rules are evaluated. If no rule matches, fallback is used — but `validate_audit_routing!` raises (audit events MUST NOT use fallback).
+
+### 14.4.2. Adapter Resolution Logic
+
+How `Event::Base#adapters` resolves target adapters:
+
+```mermaid
+flowchart TD
+    A[Event.track called] --> B[Event::Base#adapters method]
+    
+    B --> C{Check @adapters instance variable}
+    C -->|SET| D[Return @adapters]
+    C -->|NIL| E{Check parent class @adapters}
+    
+    E -->|SET| F[Return parent.adapters]
+    E -->|NIL| G{Call resolved_adapters}
+    
+    G --> H{Is audit_event?}
+    H -->|YES| I[Return empty array]
+    H -->|NO| J[Call adapters_for_severity]
+    
+    J --> K[Check severity level]
+    K --> L[severity :info → logs]
+    K --> M[severity :error → logs + errors_tracker]
+    K --> N[severity :fatal → logs + errors_tracker]
+    K --> O[default → logs]
+    
+    D --> P[Result: adapters array]
+    F --> P
+    I --> P
+    L --> P
+    M --> P
+    N --> P
+    O --> P
+    
+    style I fill:#fff9c4
+    style P fill:#e0e0e0
+```
+
+**Key:** Audit events without explicit adapters return `[]` — routing middleware then applies `routing_rules` (e.g. `->(e) { :audit_encrypted if e[:audit_event] }`).
+
 ### 14.5. Configuration
 
 ```ruby
@@ -2508,13 +2525,13 @@ E11y.configure do |config|
     # Rule 2: Long retention → cold storage
     ->(event) {
       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      :s3_glacier if days > 90
+      :archive if days > 90
     },
     
     # Rule 3: Medium retention → warm storage
     ->(event) {
       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      :s3_standard if days.between?(30, 90)
+      :warm if days.between?(30, 90)
     },
     
     # Rule 4: Short retention → hot storage
@@ -2566,7 +2583,7 @@ end
 **After:** Automatic routing
 - Debug logs (7 days) → stdout: $0/month
 - Business (30 days) → Loki: $100/month
-- Audit (7 years) → S3 Glacier: $5/month
+- Audit (7 years) → cold tier: $5/month
 - **Total: $105/month (80% savings!)**
 
 ### 14.8. Advantages vs TieredStorage
@@ -2619,7 +2636,7 @@ RSpec.describe E11y::Middleware::Routing do
   it 'respects explicit adapters' do
     event = { adapters: [:sentry], retention_until: 1.year.from_now.iso8601 }
     expect(adapters[:sentry]).to receive(:write)
-    expect(adapters[:s3_glacier]).not_to receive(:write)
+    expect(adapters[:archive]).not_to receive(:write)
     routing.call(event)
   end
 end

data/docs/{ADR-005-tracing-context.md → architecture/ADR-005-tracing-context.md}

@@ -682,11 +682,11 @@ Already implemented in ADR-008, but here's the core logic:
 module E11y
   module TraceContext
     class JobPropagator
-      # Inject trace context into job metadata
+      # C17 Hybrid: Inject parent trace into job metadata (job will create NEW trace_id)
       def self.inject(job_metadata = {})
         return job_metadata unless E11y::Current.traced?
         
-        job_metadata['e11y_trace_id'] = E11y::Current.trace_id
+        job_metadata['e11y_parent_trace_id'] = E11y::Current.trace_id
         job_metadata['e11y_span_id'] = E11y::Current.span_id
         job_metadata['e11y_sampled'] = E11y::Current.sampled
         
@@ -702,14 +702,15 @@ module E11y
         job_metadata
       end
       
-      # Extract trace context from job metadata
+      # C17 Hybrid: Extract parent context; job gets NEW trace_id, links via parent_trace_id
       def self.extract(job_metadata)
-        return {} unless job_metadata['e11y_trace_id']
+        return {} unless job_metadata['e11y_parent_trace_id']
         
         {
-          trace_id: job_metadata['e11y_trace_id'],
+          trace_id: IDGenerator.generate_trace_id,  # NEW trace per job
+          parent_trace_id: job_metadata['e11y_parent_trace_id'],
           parent_span_id: job_metadata['e11y_span_id'],
-          span_id: IDGenerator.generate_span_id,  # New span for job
+          span_id: IDGenerator.generate_span_id,
           sampled: job_metadata['e11y_sampled'],
           baggage: job_metadata['e11y_baggage'],
           user_id: job_metadata['e11y_user_id'],
@@ -1055,7 +1056,7 @@ module E11y
       
       def extract_parent_context(job)
         {
-          trace_id: job['e11y_trace_id'],
+          trace_id: job['e11y_parent_trace_id'],
           span_id: job['e11y_span_id'],
           sampled: job['e11y_sampled'],
           baggage: job['e11y_baggage'],
@@ -1085,7 +1086,7 @@ module E11y
       def call(worker_class, job, queue, redis_pool)
         # Inject current trace context into job metadata
         if E11y::Current.traced?
-          job['e11y_trace_id'] = E11y::Current.trace_id
+          job['e11y_parent_trace_id'] = E11y::Current.trace_id
           job['e11y_span_id'] = E11y::Current.span_id
           job['e11y_sampled'] = E11y::Current.sampled
           job['e11y_baggage'] = E11y::Current.baggage if E11y::Current.baggage&.any?
@@ -1184,7 +1185,7 @@ ORDER BY created_at;
 # 1. Web request (trace_id: abc-123)
 POST /orders
   → Events::OrderCreated (trace_id: abc-123, span_id: span-001)
-  → Enqueue SendOrderEmailJob (metadata: {e11y_trace_id: 'abc-123'})
+  → Enqueue SendOrderEmailJob (metadata: {e11y_parent_trace_id: 'abc-123'})
 
 # 2. Sidekiq job execution (NEW trace_id: xyz-789)
 SendOrderEmailJob#perform