chronos-ruby 0.5.0.pre.1 → 0.6.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8475c8f2a946a1c0e512d37b01d9931a47df75c2446c6c898a8d8a795db4aff3
-  data.tar.gz: 533465780682cdbfad58087cae0458c513d7086828350587728b970093be5264
+  metadata.gz: 5ad7bc09dd58b0476b65687d0b7c695bdc5e82c898f882fc82ed2e87eb352b79
+  data.tar.gz: 527383d76a4432bc16f48d2a476d7c2398d66f5b891bbe666d1e0ceba9dc9959
 SHA512:
-  metadata.gz: 456b339239a6fdd7b11706e2cd2c4be59dbf11e015354e95f60a7ebffb07305f66df1bdc79a77c7b8f9a776b9ba66325f288af6d954b5027808d1e85d1992097
-  data.tar.gz: 29126344b372211a3940eb7b58a66ae8e10f5769090081a9dfefaedee4001fdc949a03b0511b3492ae783e1ba0d99b24f1adbfba6b9c8775123e1b03f88e6fa2
+  metadata.gz: 24bf5ed37de64c34a82fd0b98f3e1323cac14c2392fa0d6a01dbcd24d48a69a52100a6127a79b2567314bcf2c464b354fee226ab19bba08ea384bfb3ec8a12f9
+  data.tar.gz: 1696953512893c9d3eecc23d361b35c5434df7dda25e33a1fe6321b5c25ae4d9e03a2a843bd76e9c327130be2cba2a6c7a9766d70a6f068007b24959aa3cfdc0

data/CHANGELOG.md

@@ -6,11 +6,33 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ### Fixed
 
+- `WorkerPool#flush` no longer returns before a worker marks a just-popped event as active;
 - release publishing now updates RubyGems to a Ruby 2.6-compatible version that supports `GEM_HOST_API_KEY`.
 - Updated the legacy development toolchain to non-vulnerable Rake and RuboCop versions.
 - 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.6.0.pre.1] - 2026-07-20
+
+### Added
+
+- optional Sidekiq 4/5 client and server middleware loaded through `chronos/sidekiq`;
+- versioned trace/request context propagation beside, never inside, public job arguments;
+- Sidekiq class, queue, JID, retry count, duration, calculable latency, bounded arguments, tags, status, and error telemetry;
+- shared per-job exception deduplication for nested Sidekiq and Active Job capture paths;
+- Sidekiq payload contract, unit/integration tests, executable example, benchmark, module documentation, and ADR-014.
+
+### Changed
+
+- version advanced to `0.6.0.pre.1`;
+- the public facade exposes bounded propagation context for optional process-boundary integrations.
+
+### Known limitations
+
+- Sidekiq 4/5 remains `Best effort` until dedicated real-gem matrix jobs pass;
+- Active Job context propagation, Resque, and Delayed Job remain subsequent version 0.6 increments;
+- Sidekiq argument capture is automatic, though strictly bounded and sanitized.
+
 ## [0.4.0.pre.1] - 2026-07-20
 
 ### Added

data/README.md

@@ -1,10 +1,10 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors and bounded telemetry to Chronos. Version 0.5 adds legacy Rails 4.2 and 5.2 installation, controller exception deduplication, and allowlisted request, query, job, and cache events to the Rack, privacy, and resilience foundations from earlier releases.
+Chronos Ruby is the framework-independent client for sending Ruby application errors and bounded telemetry to Chronos. Version 0.6 starts legacy worker support with Sidekiq 4/5 middleware, cross-process trace context, bounded job telemetry, and exception deduplication on top of the Rails, Rack, privacy, and resilience foundations from earlier releases.
 
 ## What the gem collects
 
-For each exception, version 0.5 can collect:
+For each exception, version 0.6 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -31,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.5.0.pre.1"
+gem "chronos-ruby", "0.6.0.pre.1"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -52,7 +52,7 @@ gem install chronos-ruby --pre
 Version 0.5 exposes Rails support explicitly, keeping Rails and ActiveSupport out of plain Ruby applications:
 
 ```ruby
-gem "chronos-ruby", "0.5.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.6.0.pre.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -172,7 +172,16 @@ Version 0.5 emits bounded `request`, `query`, `job`, and `cache` events from pub
 
 ## Sidekiq and Active Job
 
-Version 0.5 records bounded Active Job execution telemetry when Active Job is available. It includes the job class, queue, and duration, but excludes job IDs and arguments. Sidekiq-specific integration is not implemented.
+Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
+
+```ruby
+gem "sidekiq", "~> 5.0"
+gem "chronos-ruby", "0.6.0.pre.1", :require => "chronos/sidekiq"
+```
+
+The client middleware propagates only trace/request identifiers in a versioned Sidekiq-envelope field and never changes worker arguments. The server records class, queue, JID, retry count, duration, calculable queue latency, bounded arguments/tags, status, and error class. Values pass through the shared sanitizer before delivery. Failed jobs are notified once and the original exception is re-raised. See [Sidekiq 4/5 legacy integration](docs/modules/sidekiq-legacy.md).
+
+The Rails subscriber continues to record basic Active Job class, queue, and duration. Full Active Job context propagation plus optional Resque and Delayed Job adapters are subsequent version 0.6 increments.
 
 ## Deploy tracking
 
@@ -257,7 +266,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.5 benchmarks with:
+Run the version 0.6 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -267,13 +276,14 @@ 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
 bundle _1.17.3_ exec ruby benchmarks/rails_notifications.rb
+bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.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.5 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.6 does not claim API compatibility or automatic replacement.
 
 ## Local development
 

data/contracts/sidekiq-job-v1.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/sidekiq-job-v1.schema.json",
+  "title": "Chronos Sidekiq job payload v1",
+  "type": "object",
+  "required": ["kind", "class", "queue", "duration_ms", "status"],
+  "properties": {
+    "kind": {"const": "sidekiq"},
+    "class": {"type": "string"},
+    "queue": {"type": "string"},
+    "jid": {"type": "string"},
+    "duration_ms": {"type": "number", "minimum": 0},
+    "queue_latency_ms": {"type": ["number", "null"], "minimum": 0},
+    "retry_count": {"type": "integer", "minimum": 0},
+    "arguments": {"type": "array", "maxItems": 20},
+    "arguments_truncated": {"type": "boolean"},
+    "tags": {"type": "array", "maxItems": 20},
+    "status": {"enum": ["completed", "failed"]},
+    "error_class": {"type": "string"}
+  }
+}

data/docs/adr/ADR-014-sidekiq-envelope-context.md

@@ -0,0 +1,27 @@
+# ADR-014 — Sidekiq context in the job envelope
+
+## Status
+
+Accepted for version 0.6.
+
+## Context
+
+Sidekiq clients and servers usually run in different processes. Chronos needs correlation without changing the worker's public arguments, opening per-job resources, or allowing nested Active Job and Sidekiq hooks to duplicate the same exception.
+
+## Decision
+
+Use Sidekiq 4/5 public client and server middleware. Store a versioned `chronos` object beside `args`, containing only enqueue time, trace ID, and request ID. Never append metadata to `args`. On the server, establish a job execution context with a shared exception-deduplication map, emit bounded job telemetry, notify failures through `notify_once`, and re-raise the original exception. Do not install a global Sidekiq error handler.
+
+Limit job arguments before the common sanitizer and serializer: 20 top-level arguments, 20 items per collection, depth four, and 512 bytes per string. Sanitization remains mandatory before queueing, retry, backlog, or transport.
+
+## Alternatives
+
+Appending a context argument was rejected because it changes worker arity and application-visible data. A process-global context was rejected because concurrent jobs would leak correlation. A global error handler plus server middleware was rejected because it creates duplicate capture paths. Per-job delivery threads or Redis connections were rejected because lifecycle and resource ownership belong to Sidekiq and the existing bounded agent.
+
+## Positive consequences
+
+Worker signatures remain compatible, cross-process correlation is bounded, nested integrations share deduplication, and Sidekiq retains retry semantics.
+
+## Negative consequences
+
+The Sidekiq envelope grows slightly, only two context identifiers propagate, and automatic argument collection still requires application privacy review.

data/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.5 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.6 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -16,6 +16,8 @@ flowchart TB
   Context --> ThreadLocal[Adapters / ThreadLocalContextStore]
   Rails[Chronos Rails / Railtie and subscribers] --> Facade
   Rails --> Notifications[ActiveSupport Notifications]
+  Sidekiq[Integrations / Sidekiq client and server middleware] --> Facade
+  Sidekiq --> Envelope[Versioned job-envelope context]
   Application --> Telemetry[Core / TelemetryEvent]
 ```
 
@@ -28,6 +30,7 @@ flowchart TB
 - Internal contains private concurrency and diagnostic mechanisms.
 - Integrations contain optional framework entry points and never enter the domain boundary.
 - `Chronos::Rails` contains the optional Railtie, installer, generator, and public-notification adapters.
+- `Chronos::Integrations::Sidekiq` contains optional Sidekiq 4/5 middleware and bounded job normalization.
 
 The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and job libraries must not be required by the core.
 
@@ -41,6 +44,8 @@ An exception becomes an immutable notice. `Sanitizer` removes sensitive values b
 
 Rails timings become immutable `TelemetryEvent` values. `CaptureTelemetry` applies the remote/local event policy, `TelemetrySerializer` sanitizes the allowlisted payload, and the resulting `SerializedEvent` enters the same delivery pipeline. Rails classes are loaded only through `chronos/rails`; the core never requires Rails or ActiveSupport.
 
+Sidekiq client middleware writes a versioned, allowlisted trace/request context beside the job's public arguments. Server middleware restores a job scope, limits arguments and tags, emits one job telemetry event, and routes a failure through the existing notice pipeline before re-raising it. Sidekiq retains queue, retry, thread, and connection lifecycle ownership.
+
 ## Failure policy
 
 Explicit invalid configuration raises `Chronos::ConfigurationError`. Capture, serialization, logger, worker, retry, circuit, TLS, network, HTTP, and remote-policy failures do not escape into the host application. They produce `false`, a classified transport result, a bounded state transition, or a bounded logger diagnostic.

data/docs/compatibility.md

@@ -11,8 +11,14 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 | 2.6.10 | Rails 5.2 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
 | 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
 
+| Ruby | Sidekiq integration | Status | Evidence |
+|---|---|---|---|
+| 2.2.10–2.6 | Sidekiq 4 / 5 | Best effort | Middleware unit/integration contracts; dedicated real-gem matrix pending |
+
 Version 0.5 includes Rails 4.2 and 5.2 applications plus a dedicated matrix, but this document conservatively keeps the combinations at `Best effort` until all release-gate evidence, including fake-server payload validation, is green. Rails 5.0 uses the same feature-detected public APIs but does not yet have its own example application.
 
+Version `0.6.0.pre.1` uses the public Sidekiq 4/5 middleware signatures and remains `Best effort` until dedicated jobs exercise both real gem versions across their valid Ruby combinations.
+
 Status meanings:
 
 - Supported: the complete required compatibility gate passes.

data/docs/data-collected.md

@@ -1,6 +1,6 @@
 # Data collected
 
-Version 0.5 emits exception, request, query, job, and cache events. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
+Version 0.6 emits exception, request, query, job, and cache events. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
 
 | Data | Default | Source |
 |---|---|---|
@@ -27,9 +27,14 @@ Version 0.5 emits exception, request, query, job, and cache events. All fields p
 | SQL operation name, cached flag, duration | Collected; SQL text omitted | `sql.active_record` |
 | Mailer/action and duration | Collected; message content omitted | `deliver.action_mailer` |
 | Active Job class, queue, duration | Collected when available; arguments omitted | `perform.active_job` |
+| Sidekiq class, queue, JID, retry count, duration, status, error class | Collected with optional middleware | Sidekiq job envelope and local clock |
+| Sidekiq queue latency | Collected when enqueue time is available | Sidekiq or Chronos envelope timestamp |
+| Sidekiq arguments | Collected, sanitized, and bounded | First 20 job arguments; collections/depth/strings limited |
+| Sidekiq tags | Collected and bounded | Job payload or public worker options |
+| Sidekiq trace/request IDs | Propagated when present; trace generated otherwise | Chronos job-envelope metadata |
 | Cache operation, store, hit flag, duration | Collected; key/value omitted | ActiveSupport cache notifications |
 
-The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, source code, raw SQL, SQL bind values, database rows, cache keys/values, mail bodies/recipients, job IDs/arguments, or installed gems in version 0.5.
+The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, source code, raw SQL, SQL bind values, database rows, cache keys/values, mail bodies/recipients, or installed gems. Sidekiq JIDs and bounded arguments are the explicit version 0.6 exception to the earlier job-ID/argument exclusion.
 
 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/rails-legacy.md

@@ -57,4 +57,4 @@ The repository contains independent applications under `examples/rails-4.2` and
 
 ## Limits
 
-Version 0.5 emits individual bounded timings. It does not aggregate APM metrics, capture SQL text, calculate query fingerprints, or provide Sidekiq integration. Those belong to later versions in the development order.
+Version 0.5 emits individual bounded timings. It does not aggregate APM metrics, capture SQL text, or calculate query fingerprints. Sidekiq support is a separate optional integration beginning in version 0.6; full Active Job propagation remains a later 0.6 increment.

data/docs/modules/sidekiq-legacy.md

@@ -0,0 +1,23 @@
+# Sidekiq 4/5 legacy integration
+
+Version `0.6.0.pre.1` starts the legacy jobs line with optional Sidekiq 4 and 5 client and server middleware. Load it after declaring Sidekiq:
+
+```ruby
+gem "sidekiq", "~> 5.0"
+gem "chronos-ruby", "0.6.0.pre.1", :require => "chronos/sidekiq"
+```
+
+`chronos/sidekiq` installs middleware through the public `configure_client` and `configure_server` APIs. It does nothing when Sidekiq is unavailable, and the core gem never requires Sidekiq. Installation adds no Chronos thread or Redis/database connection per job; delivery continues through the agent's existing fixed worker pool.
+
+The client middleware adds a top-level `chronos` metadata object to the Sidekiq envelope. It never changes the public `args` array. Only `trace_id` and `request_id` propagate, with schema version and enqueue time. The server scopes that context for the worker, measures duration and calculable queue latency, and emits one `job` event.
+
+Collected Sidekiq fields are worker class, queue, JID, retry count, duration, queue latency, status, error class, bounded tags, and bounded arguments. At most 20 top-level arguments, 20 values per nested collection, four levels, and 512 bytes per string are traversed. Arguments then pass through the standard sensitive-key/content sanitizer before queueing. Limits reduce exposure and resource use but do not make unnecessary personal data safe to collect.
+
+On failure, the server middleware records failed-job telemetry, invokes `notify_once`, and re-raises the identical exception so Sidekiq retains ownership of retries and failure handlers. A shared execution marker prevents a nested Active Job hook and the Sidekiq middleware from sending the same exception twice. Chronos does not install an additional global Sidekiq error handler.
+
+Known limitations for this first 0.6 prerelease:
+
+- the compatibility contract uses Sidekiq 4/5 public middleware signatures; dedicated real Sidekiq matrix jobs must pass before status becomes `Supported`;
+- Active Job propagation, Resque, and Delayed Job are subsequent 0.6 increments;
+- argument collection is automatic in this prerelease; applications should avoid placing secrets or unnecessary personal data in job arguments;
+- context propagation is limited to trace and request identifiers.

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.5 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.6 makes no unverified speed claim.
 
 Current controls:
 
@@ -19,6 +19,7 @@ Current controls:
 - request context and breadcrumbs have fixed structural and byte limits;
 - Rack middleware never consumes request or response bodies.
 - Rails subscribers copy only small allowlisted field sets and never copy raw SQL or job arguments.
+- Sidekiq middleware creates no per-job thread or connection and bounds arguments, collections, nesting, strings, and tags before telemetry capture.
 
 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, `benchmarks/request_overhead.rb` compares Rack-protocol calls, and `benchmarks/rails_notifications.rb` isolates subscriber normalization overhead.
 
@@ -76,3 +77,13 @@ 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.
+
+## Version 0.6 Sidekiq middleware benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
+```
+
+The benchmark executes client context injection and successful server normalization with a no-op notifier. It includes bounded argument handling and clock reads, but excludes Sidekiq/Redis, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.5 sanitizes exception and framework telemetry 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.6 sanitizes exception and framework telemetry 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,14 +13,19 @@ Version 0.5 sanitizes exception and framework telemetry before JSON serializatio
 | 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, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, job arguments, environment variables | Never collected automatically in version 0.5 |
+| Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, environment variables | Never collected automatically |
+| Sidekiq arguments | Collected automatically, limited before sanitization, then redacted by the common policy |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.5 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.6 does not persist telemetry to disk.
 
 ## Rails telemetry
 
 Rails subscribers use per-notification allowlists. SQL events retain only the operation name, cached flag, and duration; cache events omit key and value; mailer events omit addresses and content; Active Job events omit job ID and arguments; view identifiers are reduced to basenames. Controller parameters are sanitized by the normal payload pipeline before queueing.
 
+## Sidekiq jobs
+
+The optional Sidekiq middleware is the only version 0.6 integration that automatically reads job arguments. It traverses at most 20 top-level arguments, 20 items per nested collection, four levels, and 512 bytes per string. These structural limits run before the common key and content sanitizer. Trace propagation contains only trace and request identifiers. Do not place credentials or unnecessary personal, health, or financial data in job arguments; configure application-specific blocklist keys and audit representative synthetic payloads before enabling production delivery.
+
 ## 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.

data/docs/troubleshooting.md

@@ -24,6 +24,14 @@ Require `chronos/rails` from the generated initializer and confirm it runs befor
 
 This is intentional. Version 0.5 records SQL operation name/duration and cache operation/store/hit status without raw statements, binds, keys, or values. These omissions are privacy and cardinality boundaries, not capture failures.
 
+## Sidekiq telemetry is missing
+
+Require `chronos/sidekiq` after Sidekiq is available and configure Chronos before jobs run. The entry point uses Sidekiq's public client/server middleware configuration and remains optional. Requiring only `chronos` or `chronos/rails` does not load Sidekiq. A job already enqueued before client middleware installation may lack propagated trace context, but server timing and failure capture can still run.
+
+## A failed Sidekiq job appears twice
+
+The bundled middleware does not install a global error handler and uses `notify_once` inside a shared job scope. Check for application-installed Chronos calls or third-party global handlers outside that scope. Keep a single bundled server middleware entry in the Sidekiq chain.
+
 ## 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.

data/lib/chronos/agent.rb

@@ -67,6 +67,21 @@ module Chronos
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
 
+    # Returns the correlation subset safe for an integration-owned process boundary.
+    def propagation_context
+      current = context_hash(@context_store.get)
+      nested = context_hash(current[:context] || current["context"])
+      request = context_hash(nested["request"] || nested[:request])
+      values = {
+        "trace_id" => nested["trace_id"] || nested[:trace_id],
+        "request_id" => nested["request_id"] || nested[:request_id] ||
+                        request["request_id"] || request[:request_id]
+      }
+      values.delete_if { |_key, value| value.to_s.empty? }
+    rescue StandardError
+      {}
+    end
+
     def notify_once(exception, context = {})
       execution = @context_store.get
       captured = execution[:__chronos_captured_exceptions] || {}

data/lib/chronos/integrations/job_payload.rb

@@ -0,0 +1,72 @@
+module Chronos
+  module Integrations
+    # Builds bounded job metadata before the shared privacy serializer runs.
+    #
+    # @responsibility Limit job arguments, tags, strings, containers, and nesting.
+    # @motivation Worker payloads are application-controlled and may be very large.
+    # @limits It limits values but deliberately leaves redaction to Core::Sanitizer.
+    # @collaborators Sidekiq middleware and the Chronos telemetry pipeline.
+    # @thread_safety Instances keep no mutable state and may be shared.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   JobPayload.new.arguments(["account-1"])
+    # @errors Unreadable values become bounded class-name placeholders.
+    # @performance Traversal is capped by argument, collection, depth, and string limits.
+    class JobPayload
+      MAX_ARGUMENTS = 20
+      MAX_COLLECTION_ITEMS = 20
+      MAX_DEPTH = 4
+      MAX_STRING_BYTES = 512
+
+      def arguments(values)
+        source = values.is_a?(Array) ? values : []
+        [source.first(MAX_ARGUMENTS).map { |value| limit(value, 0) }, source.length > MAX_ARGUMENTS]
+      rescue StandardError
+        [[], true]
+      end
+
+      def tags(values)
+        Array(values).first(MAX_COLLECTION_ITEMS).map { |value| limit_string(value.to_s) }
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def limit(value, depth)
+        return "[TRUNCATED]" if depth >= MAX_DEPTH
+
+        case value
+        when Hash
+          limit_hash(value, depth)
+        when Array
+          value.first(MAX_COLLECTION_ITEMS).map { |child| limit(child, depth + 1) }
+        when String
+          limit_string(value)
+        when NilClass, TrueClass, FalseClass, Numeric
+          value
+        else
+          limit_string(value.to_s)
+        end
+      rescue StandardError
+        "[UNREADABLE]"
+      end
+
+      def limit_hash(value, depth)
+        result = {}
+        value.to_a.first(MAX_COLLECTION_ITEMS).each do |key, child|
+          result[limit_string(key.to_s)] = limit(child, depth + 1)
+        end
+        result
+      end
+
+      def limit_string(value)
+        return value if value.bytesize <= MAX_STRING_BYTES
+
+        value.byteslice(0, MAX_STRING_BYTES) + "[TRUNCATED]"
+      rescue StandardError
+        "[UNREADABLE]"
+      end
+    end
+  end
+end

data/lib/chronos/integrations/sidekiq.rb

@@ -0,0 +1,258 @@
+require "securerandom"
+require "chronos/integrations/job_payload"
+
+module Chronos
+  module Integrations
+    # Optional Sidekiq 4/5 middleware integration for the legacy Chronos line.
+    #
+    # @responsibility Install client/server middleware and namespace worker telemetry.
+    # @motivation Sidekiq jobs need process-boundary context and failure capture.
+    # @limits It does not own Sidekiq lifecycle, Redis connections, retries, or threads.
+    # @collaborators Sidekiq public middleware configuration and Chronos facade.
+    # @thread_safety Installation is mutex-protected; middleware instances are stateless.
+    # @compatibility Sidekiq 4.x and 5.x; Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Integrations::Sidekiq.install
+    # @errors Missing Sidekiq or configuration failures return false.
+    # @performance Adds bounded payload normalization and two clock reads per performed job.
+    module Sidekiq
+      CONTEXT_KEY = "chronos".freeze
+      CONTEXT_SCHEMA_VERSION = "1.0".freeze
+
+      @mutex = Mutex.new
+      @installed = false
+
+      class << self
+        def install(sidekiq = nil, notifier = Chronos)
+          library = sidekiq || (::Sidekiq if defined?(::Sidekiq))
+          return false unless library
+
+          @mutex.synchronize do
+            return false if @installed
+
+            configure_client(library, notifier)
+            configure_server(library, notifier)
+            @installed = true
+          end
+          true
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def configure_client(library, notifier)
+          return unless library.respond_to?(:configure_client)
+
+          library.configure_client do |config|
+            next unless config.respond_to?(:client_middleware)
+
+            config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+          end
+        end
+
+        def configure_server(library, notifier)
+          return unless library.respond_to?(:configure_server)
+
+          library.configure_server do |config|
+            if config.respond_to?(:client_middleware)
+              config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+            end
+            if config.respond_to?(:server_middleware)
+              config.server_middleware { |chain| chain.add(ServerMiddleware, :notifier => notifier) }
+            end
+          end
+        end
+      end
+
+      # Adds a small allowlisted Chronos context to the Sidekiq job envelope.
+      #
+      # @responsibility Propagate trace/request identifiers without modifying `args`.
+      # @motivation Client and server usually execute in different processes.
+      # @limits It does not capture arguments, enqueue errors, or application context fields.
+      # @collaborators Chronos propagation context and Sidekiq client middleware chain.
+      # @thread_safety Calls allocate their own hashes and may execute concurrently.
+      # @compatibility Sidekiq 4.x/5.x client middleware signature.
+      # @example
+      #   ClientMiddleware.new.call(MyWorker, job, "default") { push(job) }
+      # @errors Context failures are contained and the enqueue chain still runs.
+      # @performance Adds one bounded hash to the job payload; opens no connection or thread.
+      class ClientMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { Time.now.to_f }
+        end
+
+        def call(_worker_class, job, _queue, _redis_pool = nil)
+          add_context(job)
+          yield
+        end
+
+        private
+
+        def add_context(job)
+          return unless job.is_a?(Hash)
+
+          context = propagation_context
+          context["trace_id"] = SecureRandom.uuid if context["trace_id"].to_s.empty?
+          job[CONTEXT_KEY] = {
+            "schema_version" => CONTEXT_SCHEMA_VERSION,
+            "enqueued_at" => @clock.call.to_f,
+            "context" => context
+          }
+        rescue StandardError
+          nil
+        end
+
+        def propagation_context
+          return {} unless @notifier.respond_to?(:propagation_context)
+
+          source = @notifier.propagation_context
+          return {} unless source.is_a?(Hash)
+
+          %w(trace_id request_id).each_with_object({}) do |key, result|
+            value = source[key] || source[key.to_sym]
+            result[key] = value.to_s unless value.to_s.empty?
+          end
+        end
+      end
+
+      # Captures Sidekiq execution timing and failures around the worker call.
+      #
+      # @responsibility Scope propagated context, emit one job event, notify failures once, and re-raise.
+      # @motivation Worker failures otherwise lose queue metadata and request correlation.
+      # @limits It does not change retry behavior, acknowledge jobs, or install global error handlers.
+      # @collaborators Chronos facade, JobPayload, and Sidekiq server middleware chain.
+      # @thread_safety Shared instances keep only immutable collaborators.
+      # @compatibility Sidekiq 4.x/5.x server middleware signature.
+      # @example
+      #   ServerMiddleware.new.call(worker, job, "default") { worker.perform }
+      # @errors The original worker exception is always re-raised after contained notification.
+      # @performance No per-job thread or connection; normalization has strict collection limits.
+      class ServerMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { monotonic_time }
+          @wall_clock = options[:wall_clock] || proc { Time.now.to_f }
+          @limiter = options[:limiter] || JobPayload.new
+        end
+
+        def call(worker, job, queue)
+          started_at = @clock.call
+          payload = base_payload(worker, job, queue)
+          context = execution_context(job, payload)
+          @notifier.with_context(context) do
+            begin
+              result = yield
+              finish(payload, started_at, "completed")
+              result
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              finish(payload, started_at, "failed", error)
+              notify_failure(error, payload)
+              raise
+            end
+          end
+        end
+
+        private
+
+        def base_payload(worker, job, queue)
+          source = job.is_a?(Hash) ? job : {}
+          arguments, truncated = @limiter.arguments(source["args"] || source[:args])
+          payload = {
+            "kind" => "sidekiq", "class" => worker_class(worker, source),
+            "queue" => (source["queue"] || source[:queue] || queue).to_s,
+            "jid" => (source["jid"] || source[:jid]).to_s,
+            "retry_count" => retry_count(source), "arguments" => arguments,
+            "arguments_truncated" => truncated, "tags" => tags(worker, source),
+            "queue_latency_ms" => queue_latency(source)
+          }
+          payload
+        end
+
+        def execution_context(job, payload)
+          metadata = job.is_a?(Hash) ? (job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]) : nil
+          propagated = metadata.is_a?(Hash) ? (metadata["context"] || metadata[:context]) : nil
+          propagated = {} unless propagated.is_a?(Hash)
+          {
+            :context => propagated.merge("job" => job_context(payload)),
+            :__chronos_captured_exceptions => {}
+          }
+        end
+
+        def finish(payload, started_at, status, error = nil)
+          payload["duration_ms"] = [elapsed_ms(started_at), 0.0].max
+          payload["status"] = status
+          payload["error_class"] = error.class.name.to_s if error
+          @notifier.record_event("job", payload)
+        rescue StandardError
+          false
+        end
+
+        def notify_failure(error, payload)
+          context = {:context => {"job" => job_context(payload)},
+                     :parameters => {"arguments" => payload["arguments"]}, :tags => payload["tags"]}
+          if @notifier.respond_to?(:notify_once)
+            @notifier.notify_once(error, context)
+          else
+            @notifier.notify(error, context)
+          end
+        rescue StandardError
+          false
+        end
+
+        def job_context(payload)
+          %w(kind class queue jid retry_count queue_latency_ms duration_ms status).each_with_object({}) do |key, result|
+            result[key] = payload[key] unless payload[key].nil?
+          end
+        end
+
+        def worker_class(worker, job)
+          explicit = job["wrapped"] || job[:wrapped] || job["class"] || job[:class]
+          explicit = worker.class.name if explicit.to_s.empty? && worker
+          explicit.to_s
+        rescue StandardError
+          ""
+        end
+
+        def retry_count(job)
+          value = job["retry_count"] || job[:retry_count]
+          value.to_i < 0 ? 0 : value.to_i
+        end
+
+        def tags(worker, job)
+          values = job["tags"] || job[:tags]
+          if values.nil? && worker
+            owner = worker.is_a?(Class) ? worker : worker.class
+            options = owner.get_sidekiq_options if owner.respond_to?(:get_sidekiq_options)
+            values = options["tags"] || options[:tags] if options.is_a?(Hash)
+          end
+          @limiter.tags(values)
+        rescue StandardError
+          []
+        end
+
+        def queue_latency(job)
+          metadata = job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]
+          enqueued_at = job["enqueued_at"] || job[:enqueued_at]
+          enqueued_at ||= metadata["enqueued_at"] || metadata[:enqueued_at] if metadata.is_a?(Hash)
+          return nil unless enqueued_at
+
+          [((@wall_clock.call.to_f - enqueued_at.to_f) * 1000.0).round(3), 0.0].max
+        rescue StandardError
+          nil
+        end
+
+        def elapsed_ms(started_at)
+          ((@clock.call - started_at) * 1000.0).round(3)
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+    end
+  end
+end

data/lib/chronos/internal/worker_pool.rb

@@ -24,6 +24,7 @@ module Chronos
         @mutex = Mutex.new
         @threads = []
         @active = 0
+        @pending = 0
         @closed = false
         @pid = Process.pid
       end
@@ -32,7 +33,9 @@ module Chronos
         prepare_after_fork
         return false if closed?
 
+        increment_pending
         accepted = @queue.push(event)
+        decrement_pending unless accepted
         ensure_started if accepted
         accepted
       end
@@ -42,7 +45,7 @@ module Chronos
         ensure_started unless @queue.empty?
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -91,6 +94,7 @@ module Chronos
             @logger.warn("Chronos worker contained #{error.class}")
           ensure
             decrement_active
+            decrement_pending
           end
         end
       rescue StandardError => error
@@ -104,13 +108,14 @@ module Chronos
           @pid = Process.pid
           @threads = []
           @active = 0
+          @pending = @queue.size
         end
       end
 
       def flush_without_reopening(timeout)
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -138,6 +143,18 @@ module Chronos
         @mutex.synchronize { @active }
       end
 
+      def increment_pending
+        @mutex.synchronize { @pending += 1 }
+      end
+
+      def decrement_pending
+        @mutex.synchronize { @pending -= 1 }
+      end
+
+      def delivery_complete?
+        @mutex.synchronize { @pending.zero? && @active.zero? }
+      end
+
       def closed?
         @mutex.synchronize { @closed }
       end

data/lib/chronos/sidekiq.rb

@@ -0,0 +1,12 @@
+require "chronos"
+
+sidekiq_available = begin
+  require "sidekiq"
+  true
+rescue LoadError
+  false
+end
+
+require "chronos/integrations/sidekiq"
+
+Chronos::Integrations::Sidekiq.install if sidekiq_available && defined?(::Sidekiq)

data/lib/chronos/version.rb

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

data/lib/chronos.rb

@@ -104,6 +104,14 @@ module Chronos
       false
     end
 
+    # Returns only trace/request identifiers for optional process-boundary adapters.
+    def propagation_context
+      agent = current_agent
+      agent ? agent.propagation_context : {}
+    rescue StandardError
+      {}
+    end
+
     def notify_once(exception, context = {})
       agent = current_agent
       agent ? agent.notify_once(exception, context) : false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.0.pre.1
+  version: 0.6.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -88,6 +88,7 @@ files:
 - SECURITY.md
 - contracts/event-v1.schema.json
 - contracts/rack-context-v1.schema.json
+- contracts/sidekiq-job-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
@@ -97,6 +98,7 @@ files:
 - docs/adr/ADR-011-bounded-resilience-and-remote-control.md
 - docs/adr/ADR-012-rack-context-isolation.md
 - docs/adr/ADR-013-legacy-rails-notifications.md
+- docs/adr/ADR-014-sidekiq-envelope-context.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -111,6 +113,7 @@ files:
 - docs/modules/retry-backlog.md
 - docs/modules/sanitization.md
 - docs/modules/serialization.md
+- docs/modules/sidekiq-legacy.md
 - docs/modules/telemetry-events.md
 - docs/modules/transport.md
 - docs/performance.md
@@ -145,8 +148,10 @@ files:
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
+- lib/chronos/integrations/job_payload.rb
 - lib/chronos/integrations/rack.rb
 - lib/chronos/integrations/rack/middleware.rb
+- lib/chronos/integrations/sidekiq.rb
 - lib/chronos/internal.rb
 - lib/chronos/internal/bounded_queue.rb
 - lib/chronos/internal/memory_backlog.rb
@@ -161,6 +166,7 @@ files:
 - lib/chronos/rails/railtie.rb
 - lib/chronos/ruby.rb
 - lib/chronos/ruby/version.rb
+- lib/chronos/sidekiq.rb
 - lib/chronos/version.rb
 - lib/generators/chronos/install/install_generator.rb
 - lib/generators/chronos/install/templates/chronos.rb