chronos-ruby 0.3.0.pre.1 → 0.4.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db591fb9c6019444d079a5a5c683be8776b68010e3665e4a09656c2bdf568b46
-  data.tar.gz: 601f34cdaa1f9e06e2748a820b4228bad3c354a8c7feb562473d4268dc217117
+  metadata.gz: 1ab10ffdc0cff4274241465904b18e4bceb4fa230ea9fddb4b8be419c08e3463
+  data.tar.gz: 2d6d778012088192efed14e0ab64958716c8a6b4c3e697127c52573dc4dcd47b
 SHA512:
-  metadata.gz: 1c4adaeb1222449ba2b7a736f1e28e701d00a1faf3733f42ffa753759854c3deed7a4c9e4c33f2ea997aa9445f057b51641b3829fb49b2012e6668687a1df4b0
-  data.tar.gz: 3809e42fbaed2f3290464cdc7a1e962a70e39fd8c3f7071b6016ee53c53406fca84a250f375e0a46506560c9bdc603f4ceb13721b79b4c6225b28a1e94abdf49
+  metadata.gz: a8bb789313b2b7d360b6a8c08e5b5cf731aa1325912be7b560a1869b3d8717e4e779610e92591c1a2c436f5d14cd39e28f1e5db837d954def1db232788284d2d
+  data.tar.gz: 93a311d6905d83dee031a88cb5887854a32e60d26eceb0dc0446a8244c77a2c9fa763089bc5ec5fa25d265cb5881c3775dafe6361b1e84a1c6044aa89df220ee

data/CHANGELOG.md

@@ -11,6 +11,29 @@ All notable changes are documented here. The project follows Semantic Versioning
 - legacy CI now resolves Bundler 1.17.3 through `Gem.bin_path` on RubyGems versions that do not support the `_version_` executable selector.
 - documentation verification now reads source and Markdown files explicitly as UTF-8 on legacy container locales.
 
+## [0.4.0.pre.1] - 2026-07-20
+
+### Added
+
+- Rack-protocol middleware for automatic exception capture with propagation of the original failure;
+- request context for method, normalized route, status, duration, request ID, optional user agent, host, path, controller/action, approximate response size, user, and sanitized parameters;
+- selectable context-store port with a thread-local legacy adapter and guaranteed scope cleanup;
+- bounded circular breadcrumbs for custom, log, request, query, external HTTP, cache, and job categories;
+- public `Chronos.with_context` and `Chronos.add_breadcrumb` APIs;
+- Rack context contract, concurrency tests, module documentation, ADR, executable example, and request-overhead benchmark.
+
+### Changed
+
+- manual notifications now inherit the current execution context and breadcrumbs;
+- version advanced to `0.4.0.pre.1`.
+
+### Known limitations
+
+- generic route normalization cannot identify every application-specific dynamic segment;
+- thread-local context does not propagate into application-created threads or fibers;
+- deferred exceptions raised only while enumerating a streaming response body are not captured;
+- Rails-specific installation and route discovery remain planned for version 0.5.
+
 ## [0.3.0.pre.1] - 2026-07-20
 
 ### Added

data/README.md

@@ -1,16 +1,18 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.3 adds bounded resilience to the privacy-focused legacy foundation: manual exceptions are sanitized before queueing, retried under a finite policy, retained in a fixed-size memory backlog during outages, and controlled by a restricted remote policy.
+Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.4 adds automatic Rack exception capture, isolated request context, and bounded breadcrumbs to the privacy and resilience foundations from earlier releases.
 
 ## What the gem collects
 
-For each exception, version 0.3 can collect:
+For each exception, version 0.4 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
 - application-supplied context, parameters, session, and user fields;
 - Ruby version, engine, platform, process ID, opaque thread ID, and hostname;
 - application version, environment, and service name.
+- Rack method, normalized route, status, duration, request ID, host, query-free path, optional user agent, controller/action, response size, trace ID, and already-parsed parameters when the middleware is used;
+- bounded breadcrumbs explicitly supplied by the application or integration.
 
 See [Data collected](docs/data-collected.md) for the complete field table.
 
@@ -20,7 +22,7 @@ Chronos Ruby does not inspect environment variables, request bodies, cookies, HT
 
 ## Supported Ruby and Rails versions
 
-Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.3 is independent of Rails and does not yet declare support for any Rails integration. All supported combinations must pass dedicated CI before being listed as supported.
+Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.4 implements the Rack protocol but does not yet declare Rails support. All supported combinations must pass dedicated CI before being listed as supported.
 
 See [Compatibility](docs/compatibility.md).
 
@@ -29,7 +31,7 @@ See [Compatibility](docs/compatibility.md).
 The current public build is a pre-release. Add its exact version to the application's `Gemfile`:
 
 ```ruby
-gem "chronos-ruby", "0.3.0.pre.1"
+gem "chronos-ruby", "0.4.0.pre.1"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -47,7 +49,7 @@ gem install chronos-ruby --pre
 
 ## Rails installation
 
-Rails automatic integration is not part of version 0.3. A Rails application may use the plain Ruby API, but this does not constitute declared Rails support. Rack and Rails adapters are planned for later legacy releases.
+Rails automatic installation is not part of version 0.4. A Rails application may install the Rack middleware manually, but this does not constitute declared Rails support. Railtie and generator support are planned for version 0.5.
 
 ## Minimum configuration
 
@@ -70,7 +72,14 @@ HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_
 
 ## Automatic capture
 
-Automatic exception capture is not implemented in version 0.3. Applications must call `Chronos.notify` or `Chronos.notify_sync`. Rack, Rails, and worker hooks will be introduced only after their compatibility suites exist.
+Rack applications can capture unhandled exceptions automatically and preserve the application error semantics:
+
+```ruby
+use Chronos::Integrations::Rack::Middleware,
+    :include_user_agent => false
+```
+
+The middleware notifies asynchronously and re-raises the same exception. It never reads the request body, raw query string, cookies, authorization headers, or response body. See [Rack integration and context](docs/modules/rack-context.md).
 
 ## Manual capture
 
@@ -101,15 +110,25 @@ User data is opt-in and must contain only values your application is allowed to
 Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
 ```
 
-Version 0.3 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
+Version 0.4 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
 
 ## Breadcrumbs
 
-Breadcrumbs are not implemented in version 0.3.
+Breadcrumbs use a fixed circular buffer scoped to the current execution:
+
+```ruby
+Chronos.add_breadcrumb(
+  :category => "custom",
+  :message => "payment started",
+  :metadata => {"provider" => "example"}
+)
+```
+
+No log, SQL, HTTP, cache, job, request body, or response body payload is collected automatically. Unknown categories become `custom`, and metadata is bounded and sanitized before queueing.
 
 ## Filters and LGPD
 
-Version 0.3 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
+Version 0.4 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
 
 ```ruby
 Chronos.configure do |config|
@@ -133,19 +152,19 @@ Chronos.configure do |config|
 end
 ```
 
-Local exception-specific ignore callbacks are not available in version 0.3. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
+Local exception-specific ignore callbacks are not available in version 0.4. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
 
 ## Performance monitoring
 
-Request, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.3. The local capture pipeline is bounded and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
+Request timing events, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.4. Rack exception context is bounded, and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
 
 ## Sidekiq and Active Job
 
-Sidekiq and Active Job integrations are not implemented in version 0.3. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
+Sidekiq and Active Job integrations are not implemented in version 0.4. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
 
 ## Deploy tracking
 
-Deploy notifications are not implemented in version 0.3. `app_version` may be included in exception events for release correlation.
+Deploy notifications are not implemented in version 0.4. `app_version` may be included in exception events for release correlation.
 
 ## Asynchronous queue
 
@@ -168,7 +187,7 @@ Use `Chronos.flush(timeout)` to wait for accepted events and `Chronos.close(time
 
 ## Retry and backlog
 
-Version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
+The resilience layer introduced in version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
 
 After retries are exhausted, the already sanitized `SerializedEvent` may enter a fixed-capacity memory backlog. The backlog drops new items when full, is lost when the process exits, and never writes to disk. A later successful half-open probe drains backlog items as new events arrive.
 
@@ -182,7 +201,8 @@ The code follows hexagonal boundaries:
 - `Chronos::Application` coordinates capture;
 - `Chronos::Application::DeliveryPipeline` owns bounded retry and remote policy;
 - `Chronos::Ports` defines delivery behavior;
-- `Chronos::Adapters` implements Net::HTTP delivery;
+- `Chronos::Adapters` implements Net::HTTP delivery and thread-local context;
+- `Chronos::Integrations::Rack` implements optional automatic Rack capture;
 - `Chronos::Internal` owns bounded queueing, workers, and defensive logging.
 
 The core has no dependency on Rails, Rack, Sidekiq, or ActiveSupport. See [Architecture](docs/architecture.md).
@@ -210,6 +230,9 @@ Chronos.configure do |config|
   config.circuit_failure_threshold = 5
   config.circuit_reset_timeout = 30.0
   config.remote_configuration = true
+  config.context_store = :thread_local
+  config.breadcrumb_capacity = 20
+  config.breadcrumb_max_bytes = 2048
 end
 ```
 
@@ -221,7 +244,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.3 benchmarks with:
+Run the version 0.4 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -229,13 +252,14 @@ bundle _1.17.3_ exec ruby benchmarks/serialization.rb
 bundle _1.17.3_ exec ruby benchmarks/filtering.rb
 bundle _1.17.3_ exec ruby benchmarks/queue.rb
 bundle _1.17.3_ exec ruby benchmarks/retry_backlog.rb
+bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
 ```
 
 Results depend on runtime, hardware, and payload. No performance comparison is claimed until repeatable measurements are published.
 
 ## Migration from Airbrake
 
-An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.3 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.4 does not claim API compatibility or automatic replacement.
 
 ## Local development
 

data/contracts/rack-context-v1.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/rack-context-v1.schema.json",
+  "title": "Chronos Rack exception context v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["request", "trace_id", "breadcrumbs"],
+  "properties": {
+    "trace_id": {"type": "string", "minLength": 1},
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "route", "status", "duration_ms", "request_id", "host", "path"],
+      "properties": {
+        "method": {"type": "string"},
+        "route": {"type": "string"},
+        "status": {"type": "integer"},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "request_id": {"type": ["string", "null"]},
+        "user_agent": {"type": ["string", "null"]},
+        "host": {"type": "string"},
+        "path": {"type": "string"},
+        "controller": {"type": ["string", "null"]},
+        "action": {"type": ["string", "null"]},
+        "response_size": {"type": ["integer", "null"], "minimum": 0}
+      }
+    },
+    "breadcrumbs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["category", "message", "metadata", "timestamp"],
+        "properties": {
+          "category": {"enum": ["custom", "log", "request", "query", "external_http", "cache", "job"]},
+          "message": {"type": "string"},
+          "metadata": {"type": "object"},
+          "timestamp": {"type": "string"}
+        }
+      }
+    }
+  }
+}

data/docs/adr/ADR-012-rack-context-isolation.md

@@ -0,0 +1,27 @@
+# ADR-012 — Rack capture with selectable execution context
+
+## Status
+
+Accepted for version 0.4.
+
+## Context
+
+Automatic Rack capture needs request-scoped state, but the legacy line cannot rely on modern fiber-local APIs. Loading the plain Ruby gem must not force Rack into applications that do not use it. Request and response bodies also carry disproportionate privacy and performance risk.
+
+## Decision
+
+Implement a Rack-protocol middleware without a runtime Rack dependency. Catch failures from the downstream application call, notify asynchronously, and re-raise the same exception. Never read `rack.input`, raw query strings, cookies, authorization headers, or response body enumeration. Use already-parsed parameter hashes only.
+
+Define a `ContextStore` port and use a selectable thread-local adapter by default. Restore nested scopes in `ensure`. Keep breadcrumbs in a fixed circular per-execution buffer and sanitize them with the rest of the event before queueing.
+
+## Alternatives
+
+Requiring Rack from the core was rejected because it would add dependency and resolution risk to plain Ruby legacy applications. Global or process-wide context was rejected because concurrent requests would leak data. Automatic body parsing and body proxies were deferred because they change I/O behavior and complicate streaming lifecycle ownership.
+
+## Positive consequences
+
+Plain Ruby loading remains dependency-free, concurrent request context is isolated, middleware failure semantics are preserved, and diagnostic memory is bounded.
+
+## Negative consequences
+
+Thread-local context does not propagate to application-created threads or fibers. Generic route normalization is less precise than router-specific integration. Exceptions raised only during deferred response-body enumeration are outside version 0.4 capture.

data/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.3 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.4 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -11,18 +11,26 @@ flowchart TB
   Application --> Delivery[Application / DeliveryPipeline]
   Delivery --> Internal[Internal / BoundedQueue, WorkerPool, and MemoryBacklog]
   Internal --> Ports
+  Rack[Integrations / Rack middleware] --> Facade
+  Facade --> Context[Ports / ContextStore]
+  Context --> ThreadLocal[Adapters / ThreadLocalContextStore]
 ```
 
 ## Boundaries
 
 - Domain/Core owns immutable event values and Ruby normalization.
 - Application owns use-case ordering and failure containment.
-- Ports define behavior expected from infrastructure.
-- Adapters contain Net::HTTP and TLS behavior.
+- Ports define behavior expected from transport and execution-context infrastructure.
+- Adapters contain Net::HTTP, TLS, and thread-local context behavior.
 - Internal contains private concurrency and diagnostic mechanisms.
+- Integrations contain optional framework entry points and never enter the domain boundary.
 
 The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and job libraries must not be required by the core.
 
+## Rack capture flow
+
+The Rack middleware establishes a context-store scope, adds a bounded request breadcrumb, and calls the downstream application. An unhandled exception is enriched with request duration and status, captured through the normal notice pipeline, then re-raised unchanged. The context-store adapter restores or clears its value in `ensure`. The middleware implements the Rack protocol without requiring the Rack library.
+
 ## Capture flow
 
 An exception becomes an immutable notice. `Sanitizer` removes sensitive values before `SafeSerializer` creates a bounded JSON envelope. Asynchronous capture inserts only that sanitized serialized event into the queue. A fixed worker sends it through `DeliveryPipeline`, which applies finite retry, a circuit breaker, and a fixed memory backlog. Synchronous capture bypasses the queue but uses the same privacy and resilience boundaries.

data/docs/compatibility.md

@@ -4,14 +4,14 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 
 | Ruby | Rails integration | Status | Evidence |
 |---|---|---|---|
-| 2.2.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.3.8 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.4.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.5.9 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.6.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 2.2.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
+| 2.3.8 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
+| 2.4.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
+| 2.5.9 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
+| 2.6.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
 | 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
 
-No Rails version is declared supported by version 0.3. Rails applications may call the plain Ruby API manually. Rails support requires a real example application, framework integration tests, and a successful dedicated matrix job.
+No Rails version is declared supported by version 0.4. The middleware is tested against the Rack protocol shape without adding a Rack runtime dependency. Rails support requires a real example application, Railtie integration tests, and a successful dedicated matrix job.
 
 Status meanings:
 

data/docs/configuration.md

@@ -39,8 +39,11 @@
 | `remote_configuration` | Optional | `true` | Accepts only the documented bounded remote policy fields |
 | `remote_config_max_bytes` | Optional | `4096` | Maximum remote policy response-header bytes |
 | `sampling_rate` | Optional | `1.0` | Local upper bound for exception sampling |
-| `enabled_event_types` | Optional | `["exception"]` | Local event-type allowlist; only exception exists in version 0.3 |
+| `enabled_event_types` | Optional | `["exception"]` | Local event-type allowlist; only exception exists in version 0.4 |
 | `max_remote_send_interval` | Optional | `60.0` | Local upper bound for remotely requested send spacing |
+| `context_store` | Optional | `:thread_local` | `:thread_local` or an object implementing `get`, `set`, `clear`, and `with_context` |
+| `breadcrumb_capacity` | Optional | `20` | Positive count of newest breadcrumbs retained per execution |
+| `breadcrumb_max_bytes` | Optional | `2048` | Maximum bytes per normalized breadcrumb; minimum `128` |
 
 ```ruby
 Chronos.configure do |config|
@@ -56,6 +59,8 @@ Chronos.configure do |config|
   config.max_retries = 3
   config.backlog_size = 100
   config.circuit_failure_threshold = 5
+  config.context_store = :thread_local
+  config.breadcrumb_capacity = 20
 end
 ```
 

data/docs/data-collected.md

@@ -1,6 +1,6 @@
 # Data collected
 
-Version 0.3 emits only manually submitted exception events. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
+Version 0.4 emits exception events submitted manually or captured by the optional Rack middleware. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
 
 | Data | Default | Source |
 |---|---|---|
@@ -15,8 +15,14 @@ Version 0.3 emits only manually submitted exception events. All fields pass thro
 | Context, parameters, session, user | Optional and sanitized | Explicit capture arguments |
 | Tags and fingerprint | Optional and sanitized | Explicit capture arguments |
 | IPv4 address in supplied text | Anonymized | Explicit capture arguments |
+| Rack method, normalized route, status, duration, request ID, host, query-free path, trace ID | Collected with Rack middleware | Rack environment and local clock |
+| Rack user agent | Disabled by default | `HTTP_USER_AGENT` when middleware option is enabled |
+| Rack controller/action | Collected when already supplied | Explicit Chronos or Action Dispatch environment values |
+| Rack parameters | Collected only when already parsed | Explicit, Rack, or Action Dispatch parameter hashes |
+| Response size | `Content-Length` when present | Rack response headers |
+| Breadcrumbs | Explicit and bounded | Application and Chronos integration |
 
-The gem never collects request bodies, response bodies, cookies, HTTP authorization headers, environment variables in bulk, source code, SQL bind values, database rows, or installed gems in version 0.3.
+The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, source code, SQL bind values, database rows, or installed gems in version 0.4.
 
 The secret `project_key` is an authentication header and is excluded from the JSON payload and logger diagnostics. The envelope field named `project_key` contains the public `project_id` required by the current v1 server contract.
 

data/docs/modules/rack-context.md

@@ -0,0 +1,59 @@
+# Rack integration, execution context, and breadcrumbs
+
+Version 0.4 adds automatic capture through `Chronos::Integrations::Rack::Middleware`. The integration implements the Rack protocol directly and does not require Rack when `chronos-ruby` is loaded. Add the middleware after configuring Chronos:
+
+```ruby
+use Chronos::Integrations::Rack::Middleware,
+    :include_user_agent => false
+```
+
+## Capture behavior
+
+The middleware catches an exception raised by the downstream application, submits it asynchronously, and re-raises the same exception object. A notification or logger failure cannot replace the application failure. An `ensure` boundary clears request context in every outcome.
+
+Captured request fields are method, normalized route, status, duration in milliseconds, request ID, optional user agent, host, query-free path, controller/action when already supplied, approximate response size from `Content-Length`, a generated or supplied trace ID, already-parsed parameters, and application-supplied user context. The final event serializer sanitizes every field before queueing.
+
+The middleware never reads `rack.input`, copies `QUERY_STRING`, parses a body, enumerates a response body, or reads cookies and authorization headers. Parameters are collected only from already-materialized hashes at `rack.request.query_hash`, `action_dispatch.request.query_parameters`, `action_dispatch.request.path_parameters`, or the explicit `chronos.parameters` key. User context is opt-in through `chronos.user`.
+
+Without an explicit `chronos.route` or `action_dispatch.route_uri_pattern`, numeric and UUID path segments are replaced with `:id`. This is a conservative cardinality guard, not a complete router-aware normalizer.
+
+## Context store
+
+`Chronos::Ports::ContextStore` defines `get`, `set`, `clear`, and `with_context`. The legacy default, `Chronos::Adapters::ThreadLocalContextStore`, isolates each thread and restores nested scopes in `ensure`. It deliberately does not propagate state into newly created threads or fibers.
+
+A custom strategy can be selected at configuration time if it implements the complete port:
+
+```ruby
+Chronos.configure do |config|
+  # credentials omitted
+  config.context_store = MyContextStore.new
+end
+```
+
+Application code can add scoped values. Manual notifications issued inside the block inherit them:
+
+```ruby
+Chronos.with_context(:user => {"id" => "customer-42"}) do
+  Chronos.notify(error)
+end
+```
+
+## Breadcrumbs
+
+`Chronos.add_breadcrumb` records an explicit marker in the current execution buffer:
+
+```ruby
+Chronos.add_breadcrumb(
+  :category => "custom",
+  :message => "payment authorization started",
+  :metadata => {"provider" => "example"}
+)
+```
+
+Allowed categories are `custom`, `log`, `request`, `query`, `external_http`, `cache`, and `job`; an unknown value becomes `custom`. No log, SQL, body, cache, job, or external HTTP payload is captured automatically in 0.4. Metadata exists only when the application or a later integration explicitly supplies it.
+
+The default circular buffer keeps the newest 20 entries. Each breadcrumb is normalized to JSON primitives with bounded depth, collections, strings, nodes, and serialized bytes. The entire exception payload still passes through the privacy sanitizer before it can enter the queue or retry backlog.
+
+## Concurrency and limitations
+
+Concurrent Rack threads receive distinct user, parameter, breadcrumb, and trace values. Context does not cross threads automatically, so applications that start their own thread must establish a new scope explicitly. Version 0.4 captures exceptions raised during the initial Rack application call; deferred failures raised only while a server enumerates a streaming response body are not intercepted.

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.3 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.4 makes no unverified speed claim.
 
 Current controls:
 
@@ -16,8 +16,10 @@ Current controls:
 - the circuit breaker suppresses requests during sustained failure;
 - retry backlog capacity is fixed and may be disabled;
 - shutdown and flush have caller-controlled timeouts.
+- request context and breadcrumbs have fixed structural and byte limits;
+- Rack middleware never consumes request or response bodies.
 
-Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. `benchmarks/filtering.rb` measures privacy filtering, while `benchmarks/retry_backlog.rb` measures fixed-memory behavior with an unavailable in-memory transport. Request overhead is not measured because automatic request integration is outside version 0.3.
+Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. `benchmarks/filtering.rb` measures privacy filtering, `benchmarks/retry_backlog.rb` measures fixed-memory outage behavior, and `benchmarks/request_overhead.rb` compares a successful direct Rack-protocol call with the middleware path.
 
 ## Version 0.2 development measurement
 
@@ -51,3 +53,13 @@ A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 with 1,000
 | Open-circuit backlog handling | 88,922 operations/second |
 
 The outage run retained exactly 100 events and rejected 9,900 additional events without growing the backlog. These are single development runs without median or dispersion and are not comparative performance claims.
+
+## Version 0.4 Rack middleware benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
+```
+
+A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 successful Rack-protocol calls. The direct application calls took 0.013272 seconds and middleware calls took 0.539758 seconds, for an estimated 52.649 microseconds of middleware work per request. The fixture uses no network, error capture, or response-body enumeration. This is a single development measurement, not a production latency claim; controlled warmup, median, and dispersion remain required before publishing a performance claim.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.3 sanitizes every exception event before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
+Version 0.4 sanitizes every exception event before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
 
 ## Default policy
 
@@ -13,9 +13,15 @@ Version 0.3 sanitizes every exception event before JSON serialization, queueing,
 | Payment-card candidates that pass the Luhn check | Replaced with `[FILTERED_CARD]` |
 | IPv4 addresses | Last octet replaced with `0` |
 | Unknown Ruby objects | Represented by class name without calling application serialization |
-| Request/response bodies, cookies, HTTP headers, SQL binds, environment variables | Never collected automatically in version 0.3 |
+| Request/response bodies, raw query strings, cookies, authorization headers, SQL binds, environment variables | Never collected automatically in version 0.4 |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.3 does not persist telemetry to disk.
+The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.4 does not persist telemetry to disk.
+
+## Rack context and breadcrumbs
+
+The Rack middleware copies only bounded operational fields and parameter hashes that another component already parsed. It does not read `rack.input` or copy `QUERY_STRING`. User context is opt-in through `chronos.user`, and user agent collection is disabled unless the middleware option enables it.
+
+Breadcrumbs contain category, bounded message, bounded metadata, and timestamp. No raw request, response, SQL, cache, job, log, or external HTTP payload is added automatically. Rack context and breadcrumbs pass through the same sanitizer as manual context before queueing.
 
 Blocklist matching accepts `String`, `Symbol`, and `Regexp`. String and Symbol matching is case-insensitive after punctuation normalization and also protects namespaced keys such as `user_password`.
 

data/docs/troubleshooting.md

@@ -2,7 +2,7 @@
 
 ## Configuration raises an error
 
-Verify `project_id`, `project_key`, and `host`. HTTPS is required while `ssl_verify` is true. Queue size, worker count, payload size, and timeouts must be positive.
+Verify `project_id`, `project_key`, and `host`. HTTPS is required while `ssl_verify` is true. Queue size, worker count, payload size, breadcrumb capacity, and timeouts must be positive. `breadcrumb_max_bytes` must be at least 128.
 
 ## `Chronos.notify` returns false
 
@@ -10,7 +10,15 @@ The agent may be unconfigured, disabled, ignored in the current environment, una
 
 ## `Chronos.notify_sync` returns false
 
-Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and timeout values. Version 0.3 retries only network errors, HTTP `408`, `429`, and `5xx` responses. Inspect `agent.diagnostics` when constructing an agent directly to see retry state, backlog usage, and the circuit state.
+Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and timeout values. The resilience layer retries only network errors, HTTP `408`, `429`, and `5xx` responses. Inspect `agent.diagnostics` when constructing an agent directly to see retry state, backlog usage, and the circuit state.
+
+## Rack exception is not captured
+
+Confirm that `Chronos.configure` runs before the middleware handles requests and that the middleware wraps the application component that raises. Version 0.4 captures exceptions raised by the initial downstream Rack call; an exception raised later while a server enumerates a streaming response body is outside this release. The original exception is always re-raised, so the server log should still show it.
+
+## Context appears missing
+
+The legacy context store is thread-local. A new application-created thread does not inherit context. Establish a new `Chronos.with_context` scope inside that thread, and issue manual notification before the scope exits. For Rack capture, supply user and explicit parameters through the documented environment keys.
 
 ## Events disappear during shutdown
 

data/lib/chronos/adapters/thread_local_context_store.rb

@@ -0,0 +1,52 @@
+module Chronos
+  module Adapters
+    # Stores execution context in the current Ruby thread.
+    #
+    # @responsibility Isolate request context and restore nested scopes reliably.
+    # @motivation Legacy Ruby does not provide a portable fiber-local storage API.
+    # @limits Context does not propagate to new threads or across processes.
+    # @collaborators ContextStore port and Rack middleware.
+    # @thread_safety Each thread owns an independent value; one instance may be shared.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   store.with_context(:request_id => "r1") { store.get }
+    # @errors The previous value is restored in ensure even when the block raises.
+    # @performance Reads and writes are constant-time thread-local operations.
+    class ThreadLocalContextStore
+      def initialize
+        @key = "chronos_context_#{object_id}".freeze
+      end
+
+      def get
+        Thread.current[@key] || {}
+      end
+
+      def set(context)
+        raise ArgumentError, "context must be a Hash" unless context.is_a?(Hash)
+
+        Thread.current[@key] = context
+      end
+
+      def clear
+        Thread.current[@key] = nil
+        nil
+      end
+
+      def with_context(context)
+        previous = Thread.current[@key]
+        set(merge_context(previous || {}, context))
+        yield
+      ensure
+        previous ? Thread.current[@key] = previous : clear
+      end
+
+      private
+
+      def merge_context(current, additional)
+        raise ArgumentError, "context must be a Hash" unless additional.is_a?(Hash)
+
+        current.merge(additional)
+      end
+    end
+  end
+end

data/lib/chronos/agent.rb

@@ -1,10 +1,10 @@
 module Chronos
   # Runtime composition root for the framework-independent Chronos agent.
   #
-  # @responsibility Own transport, resilient delivery pipeline, and the capture use case.
+  # @responsibility Own delivery, capture, execution context, and breadcrumb collaborators.
   # @motivation Keep construction details outside the public module facade.
-  # @limits It does not integrate with Rails, Rack, or job systems.
-  # @collaborators Configuration snapshot, CaptureException, DeliveryPipeline, and NetHttpTransport.
+  # @limits It does not install Rack, Rails, or job integrations automatically.
+  # @collaborators CaptureException, DeliveryPipeline, ContextStore, and BreadcrumbBuffer.
   # @thread_safety Runtime collaborators synchronize mutable state.
   # @compatibility Ruby 2.2.10 through Ruby 2.6.
   # @example
@@ -19,6 +19,10 @@ module Chronos
     def initialize(config, options = {})
       @config = config
       @logger = options[:logger] || Internal::SafeLogger.new(config.logger)
+      @context_store = options[:context_store] || build_context_store(config.context_store)
+      unless Ports::ContextStore.compatible?(@context_store)
+        raise ArgumentError, "context store does not implement the Chronos context-store port"
+      end
       @transport = options[:transport] || Adapters::NetHttpTransport.new(config, @logger)
       unless Ports::Transport.compatible?(@transport)
         raise ArgumentError, "transport does not implement the Chronos transport port"
@@ -36,11 +40,27 @@ module Chronos
     end
 
     def notify(exception, context = {})
-      @capture.call(exception, context)
+      @capture.call(exception, context_for_capture(context))
     end
 
     def notify_sync(exception, context = {})
-      @capture.call_sync(exception, context)
+      @capture.call_sync(exception, context_for_capture(context))
+    end
+
+    def with_context(context = {}, &block)
+      @context_store.with_context(context, &block)
+    end
+
+    def add_breadcrumb(attributes = {})
+      context = @context_store.get
+      buffer = context[:__chronos_breadcrumbs]
+      buffer ||= Core::BreadcrumbBuffer.new(@config.breadcrumb_capacity, @config.breadcrumb_max_bytes)
+      buffer.add(attributes)
+      @context_store.set(context.merge(:__chronos_breadcrumbs => buffer))
+      true
+    rescue StandardError => error
+      @logger.warn("Chronos breadcrumb failed: #{error.class}")
+      false
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
@@ -61,5 +81,34 @@ module Chronos
       details = @delivery_pipeline.diagnostics
       details[:queue].merge(details)
     end
+
+    private
+
+    def build_context_store(strategy)
+      return Adapters::ThreadLocalContextStore.new if strategy == :thread_local
+
+      strategy
+    end
+
+    def context_for_capture(additional)
+      merged = deep_merge(context_hash(@context_store.get), context_hash(additional))
+      buffer = merged.delete(:__chronos_breadcrumbs) || merged.delete("__chronos_breadcrumbs")
+      if buffer.respond_to?(:to_a)
+        merged[:context] = context_hash(merged[:context]).merge("breadcrumbs" => buffer.to_a)
+      end
+      merged
+    rescue StandardError
+      context_hash(additional)
+    end
+
+    def deep_merge(left, right)
+      left.merge(right) do |_key, old_value, new_value|
+        old_value.is_a?(Hash) && new_value.is_a?(Hash) ? deep_merge(old_value, new_value) : new_value
+      end
+    end
+
+    def context_hash(value)
+      value.is_a?(Hash) ? value : {}
+    end
   end
 end

data/lib/chronos/application/capture_exception.rb

@@ -2,9 +2,9 @@ module Chronos
   module Application
     # Orchestrates exception normalization, serialization, queueing, and delivery.
     #
-    # @responsibility Execute the version 0.3 exception capture pipeline.
+    # @responsibility Execute the exception capture pipeline for manual and integration callers.
     # @motivation Keep the public facade and transport adapters free of use-case logic.
-    # @limits It does not implement framework hooks or automatic capture.
+    # @limits Framework hooks remain separate integration adapters.
     # @collaborators NoticeBuilder, PayloadSerializer, and DeliveryPipeline.
     # @thread_safety Collaborators are immutable or synchronized; calls may run concurrently.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.

data/lib/chronos/configuration.rb

@@ -24,6 +24,7 @@ module Chronos
       token access_token refresh_token private_key client_secret cookie set-cookie
       session credit_card card_number cvv cpf cnpj
     ).freeze
+    CONTEXT_STORE_METHODS = [:get, :set, :clear, :with_context].freeze
 
     ATTRIBUTES = [
       :project_id, :project_key, :host, :environment, :app_version,
@@ -35,7 +36,8 @@ module Chronos
       :retry_base_interval, :retry_max_interval, :retry_jitter,
       :backlog_size, :circuit_failure_threshold, :circuit_reset_timeout,
       :remote_configuration, :remote_config_max_bytes, :sampling_rate,
-      :enabled_event_types, :max_remote_send_interval
+      :enabled_event_types, :max_remote_send_interval, :context_store,
+      :breadcrumb_capacity, :breadcrumb_max_bytes
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -57,7 +59,7 @@ module Chronos
       validation_errors.empty?
     end
 
-    def validation_errors
+    def validation_errors # rubocop:disable Metrics/AbcSize
       errors = []
       if enabled
         errors << "project_id is required" if blank?(project_id)
@@ -71,6 +73,7 @@ module Chronos
       errors << "max_payload_size must be a positive integer" unless positive_integer?(max_payload_size)
       errors.concat(resilience_errors)
       errors.concat(privacy_errors)
+      errors.concat(context_errors)
       errors
     end
 
@@ -97,6 +100,9 @@ module Chronos
       @user_agent = "chronos-ruby/#{Chronos::VERSION}"
       @max_payload_size = 1_048_576
       @gzip = false
+      @context_store = :thread_local
+      @breadcrumb_capacity = 20
+      @breadcrumb_max_bytes = 2048
     end
 
     def initialize_privacy_defaults
@@ -187,6 +193,20 @@ module Chronos
       errors
     end
 
+    def context_errors
+      errors = []
+      unless context_store == :thread_local || CONTEXT_STORE_METHODS.all? do |method_name|
+        context_store.respond_to?(method_name)
+      end
+        errors << "context_store must be :thread_local or implement get, set, clear, and with_context"
+      end
+      errors << "breadcrumb_capacity must be a positive integer" unless positive_integer?(breadcrumb_capacity)
+      unless breadcrumb_max_bytes.is_a?(Integer) && breadcrumb_max_bytes >= 128
+        errors << "breadcrumb_max_bytes must be an integer greater than or equal to 128"
+      end
+      errors
+    end
+
     def filter_errors
       return ["filters must be an array"] unless filters.is_a?(Array)
       return [] if filters.all? { |filter| filter.respond_to?(:call) }
@@ -278,7 +298,7 @@ module Chronos
       private
 
       def deep_freeze(value)
-        return value if value.respond_to?(:call)
+        return value if value.respond_to?(:call) || context_store?(value)
 
         case value
         when Hash
@@ -291,6 +311,12 @@ module Chronos
         end
         value.freeze
       end
+
+      def context_store?(value)
+        CONTEXT_STORE_METHODS.all? { |method_name| value.respond_to?(method_name) }
+      rescue StandardError
+        false
+      end
     end
   end
 end

data/lib/chronos/core/breadcrumb.rb

@@ -0,0 +1,126 @@
+require "json"
+require "time"
+
+module Chronos
+  module Core
+    # Immutable, bounded diagnostic marker attached to an execution.
+    #
+    # @responsibility Normalize one breadcrumb without retaining raw application objects.
+    # @motivation Preserve useful events leading to an exception with predictable memory use.
+    # @limits It does not capture logs, SQL, bodies, or HTTP calls automatically.
+    # @collaborators SafeSerializer and BreadcrumbBuffer.
+    # @thread_safety Immutable after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   breadcrumb.to_h #=> {"category"=>"custom", ...}
+    # @errors Unserializable metadata is replaced by SafeSerializer placeholders.
+    # @performance Metadata traversal has strict depth, node, item, and byte limits.
+    class Breadcrumb
+      CATEGORIES = %w(custom log request query external_http cache job).freeze
+
+      def initialize(attributes, clock = nil, max_bytes = 2048)
+        attributes = {} unless attributes.is_a?(Hash)
+        clock ||= proc { Time.now }
+        serializer = SafeSerializer.new(
+          :max_depth => 5, :max_keys => 20, :max_items => 20,
+          :max_string_bytes => 512, :max_nodes => 100
+        )
+        @data = serializer.call(build_data(attributes, clock))
+        @data = compact_data(@data, max_bytes) if JSON.generate(@data).bytesize > max_bytes
+        deep_freeze(@data)
+        freeze
+      end
+
+      def to_h
+        @data
+      end
+
+      private
+
+      def build_data(attributes, clock)
+        category = value(attributes, :category).to_s
+        category = "custom" unless CATEGORIES.include?(category)
+        {
+          "category" => category,
+          "message" => value(attributes, :message).to_s,
+          "metadata" => value(attributes, :metadata) || {},
+          "timestamp" => clock.call.utc.iso8601(6)
+        }
+      end
+
+      def compact_data(data, max_bytes)
+        message_limit = [max_bytes / 4, 32].max
+        compacted = {
+          "category" => data["category"],
+          "message" => SafeSerializer.new.call(data["message"], :max_string_bytes => message_limit),
+          "metadata" => {"_truncated" => true},
+          "timestamp" => data["timestamp"]
+        }
+        trim_compacted_message(compacted, max_bytes)
+      end
+
+      def trim_compacted_message(compacted, max_bytes)
+        while JSON.generate(compacted).bytesize > max_bytes && !compacted["message"].empty?
+          length = [compacted["message"].bytesize - 16, 0].max
+          compacted["message"] = SafeSerializer.new.call(
+            compacted["message"].byteslice(0, length).to_s,
+            :max_string_bytes => length
+          )
+        end
+        compacted
+      end
+
+      def value(attributes, key)
+        attributes.key?(key) ? attributes[key] : attributes[key.to_s]
+      end
+
+      def deep_freeze(value)
+        if value.is_a?(Hash)
+          value.each do |key, child|
+            deep_freeze(key)
+            deep_freeze(child)
+          end
+        elsif value.is_a?(Array)
+          value.each { |child| deep_freeze(child) }
+        end
+        value.freeze
+      end
+    end
+
+    # Fixed-size circular collection of execution breadcrumbs.
+    #
+    # @responsibility Retain only the newest bounded breadcrumbs for one execution.
+    # @motivation Prevent long requests or noisy instrumentation from growing memory indefinitely.
+    # @limits It is process memory only and does not collect events by itself.
+    # @collaborators Breadcrumb and Agent.
+    # @thread_safety Intended for one execution thread; snapshots are immutable values.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   buffer.add(:category => "custom", :message => "started")
+    # @errors Invalid attributes are normalized into a safe breadcrumb.
+    # @performance Add is constant time and storage never exceeds capacity.
+    class BreadcrumbBuffer
+      def initialize(capacity, max_bytes = 2048)
+        raise ArgumentError, "capacity must be a positive integer" unless capacity.is_a?(Integer) && capacity > 0
+
+        @capacity = capacity
+        @max_bytes = max_bytes
+        @items = []
+      end
+
+      def add(attributes)
+        @items.shift if @items.length >= @capacity
+        @items << Breadcrumb.new(attributes, nil, @max_bytes)
+        true
+      end
+
+      def to_a
+        @items.map(&:to_h)
+      end
+
+      def size
+        @items.size
+      end
+    end
+  end
+end

data/lib/chronos/integrations/rack/middleware.rb

@@ -0,0 +1,152 @@
+require "securerandom"
+
+module Chronos
+  module Integrations
+    module Rack
+      # Captures unhandled Rack exceptions while preserving Rack semantics.
+      #
+      # @responsibility Build bounded request context, notify Chronos, and re-raise the original exception.
+      # @motivation Provide automatic error capture without coupling the core to Rack.
+      # @limits It never reads rack.input, enumerates response bodies, or infers Rails routes.
+      # @collaborators Rack application and the Chronos facade or Agent.
+      # @thread_safety Shared instances keep no per-request mutable state.
+      # @compatibility Rack 1.x/2.x protocol; Ruby 2.2.10 through Ruby 2.6.
+      # @example
+      #   use Chronos::Integrations::Rack::Middleware
+      # @errors Notification failures are contained; the application exception is always re-raised.
+      # @performance Adds bounded hash construction and monotonic-clock reads per request.
+      class Middleware
+        def initialize(app, options = {})
+          @app = app
+          @notifier = options[:notifier] || Chronos
+          @include_user_agent = options[:include_user_agent] || false
+          @clock = options[:clock] || proc { monotonic_time }
+        end
+
+        def call(env)
+          started_at = @clock.call
+          base = request_capture_context(env)
+          @notifier.with_context(base) do
+            add_request_breadcrumb("request started", base)
+            call_application(env, base, started_at)
+          end
+        end
+
+        private
+
+        def call_application(env, base, started_at)
+          response = @app.call(env)
+          status = response[0]
+          headers = response[1]
+          add_request_breadcrumb("request completed", dynamic_request_context(base, status, headers, started_at))
+          response
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          context = dynamic_request_context(base, 500, nil, started_at)
+          notify_safely(error, context)
+          raise
+        end
+
+        def notify_safely(error, context)
+          @notifier.notify(error, context)
+        rescue StandardError
+          false
+        end
+
+        def request_capture_context(env)
+          request = request_values(env)
+          {
+            :context => {"request" => request, "trace_id" => trace_id(env)},
+            :parameters => parameters(env),
+            :user => hash_value(env["chronos.user"])
+          }
+        end
+
+        def request_values(env)
+          values = {
+            "method" => env["REQUEST_METHOD"].to_s,
+            "route" => normalized_route(env),
+            "request_id" => request_id(env),
+            "host" => (env["HTTP_HOST"] || env["SERVER_NAME"]).to_s,
+            "path" => env["PATH_INFO"].to_s,
+            "controller" => controller_action(env, "controller"),
+            "action" => controller_action(env, "action")
+          }
+          values["user_agent"] = env["HTTP_USER_AGENT"].to_s if @include_user_agent
+          values
+        end
+
+        def dynamic_request_context(base, status, headers, started_at)
+          request = base[:context]["request"].merge(
+            "status" => status.to_i,
+            "duration_ms" => ((@clock.call - started_at) * 1000.0).round(3),
+            "response_size" => response_size(headers)
+          )
+          {:context => base[:context].merge("request" => request)}
+        end
+
+        def parameters(env)
+          result = {}
+          [env["rack.request.query_hash"], env["action_dispatch.request.query_parameters"],
+           env["action_dispatch.request.path_parameters"], env["chronos.parameters"]].each do |candidate|
+            result.merge!(candidate) if candidate.is_a?(Hash)
+          end
+          result
+        rescue StandardError
+          {}
+        end
+
+        def normalized_route(env)
+          explicit = env["chronos.route"] || env["action_dispatch.route_uri_pattern"]
+          return explicit.to_s unless explicit.to_s.empty?
+
+          env["PATH_INFO"].to_s.split("/").map { |part| dynamic_segment?(part) ? ":id" : part }.join("/")
+        end
+
+        def dynamic_segment?(segment)
+          segment =~ /\A\d+\z/ || segment =~ /\A[0-9a-f]{8}-[0-9a-f-]{27,}\z/i
+        end
+
+        def controller_action(env, key)
+          explicit = env["chronos.#{key}"]
+          paths = env["action_dispatch.request.path_parameters"]
+          explicit || (paths[key] if paths.is_a?(Hash)) || (paths[key.to_sym] if paths.is_a?(Hash))
+        end
+
+        def request_id(env)
+          env["chronos.request_id"] || env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+        end
+
+        def trace_id(env)
+          env["chronos.trace_id"] || SecureRandom.uuid
+        end
+
+        def response_size(headers)
+          return nil unless headers.respond_to?(:each)
+
+          pair = headers.find { |key, _value| key.to_s.casecmp("content-length").zero? }
+          pair ? pair[1].to_i : nil
+        rescue StandardError
+          nil
+        end
+
+        def add_request_breadcrumb(message, context)
+          request = context[:context]["request"]
+          @notifier.add_breadcrumb(
+            :category => "request", :message => message,
+            :metadata => {"method" => request["method"], "route" => request["route"], "status" => request["status"]}
+          )
+        end
+
+        def hash_value(value)
+          value.is_a?(Hash) ? value : {}
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+    end
+  end
+end

data/lib/chronos/integrations/rack.rb

@@ -0,0 +1,12 @@
+module Chronos
+  module Integrations
+    # Rack protocol integrations that do not require Rack at gem load time.
+    #
+    # @responsibility Namespace Rack-compatible middleware.
+    # @motivation Permit optional use without adding a runtime Rack dependency.
+    # @limits It does not provide Rails-specific route discovery.
+    # @thread_safety Middleware instances may be shared by concurrent Rack threads.
+    # @compatibility Rack 1.x and 2.x protocol shapes on Ruby 2.2.10 through Ruby 2.6.
+    module Rack; end
+  end
+end

data/lib/chronos/integrations.rb

@@ -0,0 +1,10 @@
+module Chronos
+  # Optional framework entry points kept outside the framework-independent core.
+  #
+  # @responsibility Namespace integration adapters such as Rack middleware.
+  # @motivation Keep framework loading optional for plain Ruby applications.
+  # @limits Integrations may depend only on documented public agent behavior.
+  # @thread_safety Each integration documents its own guarantees.
+  # @compatibility Version 0.4 supports Rack protocol behavior on Ruby 2.2.10 through 2.6.
+  module Integrations; end
+end

data/lib/chronos/ports/context_store.rb

@@ -0,0 +1,22 @@
+module Chronos
+  module Ports
+    # Conceptual storage port for execution-scoped context.
+    #
+    # @responsibility Define get, set, clear, and scoped context behavior.
+    # @motivation Let integrations isolate request state without depending on a thread implementation.
+    # @limits The port does not prescribe thread, fiber, or distributed propagation semantics.
+    # @collaborators Agent and context-store adapters.
+    # @thread_safety Implementations must isolate concurrent executions.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Ports::ContextStore.compatible?(store) #=> true
+    # @errors Compatibility checks never invoke application methods.
+    module ContextStore
+      REQUIRED_METHODS = [:get, :set, :clear, :with_context].freeze
+
+      def self.compatible?(object)
+        REQUIRED_METHODS.all? { |method_name| object.respond_to?(method_name) }
+      end
+    end
+  end
+end

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.3.0.pre.1".freeze
+  VERSION = "0.4.0.pre.1".freeze
 end

data/lib/chronos.rb

@@ -16,23 +16,29 @@ require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
 require "chronos/core/payload_serializer"
 require "chronos/ports/transport"
+require "chronos/ports/context_store"
 require "chronos/internal/safe_logger"
 require "chronos/internal/bounded_queue"
 require "chronos/internal/memory_backlog"
 require "chronos/internal/worker_pool"
 require "chronos/adapters/net_http_transport"
+require "chronos/adapters/thread_local_context_store"
+require "chronos/core/breadcrumb"
 require "chronos/application/retry_policy"
 require "chronos/application/circuit_breaker"
 require "chronos/application/remote_configuration"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
 require "chronos/agent"
+require "chronos/integrations"
+require "chronos/integrations/rack"
+require "chronos/integrations/rack/middleware"
 
 # Framework-independent public facade for the Chronos Ruby agent.
 #
 # @responsibility Configure the agent and expose its small lifecycle API.
 # @motivation Give applications a stable entry point while internals evolve.
-# @limits Version 0.3 captures Ruby exceptions manually; integrations arrive later.
+# @limits Version 0.4 captures Rack failures but does not install middleware automatically.
 # @collaborators Configuration and Agent.
 # @thread_safety Agent replacement and lookup are protected by a mutex.
 # @compatibility Ruby 2.2.10 through Ruby 2.6.
@@ -75,6 +81,20 @@ module Chronos
       false
     end
 
+    def with_context(context = {})
+      agent = current_agent
+      return yield unless agent
+
+      agent.with_context(context) { yield }
+    end
+
+    def add_breadcrumb(attributes = {})
+      agent = current_agent
+      agent ? agent.add_breadcrumb(attributes) : false
+    rescue StandardError
+      false
+    end
+
     def configured?
       !current_agent.nil?
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0.pre.1
+  version: 0.4.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -87,6 +87,7 @@ files:
 - README.md
 - SECURITY.md
 - contracts/event-v1.schema.json
+- contracts/rack-context-v1.schema.json
 - docs/adr/ADR-001-core-and-integrations.md
 - docs/adr/ADR-002-version-lines.md
 - docs/adr/ADR-003-net-http-legacy-transport.md
@@ -94,6 +95,7 @@ files:
 - docs/adr/ADR-005-sanitize-before-backlog.md
 - docs/adr/ADR-006-versioned-event-contract.md
 - docs/adr/ADR-011-bounded-resilience-and-remote-control.md
+- docs/adr/ADR-012-rack-context-isolation.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -102,6 +104,7 @@ files:
 - docs/modules/async-queue.md
 - docs/modules/configuration.md
 - docs/modules/notice-pipeline.md
+- docs/modules/rack-context.md
 - docs/modules/remote-configuration.md
 - docs/modules/retry-backlog.md
 - docs/modules/sanitization.md
@@ -113,6 +116,7 @@ files:
 - lib/chronos.rb
 - lib/chronos/adapters.rb
 - lib/chronos/adapters/net_http_transport.rb
+- lib/chronos/adapters/thread_local_context_store.rb
 - lib/chronos/agent.rb
 - lib/chronos/application.rb
 - lib/chronos/application/capture_exception.rb
@@ -123,6 +127,7 @@ files:
 - lib/chronos/configuration.rb
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
+- lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/notice.rb
 - lib/chronos/core/notice_builder.rb
@@ -132,12 +137,16 @@ files:
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
 - lib/chronos/errors.rb
+- lib/chronos/integrations.rb
+- lib/chronos/integrations/rack.rb
+- lib/chronos/integrations/rack/middleware.rb
 - lib/chronos/internal.rb
 - lib/chronos/internal/bounded_queue.rb
 - lib/chronos/internal/memory_backlog.rb
 - lib/chronos/internal/safe_logger.rb
 - lib/chronos/internal/worker_pool.rb
 - lib/chronos/ports.rb
+- lib/chronos/ports/context_store.rb
 - lib/chronos/ports/transport.rb
 - lib/chronos/ruby.rb
 - lib/chronos/ruby/version.rb