chronos-ruby 0.1.0.pre.2

data/docs/compatibility.md

@@ -0,0 +1,21 @@
+# Compatibility
+
+Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an end-of-life Ruby or Rails release secure.
+
+| Ruby | Rails integration | Status | Evidence |
+|---|---|---|---|
+| 2.2.10 | None in 0.1 | Best effort | Local unit, contract, integration, fork, and fake-server suite |
+| 2.3.8 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
+| 2.4.10 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
+| 2.5.9 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
+| 2.6.10 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
+| 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
+
+No Rails version is declared supported by version 0.1. 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.
+
+Status meanings:
+
+- Supported: the complete required compatibility gate passes.
+- Best effort: intended to work, but the complete gate has not passed yet.
+- Deprecated: still tested while removal is planned.
+- Unsupported: outside this release line.

data/docs/configuration.md

@@ -0,0 +1,40 @@
+# Configuration
+
+`Chronos.configure` creates a mutable configuration, validates it, and gives runtime components an immutable snapshot.
+
+| Option | Required | Default | Description |
+|---|---:|---|---|
+| `project_id` | Yes when enabled | `nil` | Public project identifier included in the envelope |
+| `project_key` | Yes when enabled | `nil` | Secret authentication key sent only as an HTTP header |
+| `host` | Yes when enabled | `nil` | Absolute Chronos HTTP endpoint; HTTPS is required by default |
+| `environment` | Recommended | `production` | Application environment |
+| `app_version` | Optional | `nil` | Release or revision identifier |
+| `service_name` | Recommended | `nil` | Logical service name |
+| `root_directory` | Optional | `Dir.pwd` | Used to identify application backtrace frames |
+| `logger` | Optional | `nil` | Logger receiving bounded internal diagnostics |
+| `timeout` | Optional | `5.0` | HTTP read timeout in seconds |
+| `open_timeout` | Optional | `2.0` | HTTP connection timeout in seconds |
+| `queue_size` | Optional | `100` | Maximum queued events |
+| `workers` | Optional | `1` | Fixed positive worker count |
+| `enabled` | Optional | `true` | Enables all capture |
+| `error_notifications` | Optional | `true` | Enables exception events |
+| `ignored_environments` | Optional | `[]` | Environments where capture is disabled |
+| `proxy` | Optional | `nil` | Absolute HTTP proxy URL |
+| `ssl_verify` | Recommended | `true` | Enables TLS peer verification |
+| `user_agent` | Optional | Agent version | HTTP user agent |
+| `max_payload_size` | Optional | `1048576` | Maximum serialized payload bytes |
+| `gzip` | Optional | `false` | Compresses request bodies with gzip |
+
+```ruby
+Chronos.configure do |config|
+  config.project_id = ENV["CHRONOS_PROJECT_ID"]
+  config.project_key = ENV["CHRONOS_PROJECT_KEY"]
+  config.host = ENV["CHRONOS_HOST"]
+  config.environment = ENV["APP_ENV"] || "production"
+  config.service_name = "billing"
+  config.queue_size = 100
+  config.workers = 1
+end
+```
+
+The gem never reads all environment variables automatically. The host application decides which values to pass.

data/docs/data-collected.md

@@ -0,0 +1,20 @@
+# Data collected
+
+Version 0.1 emits only manual exception events.
+
+| Data | Default | Source |
+|---|---|---|
+| Exception class and message | Collected | Ruby exception |
+| Structured backtrace | Collected when present | Ruby exception |
+| Cause class and message | Collected when present | `Exception#cause` |
+| Ruby version, engine, platform | Collected | Ruby constants |
+| PID and opaque thread ID | Collected | Ruby runtime |
+| Hostname | Collected when available | Standard library |
+| Environment and service | Configuration | Host application |
+| Application version | Optional | Host application |
+| Context, parameters, session, user | Optional | Explicit capture arguments |
+| Tags and fingerprint | Optional | Explicit capture arguments |
+
+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.1.
+
+The secret `project_key` is an authentication header and is excluded from the JSON payload and logger diagnostics.

data/docs/examples/plain-ruby.md

@@ -0,0 +1,12 @@
+# Plain Ruby example
+
+Set test project credentials and an endpoint, then run the executable example:
+
+```bash
+CHRONOS_PROJECT_ID=project-id \
+CHRONOS_PROJECT_KEY=project-key \
+CHRONOS_HOST=https://chronos.example.com \
+bundle _1.17.3_ exec ruby examples/plain-ruby/example.rb
+```
+
+The example reports one manual exception and closes the agent with a two-second timeout. Use a local fake endpoint when auditing the payload.

data/docs/modules/async-queue.md

@@ -0,0 +1,17 @@
+# Asynchronous queue module
+
+`BoundedQueue` stores at most `queue_size` serialized events. When full, it drops the newest event and increments a counter. Producers do not wait for capacity.
+
+`WorkerPool` owns a fixed number of lazy threads. It tracks active deliveries, supports timed flush and close, contains transport errors, and recreates worker references after fork.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Accepted
+  Accepted --> Queued
+  Queued --> Sending
+  Sending --> Sent
+  Sending --> Dropped: delivery failure in 0.1
+  Accepted --> Dropped: queue full
+```
+
+Version 0.1 has no disk persistence and no retry. Queue statistics expose current size, capacity, accepted events, and dropped events. Tests cover full queues, waiter wakeup, lazy startup, contained failures, timed shutdown, double close, flush, and fork behavior.

data/docs/modules/configuration.md

@@ -0,0 +1,9 @@
+# Configuration module
+
+Configuration separates mutable setup from immutable runtime state. `Chronos::Configuration` owns defaults and validation; `Snapshot` is shared with runtime components.
+
+This module is separate from capture because configuration errors should be found before any event enters the pipeline. It can be extended by adding a validated attribute and immutable snapshot field.
+
+Risks include accidentally logging credentials and changing settings while events run. The snapshot prevents mutation, while logger and transport code never interpolate `project_key`.
+
+Tests in `spec/unit/configuration_spec.rb` verify required fields, HTTPS defaults, immutable containers, disabled operation, and bounded numeric settings.

data/docs/modules/notice-pipeline.md

@@ -0,0 +1,20 @@
+# Notice pipeline
+
+The notice pipeline converts a Ruby `Exception` into a versioned JSON event.
+
+```mermaid
+flowchart LR
+  Exception --> NoticeBuilder
+  NoticeBuilder --> BacktraceParser
+  NoticeBuilder --> CauseCollector
+  NoticeBuilder --> RuntimeInfo
+  NoticeBuilder --> Notice
+  Notice --> PayloadSerializer
+  PayloadSerializer --> SerializedEvent
+```
+
+`Notice` is immutable. Parsers are stateless. The serializer accepts only JSON primitives, bounds nested structures, tolerates invalid encoding, and represents unknown objects without arbitrary `to_json` calls.
+
+Version 0.1 deliberately excludes the advanced sanitizer, sampler, and fingerprint policy. These can be inserted before serialization without changing transport or queue code.
+
+Unit and contract tests verify missing backtraces, cyclic causes, invalid encoding, unsafe objects, payload limits, and the v1 envelope.

data/docs/modules/transport.md

@@ -0,0 +1,9 @@
+# Transport module
+
+`Chronos::Ports::Transport` defines delivery behavior. `Chronos::Adapters::NetHttpTransport` implements it with the Ruby standard library.
+
+Each event uses bounded open and read timeouts. TLS verification is enabled by default. Authentication and idempotency values are headers. Redirects are not followed. Statuses are classified as success, client error, rate limited, server error, network error, or closed.
+
+The adapter creates a connection per event in version 0.1. This is conservative for legacy applications and avoids shared socket lifecycle state. Batch optimization and retry may be added behind the same port.
+
+Risks include proxy credential exposure, TLS incompatibility on old operating systems, and endpoint latency. Tests use a local fake HTTP server to verify headers, `2xx`, `429`, `500`, timeout, and invalid TLS behavior.

data/docs/performance.md

@@ -0,0 +1,16 @@
+# Performance
+
+Performance is a functional requirement, but version 0.1 makes no unverified speed claim.
+
+Current controls:
+
+- backtraces are limited to 200 frames;
+- hashes and arrays are bounded during serialization;
+- strings and total payload size are bounded;
+- the asynchronous queue has fixed capacity;
+- worker count is fixed and threads start lazily;
+- producers never wait for queue capacity;
+- HTTP open and read timeouts are explicit;
+- shutdown and flush have caller-controlled timeouts.
+
+Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. Request overhead is not measured because automatic request integration is outside version 0.1.

data/docs/privacy-lgpd.md

@@ -0,0 +1,16 @@
+# Privacy and LGPD
+
+Version 0.1 enforces structural limits but does not yet implement the recursive sensitive-data sanitizer planned for version 0.2.
+
+Applications must not pass passwords, tokens, authorization headers, cookies, session secrets, private keys, card data, CPF, CNPJ, health data, or other unnecessary personal information.
+
+Recommended practice:
+
+1. pass opaque internal identifiers instead of names or e-mail addresses;
+2. allowlist context fields in application code;
+3. inspect payloads against a local fake server before production;
+4. keep TLS verification enabled;
+5. document the lawful purpose and retention policy in the SaaS;
+6. disable the agent in environments where collection is not authorized.
+
+Version 0.1 limits object depth, hash keys, array items, string bytes, backtrace frames, queue capacity, and total payload size. Unknown Ruby objects are represented by class name without calling their `to_json` implementation.

data/docs/troubleshooting.md

@@ -0,0 +1,25 @@
+# Troubleshooting
+
+## 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.
+
+## `Chronos.notify` returns false
+
+The agent may be unconfigured, disabled, ignored in the current environment, unable to serialize the value, closed, or at queue capacity. Check the configured logger and `agent.diagnostics` when constructing an agent directly in diagnostics code.
+
+## `Chronos.notify_sync` returns false
+
+Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and timeout values. Version 0.1 does not retry.
+
+## Events disappear during shutdown
+
+Call `Chronos.close(timeout)` and inspect its Boolean result. A `false` result means accepted work could not finish before the timeout.
+
+## Forking servers
+
+Workers are recreated after a process fork. Configure before or after forking, then call capture in the child. Always close each child during shutdown.
+
+## Sensitive data
+
+Version 0.1 does not redact arbitrary context. Stop sending the affected field, rotate exposed credentials, and follow the incident process for the Chronos SaaS.

data/lib/chronos/adapters/net_http_transport.rb

@@ -0,0 +1,132 @@
+require "net/http"
+require "openssl"
+require "stringio"
+require "uri"
+require "zlib"
+
+module Chronos
+  module Adapters
+    # Net::HTTP implementation of the Chronos transport port.
+    #
+    # @responsibility Send serialized events over bounded HTTPS requests.
+    # @motivation Use the Ruby standard library to preserve legacy compatibility.
+    # @limits It classifies failures but does not retry or persist events in version 0.1.
+    # @collaborators Configuration::Snapshot, SerializedEvent, and TransportResult.
+    # @thread_safety Creates a new Net::HTTP connection per call and synchronizes health state.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; no Rails dependency.
+    # @example
+    #   result = transport.send_event(serialized_event)
+    # @errors Network, TLS, and HTTP errors are returned, never raised to callers.
+    # @performance One bounded network request per event in version 0.1.
+    class NetHttpTransport
+      EVENT_PATH = "/api/v1/events".freeze
+
+      def initialize(config, logger = nil)
+        @config = config
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        @health_mutex = Mutex.new
+        @healthy = true
+        @closed = false
+      end
+
+      def send_event(event)
+        return Ports::TransportResult.new(:closed) if closed?
+
+        response = perform_request(event)
+        result = classify(response)
+        update_health(result.success?)
+        result
+      rescue StandardError => error
+        update_health(false)
+        @logger.warn("Chronos transport failed: #{error.class}")
+        Ports::TransportResult.new(:network_error, :error => error.class.name)
+      end
+
+      def send_batch(events)
+        Array(events).map { |event| send_event(event) }
+      end
+
+      def healthy?
+        @health_mutex.synchronize { @healthy && !@closed }
+      end
+
+      def close
+        @health_mutex.synchronize { @closed = true }
+        true
+      end
+
+      private
+
+      def perform_request(event)
+        uri = endpoint_uri
+        http = build_http(uri)
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        request["User-Agent"] = @config.user_agent
+        request["X-Chronos-Project-ID"] = @config.project_id.to_s
+        request["X-Chronos-Project-Key"] = @config.project_key.to_s
+        request["Idempotency-Key"] = event.event_id
+        request.body = request_body(event.body)
+        request["Content-Encoding"] = "gzip" if @config.gzip
+        http.start { |connection| connection.request(request) }
+      end
+
+      def endpoint_uri
+        uri = URI.parse(@config.host)
+        base_path = uri.path.to_s.sub(%r{/+\z}, "")
+        uri.path = base_path + EVENT_PATH
+        uri.query = nil
+        uri.fragment = nil
+        uri
+      end
+
+      def build_http(uri)
+        http = if @config.proxy
+                 proxy = URI.parse(@config.proxy)
+                 Net::HTTP::Proxy(proxy.host, proxy.port, proxy.user, proxy.password).new(uri.host, uri.port)
+               else
+                 Net::HTTP.new(uri.host, uri.port)
+               end
+        http.open_timeout = @config.open_timeout
+        http.read_timeout = @config.timeout
+        if uri.scheme == "https"
+          http.use_ssl = true
+          http.verify_mode = @config.ssl_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+        end
+        http
+      end
+
+      def classify(response)
+        code = response.code.to_i
+        options = {:status_code => code}
+        return Ports::TransportResult.new(:success, options) if code >= 200 && code < 300
+        if code == 429
+          options[:retry_after] = response["Retry-After"]
+          return Ports::TransportResult.new(:rate_limited, options)
+        end
+        return Ports::TransportResult.new(:server_error, options) if code >= 500
+
+        Ports::TransportResult.new(:client_error, options)
+      end
+
+      def request_body(body)
+        return body unless @config.gzip
+
+        output = StringIO.new
+        writer = Zlib::GzipWriter.new(output)
+        writer.write(body)
+        writer.close
+        output.string
+      end
+
+      def update_health(value)
+        @health_mutex.synchronize { @healthy = value }
+      end
+
+      def closed?
+        @health_mutex.synchronize { @closed }
+      end
+    end
+  end
+end

data/lib/chronos/adapters.rb

@@ -0,0 +1,10 @@
+module Chronos
+  # Infrastructure implementations of Chronos ports.
+  #
+  # @responsibility Connect the agent to HTTP and future external systems.
+  # @motivation Isolate standard-library and vendor-specific behavior.
+  # @limits Adapters must not add policy to the domain pipeline.
+  # @thread_safety Defined by each adapter.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  module Adapters; end
+end

data/lib/chronos/agent.rb

@@ -0,0 +1,57 @@
+module Chronos
+  # Runtime composition root for the framework-independent Chronos agent.
+  #
+  # @responsibility Own transport, queue, workers, and the capture use case.
+  # @motivation Keep construction details outside the public module facade.
+  # @limits It does not integrate with Rails, Rack, or job systems.
+  # @collaborators Configuration snapshot, CaptureException, BoundedQueue, and NetHttpTransport.
+  # @thread_safety Runtime collaborators synchronize mutable state.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   agent.notify(RuntimeError.new("failed"))
+  # @errors Capture errors return false; explicit construction requires valid configuration.
+  # @performance No worker threads are created until the first asynchronous event.
+  class Agent
+    DEFAULT_FLUSH_TIMEOUT = 5.0
+
+    attr_reader :config
+
+    def initialize(config, options = {})
+      @config = config
+      @logger = options[:logger] || Internal::SafeLogger.new(config.logger)
+      @transport = options[:transport] || Adapters::NetHttpTransport.new(config, @logger)
+      unless Ports::Transport.compatible?(@transport)
+        raise ArgumentError, "transport does not implement the Chronos transport port"
+      end
+      @queue = options[:queue] || Internal::BoundedQueue.new(config.queue_size)
+      @worker_pool = options[:worker_pool] || Internal::WorkerPool.new(@queue, @transport, config.workers, @logger)
+      @capture = options[:capture] || Application::CaptureException.new(config, @worker_pool, @transport, @logger)
+    end
+
+    def notify(exception, context = {})
+      @capture.call(exception, context)
+    end
+
+    def notify_sync(exception, context = {})
+      @capture.call_sync(exception, context)
+    end
+
+    def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
+      @worker_pool.flush(timeout)
+    rescue StandardError => error
+      @logger.warn("Chronos flush failed: #{error.class}")
+      false
+    end
+
+    def close(timeout = DEFAULT_FLUSH_TIMEOUT)
+      @worker_pool.close(timeout)
+    rescue StandardError => error
+      @logger.warn("Chronos close failed: #{error.class}")
+      false
+    end
+
+    def diagnostics
+      @queue.stats
+    end
+  end
+end

data/lib/chronos/application/capture_exception.rb

@@ -0,0 +1,61 @@
+module Chronos
+  module Application
+    # Orchestrates exception normalization, serialization, queueing, and delivery.
+    #
+    # @responsibility Execute the version 0.1 exception capture pipeline.
+    # @motivation Keep the public facade and transport adapters free of use-case logic.
+    # @limits It does not implement advanced sanitization, sampling, retry, or backlog.
+    # @collaborators NoticeBuilder, PayloadSerializer, WorkerPool, and Transport.
+    # @thread_safety Collaborators are immutable or synchronized; calls may run concurrently.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   capture.call(exception, :user => {"id" => "42"})
+    # @errors All internal StandardError failures are contained and logged.
+    # @performance Local work is bounded before asynchronous queue insertion.
+    class CaptureException
+      def initialize(config, worker_pool, transport, logger = nil, options = {})
+        @config = config
+        @worker_pool = worker_pool
+        @transport = transport
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        @notice_builder = options[:notice_builder] || Core::NoticeBuilder.new(config)
+        @serializer = options[:serializer] || Core::PayloadSerializer.new(config)
+      end
+
+      def call(exception, context = {})
+        return false unless capture_enabled?
+
+        event = build_event(exception, context)
+        @worker_pool.enqueue(event)
+      rescue StandardError => error
+        diagnose(error)
+        false
+      end
+
+      def call_sync(exception, context = {})
+        return false unless capture_enabled?
+
+        event = build_event(exception, context)
+        @transport.send_event(event).success?
+      rescue StandardError => error
+        diagnose(error)
+        false
+      end
+
+      private
+
+      def capture_enabled?
+        @config.enabled_for_environment? && @config.error_notifications
+      end
+
+      def build_event(exception, context)
+        notice = @notice_builder.call(exception, context)
+        @serializer.call(notice)
+      end
+
+      def diagnose(error)
+        @logger.warn("Chronos capture failed: #{error.class}")
+      end
+    end
+  end
+end

data/lib/chronos/application.rb

@@ -0,0 +1,10 @@
+module Chronos
+  # Application use cases that coordinate the core and ports.
+  #
+  # @responsibility Orchestrate capture and delivery workflows.
+  # @motivation Keep policy separate from domain values and adapters.
+  # @limits Does not implement HTTP or framework hooks.
+  # @thread_safety Use cases rely on thread-safe collaborators.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  module Application; end
+end

data/lib/chronos/configuration.rb

@@ -0,0 +1,139 @@
+require "uri"
+
+module Chronos
+  # Mutable configuration used only while the Chronos agent is being set up.
+  #
+  # @responsibility Store options, validate them,
+  #   and create immutable snapshots.
+  # @motivation Prevent runtime components
+  #   from observing partially changed state.
+  # @limits It does not send events or read application environment variables.
+  # @collaborators Chronos::Configuration::Snapshot.
+  # @thread_safety Configure one instance
+  #   from one thread before sharing its snapshot.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   config = Chronos::Configuration.new
+  #   config.project_id = 'project-id'
+  #   config.project_key = 'project-key'
+  #   config.host = 'https://chronos.example.com'
+  #   snapshot = config.snapshot
+  class Configuration
+    ATTRIBUTES = [
+      :project_id, :project_key, :host, :environment, :app_version,
+      :service_name, :root_directory, :logger, :timeout, :open_timeout,
+      :queue_size, :workers, :enabled, :error_notifications,
+      :ignored_environments, :proxy, :ssl_verify, :user_agent,
+      :max_payload_size, :gzip
+    ].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize
+      @project_id = nil
+      @project_key = nil
+      @host = nil
+      @environment = "production"
+      @app_version = nil
+      @service_name = nil
+      @root_directory = Dir.pwd
+      @logger = nil
+      @timeout = 5.0
+      @open_timeout = 2.0
+      @queue_size = 100
+      @workers = 1
+      @enabled = true
+      @error_notifications = true
+      @ignored_environments = []
+      @proxy = nil
+      @ssl_verify = true
+      @user_agent = "chronos-ruby/#{Chronos::VERSION}"
+      @max_payload_size = 1_048_576
+      @gzip = false
+    end
+
+    def snapshot
+      errors = validation_errors
+      raise ConfigurationError, errors.join(", ") unless errors.empty?
+
+      Snapshot.new(to_hash)
+    end
+
+    def valid?
+      validation_errors.empty?
+    end
+
+    def validation_errors
+      errors = []
+      if enabled
+        errors << "project_id is required" if blank?(project_id)
+        errors << "project_key is required" if blank?(project_key)
+        errors.concat(host_errors)
+      end
+      errors << "timeout must be greater than zero" unless positive_number?(timeout)
+      errors << "open_timeout must be greater than zero" unless positive_number?(open_timeout)
+      errors << "queue_size must be a positive integer" unless positive_integer?(queue_size)
+      errors << "workers must be a positive integer" unless positive_integer?(workers)
+      errors << "max_payload_size must be a positive integer" unless positive_integer?(max_payload_size)
+      errors
+    end
+
+    private
+
+    def to_hash
+      ATTRIBUTES.each_with_object({}) do |attribute, values|
+        value = public_send(attribute)
+        value = value.dup if value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(String)
+        values[attribute] = value
+      end
+    end
+
+    def host_errors
+      return ["host is required"] if blank?(host)
+
+      uri = URI.parse(host.to_s)
+      return ["host must be an absolute HTTP or HTTPS URL"] unless uri.host && %w(http https).include?(uri.scheme)
+      return ["host must use HTTPS unless ssl_verify is explicitly disabled"] if uri.scheme != "https" && ssl_verify
+
+      []
+    rescue URI::InvalidURIError
+      ["host must be a valid URL"]
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def positive_number?(value)
+      value.is_a?(Numeric) && value > 0
+    end
+
+    def positive_integer?(value)
+      value.is_a?(Integer) && value > 0
+    end
+
+    # Immutable configuration shared by all runtime components.
+    #
+    # @responsibility Expose validated settings without mutable containers.
+    # @motivation Keep capture behavior stable while multiple threads run.
+    # @limits It cannot be edited after creation.
+    # @thread_safety Safe to share between threads after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    class Snapshot
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(values)
+        ATTRIBUTES.each do |attribute|
+          value = values[attribute]
+          value.freeze if value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(String)
+          instance_variable_set("@#{attribute}", value)
+        end
+        freeze
+      end
+
+      def enabled_for_environment?
+        enabled && !ignored_environments.map(&:to_s).include?(environment.to_s)
+      end
+    end
+  end
+end