e11y 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae952b91e779ee9e04150e324109586016d6dd0e9831d6acf7867e05f686f579
-  data.tar.gz: 8c3a957e11bd4cc84b4f5fa9c90eae3248c083b98a518ee328cad76401d5454b
+  metadata.gz: 9d7e79dcbcbd63a42a108fff3b2c29f4cea6f07e8e2632145d4cff39f85514ac
+  data.tar.gz: b53a0b131efaad3accb9ab20b75c5dcf973274422d384432a3b3562437750e4b
 SHA512:
-  metadata.gz: ce56d9787c13db96db175a07418a34b17a43dd11dceb23d463c346abb7082caa1c45151826f6dc59981a069d8f2ec10d0f6eb4516f2da8cbce91754c483bae20
-  data.tar.gz: b5b650f09a2b634e31fedcebd058965dbc9787960769387b12a84bb5c14c96eb68bcc3245d04393bb75d51011dd290064185040daddcbc975aa8a66f6bda1709
+  metadata.gz: 4576c625410acc475dbd5782fa546b29adcc6a815c319d86eae9a9b8e0a700c49a099197db7fdccf3c3ea43f594c24bdd90ccdc689cad82e9a8da11d18d50999
+  data.tar.gz: f569447a2c1b532cc39246d163fe245b61f63ec9ee618a2c9cf428936f3eead760549d6774de9b8a5afc09d12a0df7439ad53bf0f41993a7c518af566ebbdc1d

data/.rspec

@@ -2,3 +2,4 @@
 --format documentation
 --color
 --order random
+--tag ~benchmark

data/.rubocop.yml

@@ -3,8 +3,10 @@
 # See https://rubystyle.guide/ for Ruby style guide
 # See https://docs.rubocop.org/rubocop/ for all available cops
 
-require:
+plugins:
+  - rubocop-performance
   - rubocop-rspec
+  - rubocop-rspec_rails
 
 AllCops:
   TargetRubyVersion: 3.2
@@ -15,23 +17,89 @@ AllCops:
     - 'vendor/**/*'
     - 'node_modules/**/*'
     - 'tmp/**/*'
+    - 'benchmarks/**/*'
 
 # Metrics
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
     - 'Rakefile'
+    - 'lib/tasks/**/*'
     - '*.gemspec'
+    - 'lib/e11y/reliability/retry_handler.rb'
+    - 'lib/e11y/instruments/active_job.rb'
 
 Metrics/MethodLength:
-  Max: 15
+  Max: 20
   Exclude:
     - 'spec/**/*'
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'lib/e11y/event/base.rb'
+    - 'lib/e11y/middleware/rate_limiting.rb'
+    - 'lib/e11y/middleware/sampling.rb'
 
 Metrics/ClassLength:
   Max: 100
   Exclude:
     - 'spec/**/*'
+    - 'lib/e11y/buffers/ephemeral_buffer.rb'
+    - 'lib/e11y/registry.rb'
+    - 'lib/e11y/adapters/otel_logs.rb'
+    - 'lib/e11y/adapters/opentelemetry_collector.rb'
+    - 'lib/e11y/opentelemetry/span_creator.rb'
+    - 'lib/e11y/configuration.rb'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'spec/integration/pattern_metrics_integration_spec.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/event/base.rb'
+    - 'lib/e11y/middleware/versioning.rb'
+    - 'lib/e11y/reliability/retry_handler.rb'
+    - 'lib/e11y/adapters/base.rb'
+    - 'lib/e11y/adapters/opentelemetry_collector.rb'
+    - 'lib/e11y/adapters/otel_logs.rb'
+    - 'lib/e11y/current.rb'
+    - 'lib/e11y/instruments/active_job.rb'
+    - 'lib/e11y/instruments/sidekiq.rb'
+    - 'lib/e11y/linters/pii/pii_declaration_linter.rb'
+    - 'lib/e11y/linters/slo/config_consistency_linter.rb'
+    - 'lib/e11y/logger/bridge.rb'
+    - 'lib/e11y/middleware/pii_filter.rb'
+    - 'lib/e11y/middleware/rate_limiting.rb'
+    - 'lib/e11y/middleware/sampling.rb'
+    - 'lib/e11y/opentelemetry/span_creator.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
 
 # Style
 Style/Documentation:
@@ -45,25 +113,97 @@ Style/StringLiterals:
 Style/FrozenStringLiteralComment:
   Enabled: true
 
+# Layout
+Layout/LineLength:
+  Max: 150
+
 # RSpec
 RSpec/ExampleLength:
-  Max: 20 # Allow longer examples for integration tests
+  Max: 40 # Allow longer examples for integration tests
+  Exclude:
+    - "spec/integration/**/*"
 
 RSpec/MultipleExpectations:
   Max: 10 # Allow more expectations for integration tests
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 10 # Allow more memoized helpers for complex tests
+
 RSpec/NestedGroups:
   Max: 3
+  Exclude:
+    - "spec/e11y/current_spec.rb"
+    - "spec/e11y/middleware/pii_filtering_spec.rb"
 
 # Gem-specific: Development dependencies can be in gemspec
 Gemspec/DevelopmentDependencies:
   Enabled: false
 
+Style/OneClassPerFile:
+  Exclude:
+    - "spec/dummy/config/application.rb"
+    - "spec/support/pipeline_debug.rb"
+
 # Allow integration tests without specific class
 RSpec/DescribeClass:
   Exclude:
     - "spec/zeitwerk_spec.rb"
+    - "spec/integration/**/*"
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/e11y/configuration/error_handling_config_spec.rb"
+
+# File path conventions (generators use spec/generators/e11y/ structure)
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - "spec/e11y/event/dsl_additions_spec.rb"
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/generators/e11y/*_spec.rb"
+    - "spec/e11y/opentelemetry/semantic_conventions_spec.rb"
+    - "spec/e11y/opentelemetry/span_creator_spec.rb"
+
+RSpec/DescribeMethod:
+  Exclude:
+    - "spec/e11y/module_api_spec.rb"
+
+RSpec/MultipleDescribes:
+  Exclude:
+    - "spec/e11y/adapters/null_adapter_spec.rb"
 
 # Allow simple doubles for now (will improve in Phase 1)
 RSpec/VerifiedDoubles:
   Enabled: false
+
+# MessageSpies: Prefer explicit expect().to receive() for readability.
+# Large codebase uses this pattern consistently (116 occurrences).
+# Will be gradually migrated to have_received in future.
+RSpec/MessageSpies:
+  Enabled: false
+
+# RSpec/Output: New cop in rubocop-rspec 3.x flagging puts in specs.
+# We use puts for diagnostic output in integration tests and support files.
+RSpec/Output:
+  Enabled: false
+
+RSpec/RepeatedExample:
+  Exclude:
+    - "spec/e11y/instruments/rails_instrumentation_spec.rb"
+    - "spec/e11y/versioning/version_extractor_spec.rb"
+
+RSpec/StubbedMock:
+  Exclude:
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/e11y/slo/config_loader_spec.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/e11y/adapters/opentelemetry_collector.rb"
+    - "lib/e11y/adapters/otel_logs.rb"
+
+Style/SafeNavigationChainLength:
+  Exclude:
+    - "lib/e11y/linters/pii/pii_declaration_linter.rb"
+
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - "lib/e11y/middleware/pii_filter.rb"
+

data/CHANGELOG.md

@@ -2,25 +2,218 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
 ### Added
-- Initial gem skeleton setup
-- Zeitwerk autoloading configuration
-- Basic project structure (lib/, spec/, bin/)
-- CI/CD pipeline (GitHub Actions)
-- Documentation framework (YARD, README)
 
-## [0.1.0] - 2026-01-17
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+### Security
+
+## [1.0.0] - 2026-03-20
+
+### BREAKING: Configuration — Flat config API
+
+**Nested config objects removed.** All configuration options are now flat accessors on `config`.
+
+**Key migrations:**
+- `config.rails_instrumentation.enabled` → `config.rails_instrumentation_enabled`
+- `config.logger_bridge.track_severities` → `config.logger_bridge_track_severities`
+- `config.rate_limiting { }` removed → use `config.rate_limiting_enabled`, `config.add_rate_limit_per_event(...)`
+- `config.slo { }` removed → use `config.slo_tracking_enabled`, `config.add_slo_controller(...)`
+
+**Full mapping:** See `docs/plans/2026-03-13-configuration-design.md`
+
+### BREAKING: Middleware order changed (ADR-015 compliance)
+
+**Per ADR-015 and ADR-006:**
+- **Versioning** moved to last (before Routing) — Validation, PII, RateLimiting, Sampling now use original class names
+- **AuditSigning** before PIIFilter — audit events signed with original data (GDPR Art. 30 non-repudiation)
+- **RateLimiting** before Sampling — matches ADR #4, #5
+
+**New order:** TraceContext → Validation → AuditSigning → PIIFilter → RateLimiting → Sampling → Versioning → Routing → EventSlo
+
+**Migration:** If you custom-configured pipeline order, ensure Versioning is last before Routing. Audit events now receive unfiltered payload at signing.
+
+### BREAKING: Registry.all_events → Registry.event_classes
+
+**Renamed for clarity:** Method returns event classes, not event instances or names.
+
+**Migration:** `E11y::Registry.all_events` → `E11y::Registry.event_classes`
+
+### BREAKING: RequestScopedBuffer → EphemeralBuffer
+
+**Renamed for accuracy:** The buffer works for both HTTP requests and background jobs. "Ephemeral" reflects its temporary lifecycle.
+
+**Migration:**
+- `E11y::Buffers::RequestScopedBuffer` → `E11y::Buffers::EphemeralBuffer`
+- `config.request_buffer` → `config.ephemeral_buffer`
+- `Thread.current[:e11y_request_buffer]` → `Thread.current[:e11y_ephemeral_buffer]`
+- Yabeda metric `e11y_request_buffer_total` → `e11y_ephemeral_buffer_total`
+
+**Search and replace:** `RequestScopedBuffer` → `EphemeralBuffer`, `request_buffer` → `ephemeral_buffer`
 
 ### Added
-- Project initialization
-- Phase 0: Gem Setup & Best Practices Research complete
-- Research documents for 6 successful gems (Devise, Sidekiq, Puma, Dry-rb, Yabeda, Sentry)
-- Best practices synthesis for configuration DSL, testing, documentation, CI/CD, release process
 
-[Unreleased]: https://github.com/arturseletskiy/e11y/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/arturseletskiy/e11y/releases/tag/v0.1.0
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+### Security
+
+## [0.2.0] - 2026-01-26
+
+### Added
+- Multi-Rails version support (7.0, 7.1, 8.0) (#5)
+  - CI matrix testing across Ruby 3.2, 3.3 with Rails 7.0, 7.1, 8.0
+  - Dynamic Gemfile dependencies based on RAILS_VERSION env var
+  - Support for sqlite3 1.4 (Rails 7.x) and 2.0 (Rails 8.x)
+- Comprehensive test suite documentation in README (#5)
+  - Quick commands using rake tasks
+  - Manual commands for each test suite
+  - Test suite overview with timing and example counts
+  - Development commands reference
+- Climate Control gem for ENV manipulation in tests (#5)
+
+### Fixed
+- **RequestScopedBuffer API method names** (#5)
+  - `start!` → `initialize!` (correct initialization method)
+  - `flush!` → `discard` (for success path - discard buffered events)
+  - `flush_on_error!` → `flush_on_error` (remove bang, method doesn't modify in-place)
+  - This eliminates warning messages during test execution
+  - **BREAKING CHANGE:** If you use `E11y::Buffers::RequestScopedBuffer` directly, update method names
+- Rails instrumentation event namespaces (#5)
+  - Fixed: `"Events::Rails::*"` → `"E11y::Events::Rails::*"`
+  - Resolves uninitialized constant errors in Rails instrumentation
+- Rails 8.0 exception handling test compatibility (#5)
+  - Updated error handling test to support both Rails 7.x and 8.0 behaviors
+  - Rails 8.0 changed: exceptions caught and converted to 500 responses
+  - Rails 7.x: exceptions raised with show_exceptions = false
+- HTTP request format validation (#5)
+  - Now accepts Symbol (e.g., :html, :json) as Rails passes format as Symbol
+  - Removed strict :string type check from format field
+- Integration test isolation issues (#5)
+  - Moved Rails initialization to spec_helper.rb (prevents FrozenError)
+  - Renamed TestJob → DummyTestJob to prevent class conflicts
+  - Fixed railtie integration spec tag isolation
+  - Added File.exist? check for routes file in railtie tests
+- Floating point precision in stratified sampling tests (#5)
+  - Increased upper bound from 0.95 to 0.96 to handle FP precision
+  - Fixes intermittent test failures: expected 0.9500000000000001 to be <= 0.95
+- Test isolation in active_job_spec.rb (#5)
+  - Store and restore original request_buffer.enabled config
+  - Prevents config changes from affecting subsequent tests
+- View rendering instrumentation test (#5)
+  - Added posts/list.html.erb template
+  - Added posts#list action to render HTML views
+  - Implemented complete test for view rendering events (was pending)
+
+### Changed
+- CI workflow now tests against multiple Rails versions (#5)
+  - Matrix: Ruby 3.2, 3.3 × Rails 7.0, 7.1, 8.0
+  - Separate artifact uploads per Ruby/Rails combination
+  - Enhanced test output with Rails version information
+- Improved test execution speed with better organization (#5)
+  - Separate rake tasks: spec:unit, spec:integration, spec:railtie
+  - Unit tests exclude integration and railtie specs
+  - Integration tests run only integration specs
+  - Total: 1729 examples (1672 unit + 36 integration + 21 railtie)
+- RuboCop configuration (#5)
+  - Exclude spec/integration/**/* from RSpec/DescribeClass cop
+  - Integration tests don't always describe a specific class
+
+### Breaking Changes
+
+#### RequestScopedBuffer API (affects only direct usage)
+
+If you use `E11y::Buffers::RequestScopedBuffer` directly in your code, update method names:
+
+**Before (incorrect):**
+```ruby
+E11y::Buffers::RequestScopedBuffer.start!          # ❌ Wrong
+E11y::Buffers::RequestScopedBuffer.flush!          # ❌ Wrong
+E11y::Buffers::RequestScopedBuffer.flush_on_error! # ❌ Wrong
+```
+
+**After (correct):**
+```ruby
+E11y::Buffers::RequestScopedBuffer.initialize!     # ✅ Correct
+E11y::Buffers::RequestScopedBuffer.discard         # ✅ Correct
+E11y::Buffers::RequestScopedBuffer.flush_on_error  # ✅ Correct
+```
+
+**Impact:** LOW - RequestScopedBuffer is an internal API. Most users are not affected as the middleware, ActiveJob, and Sidekiq instrumentations are already updated. Only users who directly call these methods need to update their code.
+
+**Migration:** Search your codebase for `RequestScopedBuffer` and update method names if found.
+
+---
+
+## [0.1.0] - 2026-01-17
+
+Initial release of E11y - Event-driven observability for Rails applications.
+
+### Features
+
+- **Core Event System**
+  - Unified event API with dry-schema validation
+  - Type-safe event schemas
+  - Extensible adapter architecture
+  - Request-scoped debug buffering
+
+- **Rails Integration**
+  - Automatic Rails instrumentation
+  - ActiveJob tracking
+  - Sidekiq middleware
+  - Rails.logger bridge
+  - Trace context propagation
+
+- **Adapters**
+  - Loki (logs)
+  - Prometheus (metrics)
+  - Sentry (errors)
+  - OpenTelemetry (traces)
+  - Elasticsearch (search)
+  - Redis (fast writes)
+  - Audit log (encrypted storage)
+
+- **Advanced Features**
+  - Event-level metrics (metrics DSL)
+  - PII filtering with configurable rules
+  - Stratified sampling
+  - Rate limiting
+  - High-cardinality protection
+  - Error handling with retry and DLQ
+
+- **Developer Experience**
+  - RSpec matchers for testing
+  - InMemory test adapter
+  - Zero-config defaults
+  - Comprehensive documentation
+  - 25+ ADRs and use cases
+
+### Supported Versions
+
+- Ruby: 3.2, 3.3
+- Rails: 8.0
+- RSpec: 3.13+
+
+### Documentation
+
+- 17 Architecture Decision Records (ADRs)
+- 22 Use Cases with examples
+- Complete API documentation
+- Testing guide
+- Migration guides

data/CLAUDE.md

@@ -0,0 +1,168 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+E11y ("easy telemetry") is a Ruby gem providing observability for Rails apps. Its key differentiator is **request-scoped debug buffering**: debug logs accumulate in memory during a request and flush to storage only if the request fails, cutting noise by ~90%.
+
+- **Ruby**: 3.2+, **Rails**: 7.0–8.0 (8.1 excluded due to a sqlite3 bug)
+- **Gem version**: 0.2.0, current branch: `feat/integration-testing`
+
+## Commands
+
+```bash
+# Run all tests
+rake spec:all
+
+# Run unit tests only (fast, no Rails required)
+rake spec:unit
+
+# Run integration tests (requires --with integration bundle group)
+rake spec:integration
+
+# Integration tests for Loki/OTel adapters require services — start with docker compose:
+docker compose up -d loki otel-collector
+INTEGRATION=true bundle exec rspec spec/integration/critical_adapters_integration_spec.rb
+
+# Run a single spec file
+bundle exec rspec spec/e11y/adapters/loki_adapter_spec.rb
+
+# Run a single example by line number
+bundle exec rspec spec/e11y/adapters/loki_adapter_spec.rb:42
+
+# Lint
+bundle exec rubocop
+
+# Lint with autocorrect
+bundle exec rubocop -a
+
+# Install integration dependencies (needed before rake spec:integration)
+bundle install --with integration
+
+# Open a console with the gem loaded
+rake console
+
+# Run benchmarks
+rake spec:benchmark
+
+# Run Cucumber acceptance tests
+rake cucumber
+# Or: bundle exec cucumber features/
+
+# Cucumber with Loki (adapter_configurations.feature): start Loki + OTel first
+docker compose up -d loki otel-collector
+rake cucumber
+
+# Run TUI (interactive log viewer)
+bundle exec e11y
+
+# Start MCP server (for Cursor / Claude Code)
+bundle exec e11y mcp
+
+# Stream events to stdout
+bundle exec e11y tail
+```
+
+## Architecture
+
+### Event Processing Pipeline
+
+Every event flows through a middleware pipeline before reaching an adapter:
+
+```
+Event.track(data)
+  → Validation (dry-schema)
+  → Sampling (adaptive: error-spike, load, value-based)
+  → PII Filtering (mask/hash sensitive fields)
+  → Trace Context (attach OTel span/trace IDs)
+  → Routing (direct to adapters by severity/type)
+  → Rate Limiting
+  → Audit Signing
+  → Adapter(s): Loki | Sentry | OpenTelemetry | Yabeda | File | Stdout | InMemory
+```
+
+Pipeline is built in `lib/e11y/pipeline/builder.rb`. Middleware order matters — see ADR-015.
+
+### Key Modules
+
+| Path | Role |
+|------|------|
+| `lib/e11y.rb` | Public API, `E11y.configure`, `E11y.configuration`, `E11y.logger` |
+| `lib/e11y/event/base.rb` | Base event class; all user events inherit from this |
+| `lib/e11y/adapters/` | Backend adapters (Loki, Sentry, OTel, Yabeda, File, Stdout, InMemory) |
+| `lib/e11y/middleware/` | 11 pipeline stages (validation, sampling, PII, routing, etc.) |
+| `lib/e11y/buffers/` | Request-scoped buffer + adaptive buffer implementations |
+| `lib/e11y/pipeline/builder.rb` | Assembles middleware chain from configuration |
+| `lib/e11y/railtie.rb` | Rails integration entry point |
+| `lib/e11y/pii/` | PII detection patterns and masking/hashing strategies |
+| `lib/e11y/sampling/` | Error-spike, load-based, value-based sampling strategies |
+| `lib/e11y/reliability/` | Circuit breaker, DLQ (dead letter queue), retry logic |
+| `lib/e11y/slo/` | Event-driven SLO tracking |
+| `lib/e11y/metrics/` | Prometheus metrics registry with cardinality protection |
+| `gems/e11y-devtools/` | Developer tools gem (TUI, Browser Overlay, MCP) — dev-only |
+| `gems/e11y-devtools/lib/e11y/devtools/tui/` | ratatui_ruby TUI — interaction-centric log viewer |
+| `gems/e11y-devtools/lib/e11y/devtools/overlay/` | Rails Engine — floating badge + slide-in panel |
+| `gems/e11y-devtools/lib/e11y/devtools/mcp/` | MCP Server — AI integration for Cursor/Claude Code |
+| `lib/e11y/adapters/dev_log.rb` | DevLog adapter — JSONL write+read, shared by all viewers |
+
+### Event Definition Pattern
+
+Events are defined as classes inheriting from `E11y::Event::Base`:
+
+```ruby
+class Events::OrderCreated < E11y::Event::Base
+  schema do
+    required(:order_id).filled(:string)
+    required(:amount).filled(:float)
+    optional(:user_id).maybe(:string)
+  end
+
+  metrics do
+    counter :orders_created_total, "Orders created"
+    histogram :order_amount, "Order amount in USD", buckets: [10, 50, 100, 500]
+  end
+end
+
+# Usage
+Events::OrderCreated.track(order_id: order.id, amount: order.total)
+```
+
+### Adapter Routing
+
+Adapters are registered in configuration and events route to them by severity:
+- `error`/`fatal` → errors tracker (e.g., Sentry)
+- other severities → logs (e.g., Loki)
+- metrics always → Yabeda/Prometheus
+
+### Request-Scoped Buffering
+
+The buffer middleware captures debug-level events in a `Concurrent::Array` per request (stored in `Thread.current`). On request success: buffer discarded. On request failure: buffer flushed to configured adapters. Controlled by `config.ephemeral_buffer_enabled`.
+
+## Test Structure
+
+- `spec/e11y/` — Unit tests (86 files, ~1672 examples, fast)
+- `spec/integration/` — Integration tests against a real Rails app (~36 examples)
+- `spec/dummy/` — Minimal Rails app used by integration tests
+- `spec/dummy/app/events/events/` — Event class definitions for test fixtures
+- `spec/support/matchers/` — Custom RSpec matchers including PII matchers
+- `spec/fixtures/pii_samples.yml` — PII test data
+
+Integration tests use `DatabaseCleaner` and require `--with integration` bundle group.
+
+## Code Conventions
+
+- Frozen string literals everywhere (`# frozen_string_literal: true`)
+- Double-quoted strings (enforced by RuboCop)
+- Events use class-level `.track` (not instantiation) — zero-allocation design; data stored in plain Hashes
+- Adapters inherit from `E11y::Adapters::Base` and implement `#deliver(event_data)`
+- Middleware inherits from `E11y::Middleware::Base` and implements `#call(event, pipeline)`
+
+## Architecture Decision Records
+
+The `docs/architecture/ADR-*.md` files document design decisions. Key ones:
+- **ADR-004**: Adapter architecture
+- **ADR-011**: Testing strategy
+- **ADR-013**: Reliability and error handling
+- **ADR-015**: Middleware ordering (critical — changing order breaks the pipeline)
+- **ADR-017**: Multi-Rails compatibility approach