e11y 0.2.0 → 1.1.0

data/docs/{ADR-015-middleware-order.md → architecture/ADR-015-middleware-order.md}

@@ -14,7 +14,7 @@
 3. [Correct Order](#3-correct-order)
    - 3.1. Pipeline Flow
    - 3.2. Why Each Middleware Needs Original Class Name
-   - 3.3. Audit Event Pipeline Separation (C01 Resolution) ⚠️ CRITICAL
+   - 3.3. Audit Events in Single Pipeline (C01 Resolution) ⚠️ CRITICAL
      - 3.3.1. The Problem: PII Filtering Breaks Audit Trail
      - 3.3.2. Decision: Two Pipeline Configurations
      - 3.3.3. Declaring Audit Events
@@ -71,16 +71,18 @@
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.middleware.use E11y::Middleware::TraceContext      # 1
-  config.middleware.use E11y::Middleware::Validation        # 2
-  config.middleware.use E11y::Middleware::PIIFiltering      # 3
-  config.middleware.use E11y::Middleware::RateLimiting      # 4
-  config.middleware.use E11y::Middleware::Sampling          # 5
-  config.middleware.use E11y::Middleware::Versioning        # 6 ← LAST!
-  config.middleware.use E11y::Middleware::Routing           # 7
+  config.pipeline.use E11y::Middleware::TraceContext      # 1
+  config.pipeline.use E11y::Middleware::Validation        # 2
+  config.pipeline.use E11y::Middleware::PIIFilter      # 3
+  config.pipeline.use E11y::Middleware::RateLimiting      # 4
+  config.pipeline.use E11y::Middleware::Sampling          # 5
+  config.pipeline.use E11y::Middleware::Versioning        # 6 ← LAST!
+  config.pipeline.use E11y::Middleware::Routing           # 7
 end
 ```
 
+The default stack in `lib/e11y/configuration.rb` also includes `TrackLatency`, `BaggageProtection`, `AuditSigning`, `EventSlo`, and `SelfMonitoringEmit` after routing; the snippet is the ordering slice that matters for **versioning before routing**.
+
 ---
 
 ## 3. Correct Order
@@ -123,7 +125,7 @@ Adapters           → Receive normalized name
 |------------|----------------|------|
 | **TraceContext** | No | Just adds trace_id, doesn't care about class |
 | **Validation** | ✅ Yes | Schema is attached to specific class (V2 ≠ V1) |
-| **PIIFiltering** | ✅ Yes | PII rules may differ between V1 and V2 |
+| **PIIFilter** | ✅ Yes | PII rules may differ between V1 and V2 |
 | **RateLimiting** | ✅ Yes | Rate limits may differ between V1 and V2 |
 | **Sampling** | ✅ Yes | Sample rates may differ between V1 and V2 |
 | **Versioning** | No | Normalizes for adapters (cosmetic change) |
@@ -138,11 +140,11 @@ Adapters           → Receive normalized name
 
 ```ruby
 # ❌ WRONG ORDER!
-config.middleware.use E11y::Middleware::Versioning        # 1 ← Too early!
-config.middleware.use E11y::Middleware::Validation        # 2
-config.middleware.use E11y::Middleware::PIIFiltering      # 3
-config.middleware.use E11y::Middleware::RateLimiting      # 4
-config.middleware.use E11y::Middleware::Sampling          # 5
+config.pipeline.use E11y::Middleware::Versioning        # 1 ← Too early!
+config.pipeline.use E11y::Middleware::Validation        # 2
+config.pipeline.use E11y::Middleware::PIIFilter      # 3
+config.pipeline.use E11y::Middleware::RateLimiting      # 4
+config.pipeline.use E11y::Middleware::Sampling          # 5
 ```
 
 ### 4.2. What Breaks
@@ -244,17 +246,17 @@ Loki receives:
 - [ ] PII rules are configured **per original class** (if differ)
 - [ ] Sampling rules are configured **per original class** (if differ)
 - [ ] Metrics track **both** normalized name and version
-- [ ] Audit events use separate pipeline (C01 - see §3.3)
+- [ ] Audit events skip PII filtering via conditional logic (C01 - see §3.3, single pipeline)
 - [ ] Audit events stored in encrypted adapter (C01 requirement)
 
 ---
 
-## 3.3. Audit Event Pipeline Separation (C01 Resolution)
+## 3.3. Audit Events in Single Pipeline (C01 Resolution)
 
 > **⚠️ CRITICAL: C01 Conflict Resolution - PII Filtering × Audit Trail Signing**  
 > **See:** [CONFLICT-ANALYSIS.md C01](researches/CONFLICT-ANALYSIS.md#c01-pii-filtering--audit-trail-signing) for detailed analysis  
 > **Problem:** PII filtering before signing breaks non-repudiation (auditors can't verify original event)  
-> **Solution:** Separate pipeline for audit events that skips PII filtering, signs original data
+> **Solution:** Single pipeline for all events. Audit events get conditional skip in PIIFilter via `contains_pii false` in AuditEvent preset (:no_pii = pass-through). No separate pipeline — no need.
 
 ### 3.3.1. The Problem: PII Filtering Breaks Audit Trail
 
@@ -278,39 +280,29 @@ Storage
 - **Audit trail:** Must maintain cryptographic chain of custody
 - **Forensics:** Must be able to reconstruct exact event that occurred
 
-### 3.3.2. Decision: Two Pipeline Configurations
+### 3.3.2. Decision: One Pipeline with Conditional Skip
+
+**All events go through a single pipeline.** Audit events get conditional skip in middleware:
 
-**Standard Events (Non-Audit):**
 ```
 1. TraceContext    → Add trace_id, span_id, timestamp
 2. Validation      → Schema validation (original class)
-3. PIIFiltering    → Filter PII EARLY ✅
-4. RateLimiting    → Rate limit check
-5. Sampling        → Adaptive sampling
+3. PIIFilter    → Audit: skip (contains_pii false → :no_pii). Standard: filter PII ✅
+4. RateLimiting    → Audit: can skip (event_data[:audit_event]). Standard: rate limit
+5. Sampling        → Audit: sample_rate 1.0 (preset). Standard: adaptive
 6. Versioning      → Normalize event_name (LAST)
-7. Routing         → Route to buffer
+7. Routing         → Route to buffer / audit buffer
 ```
 
-**Audit Events (Legal Compliance):**
-```
-1. TraceContext    → Add trace_id, span_id, timestamp
-2. Validation      → Schema validation (original class)
-3. AuditSigning    → Sign ORIGINAL data (includes PII!) ✅
-4. Versioning      → Normalize event_name (LAST)
-5. Routing         → Route to audit buffer
-   
-❌ NO PII filtering for audit events!
-❌ NO rate limiting for audit events!
-❌ NO sampling for audit events!
-```
+**AuditEvent preset:** `contains_pii false` → PIIFilter :no_pii = pass-through, original data preserved for signing.
 
 ### 3.3.3. Declaring Audit Events
 
 **Event Class Flag:**
 ```ruby
-# Audit event - uses audit pipeline
+# Audit event - conditional skip in pipeline
 class Events::PermissionChanged < E11y::Event::Base
-  audit_event true  # ← Trigger audit pipeline
+  include E11y::Presets::AuditEvent  # audit_event true, contains_pii false
   # Auto-set: retention = E11y.config.audit_retention (configurable!)
   #           rate_limiting = false (LOCKED!)
   #           sampling = false (LOCKED!)
@@ -330,9 +322,9 @@ class Events::PermissionChanged < E11y::Event::Base
   version 1
 end
 
-# Standard event - uses standard pipeline
+# Standard event - full pipeline
 class Events::PageView < E11y::Event::Base
-  audit_event false  # ← Use standard pipeline (default)
+  # audit_event false (default)
   
   schema do
     required(:user_id).filled(:string)
@@ -355,21 +347,15 @@ end
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  # Standard pipeline (default for most events)
+  # Single pipeline for all events (audit and standard)
   config.pipeline.use E11y::Middleware::TraceContext      # 1
   config.pipeline.use E11y::Middleware::Validation        # 2
-  config.pipeline.use E11y::Middleware::PIIFiltering      # 3
+  config.pipeline.use E11y::Middleware::PIIFilter      # 3  # Audit: skip (contains_pii false)
   config.pipeline.use E11y::Middleware::RateLimiting      # 4
   config.pipeline.use E11y::Middleware::Sampling          # 5
-  config.pipeline.use E11y::Middleware::Versioning        # 6
-  config.pipeline.use E11y::Middleware::Routing           # 7
-  
-  # Audit pipeline override (for audit_event: true)
-  config.audit_pipeline.use E11y::Middleware::TraceContext      # 1
-  config.audit_pipeline.use E11y::Middleware::Validation        # 2
-  config.audit_pipeline.use E11y::Middleware::AuditSigning      # 3 (NEW!)
-  config.audit_pipeline.use E11y::Middleware::Versioning        # 4
-  config.audit_pipeline.use E11y::Middleware::AuditRouting      # 5
+  config.pipeline.use E11y::Middleware::AuditSigning      # 6  # Pass-through for non-audit
+  config.pipeline.use E11y::Middleware::Versioning        # 7  # Last before Routing
+  config.pipeline.use E11y::Middleware::Routing           # 8
   
   # Audit event configuration
   config.audit_events do
@@ -610,7 +596,7 @@ end
 | Aspect | Pro | Con | Mitigation |
 |--------|-----|-----|------------|
 | **Non-repudiation** | ✅ Signature on original data | ⚠️ PII in audit events | Use encrypted storage adapter |
-| **Legal compliance** | ✅ Meets audit requirements | ⚠️ Two pipelines to maintain | Clear documentation |
+| **Legal compliance** | ✅ Meets audit requirements | ⚠️ Conditional logic in middleware | Clear documentation |
 | **PII protection** | ✅ Standard events filtered | ⚠️ Audit events not filtered | Restrict access to audit logs |
 | **Performance** | ✅ No PII filter overhead | ⚠️ Signing + encryption overhead | Audit events are rare (<1%) |
 
@@ -682,7 +668,7 @@ class CustomEnrichmentMiddleware
 end
 
 # Pipeline execution:
-# 1. PIIFiltering → Removes :email field ✅
+# 1. PIIFilter → Removes :email field ✅
 # 2. CustomEnrichment → Adds :user_email field ❌ PII bypass!
 # 3. Adapters → Receive event with unfiltered PII!
 ```
@@ -771,7 +757,7 @@ E11y.configure do |config|
   
   # ZONE 2: Security (CRITICAL - PII handled here!)
   config.pipeline.zone(:security) do
-    use E11y::Middleware::PIIFiltering         # ← LAST PII touchpoint!
+    use E11y::Middleware::PIIFilter         # ← LAST PII touchpoint!
   end
   
   # ZONE 3: Routing (read-only decision making)
@@ -956,7 +942,7 @@ class UnsafeMiddleware < E11y::Middleware
   end
 end
 
-# If placed after PIIFiltering middleware:
+# If placed after PIIFilter middleware:
 # → PII bypass! Email not filtered!
 # → GDPR violation!
 ```
@@ -971,7 +957,7 @@ class SafeEnrichmentMiddleware < E11y::Middleware
     event_data[:payload][:request_path] = Current.request.path
     event_data[:payload][:user_agent] = Current.request.user_agent
     
-    # These fields will be filtered by PIIFiltering middleware if needed
+    # These fields will be filtered by PIIFilter middleware if needed
     @app.call(event_data)
   end
 end
@@ -1014,7 +1000,7 @@ end
 
 2. **Security Zone (PII filtering):**
    - ❌ DO NOT add custom middleware here
-   - ⚠️ Only E11y::Middleware::PIIFiltering should run
+   - ⚠️ Only E11y::Middleware::PIIFilter should run
    - ⚠️ Treat this zone as read-only (no custom code)
 
 3. **Post-Processing Zone (after PII filtering):**
@@ -1041,7 +1027,7 @@ end
 ```
 
 **Related Conflicts:**
-- **C01:** Audit events skip PII filtering (see §3.3)
+- **C01:** Audit events skip PII filtering via contains_pii false (see §3.3)
 - **C08:** Baggage PII protection (see ADR-007)
 
 ---
@@ -1053,8 +1039,6 @@ end
 - **ADR-012: Event Evolution & Versioning** - Full versioning design
 - **ADR-013: Reliability & Error Handling** - DLQ replay considerations
 - **UC-012: Audit Trail** - Audit event use cases
-- **COMPREHENSIVE-CONFIGURATION.md** - Complete configuration examples
-- **CONFLICT-ANALYSIS.md** - Complete conflict analysis
 
 ---