chronos-ruby 0.9.0.pre.3 → 0.9.0.pre.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a834300cdaf9acd0d75e625d6cc811c677bd8cf2f701aed885e0bbae417aaca0
-  data.tar.gz: 1b2e992ee0c9428e25bac17a8cbe21ae0bc167ebb519b63ae9c2e1cdb3ec3cc7
+  metadata.gz: 84266b3c93fc92c15268d44e3625762f471c9cf99fa0523b6f5d883f846906e4
+  data.tar.gz: bf3d2c641bbb7f117a1c9c76519fa756057f72108d899cb64d86e2eeff305423
 SHA512:
-  metadata.gz: 53be3a9634f8a47b9701897f4b6b58e1f0d023b536a2f6f4a7649f2d31344cb07f161e9f5d11c7636217194bdf31fe8181f5c6d1e916ef6049020f59b1ff2c4a
-  data.tar.gz: 40b56150fed7170583f514552cd34894c98e6b8011c09f8a188af29accc5dfe36ab72b78375875e88059324025b7d82f7ef4cbb13b184a034b0bff22e7a38ca5
+  metadata.gz: 9b54a3aef38f706677794b39740558586d9c69f083a3c2b3f2dc6ea20e3b60f2fe84765eb61a44fe2f230a03c03dcb27047cdd7a1853b14fc805fcb914d7cfb8
+  data.tar.gz: 2f915f461e658f93269d35e52f6d728ff32ef90a4a6ac765a6b92194a1fc53b06ca5350b2bc34c8d84197bf2263d523ead9a62ada46edbd9ae46363d3de27e05

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+## [0.9.0.pre.4] - 2026-07-22
+
+### Added
+
+- `Chronos.verify_integration` and `chronos:verify_integration` send a correlated synthetic exception and report credential, project, receiver, and receipt status as bounded JSON;
+- strict integration-verification response contract v1, Rails task registration, failure classification, security limits, and end-to-end tests.
+
+### Changed
+
+- version advanced to `0.9.0.pre.4` because `0.9.0.pre.3` had already been published before integration verification was added.
+
+### Fixed
+
+- legacy dependency resolution pins `parallel` to Ruby 2.2-compatible `1.19.2` and the Sidekiq 5 smoke pins `rack-protection` to Ruby 2.5-compatible `2.2.4`.
+- the Rails verification task now always depends on `environment`, even when Rails defines that Rake task after the Chronos Railtie hook runs.
+
 ## [0.9.0.pre.3] - 2026-07-21
 
 ### Changed

data/README.md

@@ -33,7 +33,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.9.0.pre.3"
+gem "chronos-ruby", "0.9.0.pre.4"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -54,7 +54,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.9.0.pre.3", :require => "chronos/rails"
+gem "chronos-ruby", "0.9.0.pre.4", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -84,6 +84,27 @@ end
 
 HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_verify = false` and should only be used with a local test server.
 
+## Verify the Chronos integration
+
+After configuring the application, Rails projects can verify credentials and end-to-end ingestion with:
+
+```bash
+bundle exec rake chronos:verify_integration
+```
+
+The task sends one synthetic exception identified as an integration verification and prints one JSON object. It exits with status `0` only when Chronos confirms valid credentials and receipt of the correlated event; configuration, authentication, inactive-project, network, protocol, rate-limit, and receiver failures exit nonzero with safe guidance.
+
+Plain Ruby Rakefiles can install the same task explicitly after loading their configuration:
+
+```ruby
+require "chronos"
+# Chronos.configure { |config| ... }
+require "chronos/rake_tasks"
+Chronos::RakeTasks.install
+```
+
+Ruby code may call `result = Chronos.verify_integration`, inspect `result.success?`, and serialize `result.to_h` or `result.to_json`. The result contains only bounded contract fields; it never exposes `project_key`, raw server responses, stack traces, source paths, or receiver internals. See [Integration verification](docs/modules/integration-verification.md).
+
 ## Automatic capture
 
 Rack applications can capture unhandled exceptions automatically and preserve the application error semantics:
@@ -201,7 +222,7 @@ Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.9.0.pre.3", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.4", :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).

data/contracts/integration-verification-response-v1.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/integration-verification-response-v1.schema.json",
+  "title": "Chronos integration verification response v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "success",
+    "status",
+    "verification_id",
+    "credentials_valid",
+    "event_received",
+    "event",
+    "project",
+    "receiver",
+    "error"
+  ],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "success": {"type": "boolean"},
+    "status": {
+      "enum": [
+        "accepted",
+        "invalid_credentials",
+        "project_inactive",
+        "receiver_unavailable",
+        "receiver_internal_error",
+        "request_rejected",
+        "rate_limited"
+      ]
+    },
+    "verification_id": {"type": "string", "minLength": 1, "maxLength": 128},
+    "credentials_valid": {"type": ["boolean", "null"]},
+    "event_received": {"type": "boolean"},
+    "event": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {"type": ["string", "null"], "maxLength": 128}
+      }
+    },
+    "project": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["id", "name", "status", "environment"],
+      "properties": {
+        "id": {"type": ["string", "null"], "maxLength": 128},
+        "name": {"type": ["string", "null"], "maxLength": 128},
+        "status": {"type": ["string", "null"], "maxLength": 32},
+        "environment": {"type": ["string", "null"], "maxLength": 128}
+      }
+    },
+    "receiver": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["name", "status", "received_at"],
+      "properties": {
+        "name": {"type": ["string", "null"], "maxLength": 64},
+        "status": {"type": ["string", "null"], "maxLength": 32},
+        "received_at": {"type": ["string", "null"], "maxLength": 64}
+      }
+    },
+    "error": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["code", "message", "guidance"],
+      "properties": {
+        "code": {"type": "string", "maxLength": 64},
+        "message": {"type": "string", "maxLength": 512},
+        "guidance": {"type": "string", "maxLength": 512}
+      }
+    }
+  }
+}

data/docs/data-collected.md

@@ -48,6 +48,7 @@ Version 0.9 emits exceptions, cache telemetry, dependency/deploy events, and agg
 | Rails, web server, database adapter, Sidekiq, release | Included when safely detectable/configured | Loaded constants/specs and `app_version` |
 | Event release, revision, deploy ID, environment, service, region, instance | Present as bounded correlation; values optional | Explicit immutable configuration or normalized deploy payload |
 | Deploy environment, revision, version, repository, actor, deploy ID, service, region, instance | Explicit synchronous deploy API | Application/deployment integration arguments |
+| Integration verification ID, fixed test marker, synthetic exception class/message, and receipt correlation | Only when `Chronos.verify_integration` or its Rake task is invoked | Locally generated bounded values |
 
 The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, Git state, source code, raw SQL, SQL bind values, database rows, raw cache keys/values, mail bodies/recipients, Active Job arguments, gem paths, or lockfile contents. Active Job IDs, Sidekiq JIDs/arguments, loaded gem names/versions, and deploy fields are documented integration data.
 
@@ -55,4 +56,6 @@ APM dimensions never include user ID, job ID, raw URL, exception message, bind v
 
 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.
 
+The integration check uses the fixed class `Chronos::IntegrationVerificationError`, tag/fingerprint `chronos-integration-verification`, and `context.integration_verification.test: true`. Its returned object allowlists only project identity/status/environment, receiver name/status/receipt time, correlation IDs, booleans, and safe guidance. Raw response bodies and Chronos implementation details are discarded.
+
 See [Privacy and LGPD](privacy-lgpd.md) for redaction rules and the payload audit procedure.

data/docs/modules/integration-verification.md

@@ -0,0 +1,65 @@
+# Integration verification
+
+`Chronos.verify_integration` performs an explicit end-to-end check of configuration, credentials, receiver availability, and ingestion acknowledgement. Rails registers `chronos:verify_integration` automatically through the Railtie. The command prints exactly one JSON object and exits nonzero unless verification succeeds.
+
+## Flow and ownership
+
+`Chronos::Application::VerifyIntegration` creates one normal v1 exception envelope, delivers it synchronously through `DeliveryPipeline`, and validates the response. `IntegrationVerificationResult` exposes the immutable, bounded public outcome. `RakeTasks` only loads the application environment, calls the facade, prints JSON, and selects the exit status.
+
+The synthetic event is recognizable without changing the event protocol:
+
+```json
+{
+  "event_type": "exception",
+  "payload": {
+    "exception": {"class": "Chronos::IntegrationVerificationError"},
+    "tags": ["chronos-integration-verification"],
+    "fingerprint": "chronos-integration-verification"
+  },
+  "context": {
+    "integration_verification": {
+      "schema_version": "1.0",
+      "verification_id": "generated-uuid",
+      "kind": "integration_verification",
+      "test": true
+    }
+  }
+}
+```
+
+Chronos must authenticate before acknowledging the event and must correlate both `verification_id` and the envelope event ID. A `2xx` response alone is insufficient. The accepted response must conform exactly to [`integration-verification-response-v1.schema.json`](../../contracts/integration-verification-response-v1.schema.json):
+
+```json
+{
+  "schema_version": "1.0",
+  "success": true,
+  "status": "accepted",
+  "verification_id": "generated-uuid",
+  "credentials_valid": true,
+  "event_received": true,
+  "event": {"id": "event-uuid"},
+  "project": {"id": "project-id", "name": "Project", "status": "active", "environment": "production"},
+  "receiver": {"name": "chronos", "status": "operational", "received_at": "2026-07-22T12:00:00Z"},
+  "error": null
+}
+```
+
+The client rejects missing, mismatched, or additional fields. It copies only the allowlisted project and receiver values and never returns the raw body.
+
+## Result and failure classification
+
+The Ruby result supports `success?`, `to_h`, and `to_json`. Its status is `verified` only after the correlated acknowledgement. Failures use `configuration_invalid`, `invalid_credentials`, `project_inactive`, `receiver_unavailable`, `receiver_internal_error`, `rate_limited`, `request_rejected`, `invalid_response`, or `verification_failed`.
+
+- `401` and untrusted `403` responses become `invalid_credentials` with instructions to create an active project API key and verify the configured identifiers.
+- A contractual authenticated `403` response may become `project_inactive`.
+- network errors, timeouts, an open circuit, and `502`/`503`/`504` become `receiver_unavailable`.
+- other `5xx` responses become `receiver_internal_error`.
+- malformed or uncorrelated success responses become `invalid_response`.
+
+Failure output uses local messages and guidance. Server exception messages, stack traces, SQL, paths, classes, credentials, response headers, and architecture details are never copied.
+
+## Usage
+
+In Rails, configure Chronos normally and run `bundle exec rake chronos:verify_integration`. In plain Ruby, require `chronos/rake_tasks` and call `Chronos::RakeTasks.install` from the Rakefile. Programmatic callers can use `Chronos.verify_integration` directly.
+
+Verification is an explicit synchronous diagnostic operation. It bypasses sampling and ignore rules so an operator-requested check cannot silently disappear, but it still uses the configured bounded retry, timeout, TLS, circuit, serializer, and transport protections. The receiver should record it as a verification/audit receipt rather than a production application incident.

data/docs/modules/sidekiq-legacy.md

@@ -4,7 +4,7 @@ Version `0.6.0.pre.1` starts the legacy jobs line with optional Sidekiq 4 and 5
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.9.0.pre.3", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.4", :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.

data/docs/performance.md

@@ -29,7 +29,7 @@ Current controls:
 
 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.
 
-## Version 0.9.0.pre.3 release gates
+## Version 0.9.0.pre.4 release gates
 
 `benchmarks/comparative.rb` compares the same successful Rack fixture without and with Chronos instrumentation. It performs configurable warmup, at least three samples, and reports median plus median absolute deviation. `benchmarks/fake_endpoint_load.rb` sends asynchronous exception events to a local TCP endpoint, verifies the v1 schema marker, ensures the secret key is absent from every payload, and fails on loss, rejection, invalid payload, or timeout.
 

data/docs/protocol-v1.md

@@ -1,5 +1,7 @@
 # Protocol v1 stability
 
-The schemas under `contracts/` are the source of truth for protocol v1. Version `0.9.0.pre.3` keeps `schema_version: "1.0"` and treats every required field, enum value, privacy exclusion, and maximum as a compatibility contract.
+The schemas under `contracts/` are the source of truth for protocol v1. Version `0.9.0.pre.4` keeps `schema_version: "1.0"` and treats every required field, enum value, privacy exclusion, and maximum as a compatibility contract.
 
 Compatible changes may add optional bounded fields or new event types accepted by the server. Removing or renaming a field, changing its type/meaning, weakening a bound, or making an optional field required needs a new protocol major schema. Authentication remains outside the JSON payload. Contract tests and `script/verify_docs` must pass before a release.
+
+The explicit integration check uses the normal exception envelope and identifies itself through `context.integration_verification`. Its receiver acknowledgement is governed separately by [`integration-verification-response-v1.schema.json`](../contracts/integration-verification-response-v1.schema.json). A successful HTTP status without a complete, correlated response is not proof of authentication or ingestion.

data/docs/release-1.0-readiness.md

@@ -1,8 +1,8 @@
 # Version 1.0 readiness
 
-Version `0.9.0.pre.3` is a hardening release, not the stable release. The local suite, lint, documentation verifier, build, load test, and comparative benchmark are required evidence. The release can advance to `1.0.0` only after the GitHub Actions matrix is green for every declared legacy Ruby/framework/job combination.
+Version `0.9.0.pre.4` is a hardening release, not the stable release. The local suite, lint, documentation verifier, build, load test, and comparative benchmark are required evidence. The release can advance to `1.0.0` only after the GitHub Actions matrix is green for every declared legacy Ruby/framework/job combination.
 
-| Gate | State in pre.2 |
+| Gate | State in pre.4 |
 |---|---|
 | Ruby pure, Rack, Rails 4.2/5.2 | Implemented; external legacy matrix must pass |
 | Sidekiq 4/5 real gems | Dedicated Docker matrix added; must pass |

data/docs/security-review.md

@@ -1,6 +1,6 @@
-# Security review for 0.9.0.pre.3
+# Security review for 0.9.0.pre.4
 
-Review date: 2026-07-21. Scope: capture, serialization, transport, remote configuration, framework/job integrations, release workflow, examples, and fixtures.
+Review date: 2026-07-22. Scope: capture, serialization, transport, integration verification, remote configuration, framework/job integrations, release workflow, examples, and fixtures.
 
 Verified by contracts and implementation review:
 
@@ -12,5 +12,6 @@ Verified by contracts and implementation review:
 - integrations contain agent failures and do not collect bodies, authorization, raw SQL/binds, mail content, or raw cache keys;
 - Active Job propagation uses a namespaced v1 field containing only bounded trace/request identifiers and does not alter job arguments;
 - fixture privacy is enforced by contract tests and dependency advisories are checked by the security workflow.
+- integration verification accepts only a strict correlated response and never exposes raw receiver bodies, credentials, stack traces, paths, SQL, or internal architecture.
 
 Residual risks: supported Ruby/Rails versions are end-of-life; in-memory backlog is lost at exit; application filters/ignore rules execute application code; project identifiers and documented job IDs may be personal data in some deployments; package signing is not enabled because no trusted certificate/key lifecycle exists. Release artifacts should use protected environments and published SHA-256 checksums until signing can be operated safely.

data/docs/troubleshooting.md

@@ -12,6 +12,12 @@ The agent may be unconfigured, disabled, ignored in the current environment, una
 
 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.
 
+## `chronos:verify_integration` fails
+
+Read the single JSON object printed by the task and use `status` and `error.guidance`. `invalid_credentials` means an active project API key must be created or the configured `project_id`/`project_key` corrected. `project_inactive` means authentication succeeded but the selected project must be activated. `receiver_unavailable` covers DNS, TLS, network, timeout, circuit-open, and gateway/service-unavailable failures. `receiver_internal_error` means Chronos reached its own safe internal-error boundary. `invalid_response` means the receiver did not implement the correlated response v1 contract. Every failure exits nonzero and deliberately omits raw receiver messages and implementation details.
+
+If Rails does not list the task, require `chronos/rails` and confirm the application initializer loads. A `not_configured` result means the current Rake process did not execute `Chronos.configure`; update to a release containing the Rails environment prerequisite fix and confirm the variables are exported into that process. In plain Ruby, require `chronos/rake_tasks` and call `Chronos::RakeTasks.install` from the Rakefile after loading configuration.
+
 ## 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.5 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.

data/lib/chronos/adapters/net_http_transport.rb

@@ -22,6 +22,7 @@ module Chronos
     class NetHttpTransport
       EVENT_PATH = "/api/v1/events".freeze
       REMOTE_CONFIGURATION_HEADER = "X-Chronos-Remote-Configuration".freeze
+      RESPONSE_BODY_MAX_BYTES = 8192
 
       def initialize(config, logger = nil)
         @config = config
@@ -71,7 +72,11 @@ module Chronos
         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) }
+        http.start do |connection|
+          connection.request(request) do |response|
+            read_bounded_response(response)
+          end
+        end
       end
 
       def endpoint_uri
@@ -101,7 +106,7 @@ module Chronos
 
       def classify(response)
         code = response.code.to_i
-        options = {:status_code => code}
+        options = {:status_code => code, :response => parse_response(response)}
         if code >= 200 && code < 300
           options[:remote_configuration] = parse_remote_configuration(response)
           return Ports::TransportResult.new(:success, options)
@@ -116,6 +121,35 @@ module Chronos
         Ports::TransportResult.new(:client_error, options)
       end
 
+      def read_bounded_response(response)
+        body = ""
+        overflow = false
+        response.read_body do |chunk|
+          next if overflow
+
+          remaining = RESPONSE_BODY_MAX_BYTES - body.bytesize
+          if chunk.bytesize > remaining
+            overflow = true
+          else
+            body << chunk
+          end
+        end
+        response.instance_variable_set(:@chronos_response_body, overflow ? nil : body)
+      end
+
+      def parse_response(response)
+        content_type = response["Content-Type"].to_s.split(";", 2).first
+        return nil unless content_type == "application/json"
+
+        body = response.instance_variable_get(:@chronos_response_body)
+        return nil if body.nil? || body.empty?
+
+        parsed = JSON.parse(body)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
       def parse_remote_configuration(response)
         return nil unless @config.remote_configuration
 

data/lib/chronos/agent.rb

@@ -50,6 +50,24 @@ module Chronos
       @capture.call_sync(exception, context_for_capture(context))
     end
 
+    def verify_integration
+      @verification.call
+    rescue StandardError => error
+      @logger.warn("Chronos integration verification failed: #{error.class}")
+      Core::IntegrationVerificationResult.new(
+        :success => false,
+        :status => "verification_failed",
+        :credentials_valid => nil,
+        :event => {"id" => nil, "received" => false},
+        :receiver => {"name" => "chronos", "status" => "not_checked", "received_at" => nil},
+        :error => {
+          "code" => "verification_failed",
+          "message" => "Chronos integration verification failed locally.",
+          "guidance" => "Review the Chronos configuration and retry."
+        }
+      )
+    end
+
     def ignore_if(&block)
       @ignore_policy.add(&block)
     end
@@ -202,6 +220,9 @@ module Chronos
     def initialize_observability(options)
       @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(@config)
       @deploy_normalizer = options[:deploy_normalizer] || Core::DeployNormalizer.new(@config)
+      @verification = options[:verification] || Application::VerifyIntegration.new(
+        @config, @delivery_pipeline, @logger
+      )
     end
 
     def build_context_store(strategy)

data/lib/chronos/application/delivery_pipeline.rb

@@ -42,13 +42,16 @@ module Chronos
       end
 
       def deliver_sync(event)
+        deliver_sync_result(event).success?
+      end
+
+      def deliver_sync_result(event)
         record_pre_delivery(event)
-        result = deliver_with_backlog(event)
-        result && result.success?
+        deliver_with_backlog(event)
       rescue StandardError => error
         diagnose(error)
         store_in_backlog(event)
-        false
+        Ports::TransportResult.new(:network_error, :error => error.class.name)
       end
 
       # WorkerPool delivery entry point. Events were counted when accepted into the queue.

data/lib/chronos/application/verify_integration.rb

@@ -0,0 +1,262 @@
+require "securerandom"
+
+module Chronos
+  module Application
+    # Sends and verifies one synthetic exception against the configured Chronos receiver.
+    #
+    # @responsibility Build an identified test notice, deliver it synchronously, and validate its acknowledgement.
+    # @motivation Verify credentials and end-to-end ingestion without mistaking an empty 2xx for confirmation.
+    # @limits It exposes only allowlisted project/receiver fields and never returns raw server responses.
+    # @collaborators NoticeBuilder, PayloadSerializer, DeliveryPipeline, and IntegrationVerificationResult.
+    # @thread_safety Calls allocate independent IDs and immutable results; collaborators synchronize delivery.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   result = verifier.call
+    #   result.success? #=> true or false
+    # @errors Network, protocol, configuration, and receiver failures become structured results.
+    # @performance Performs one bounded synchronous verification plus configured bounded retries.
+    class VerifyIntegration
+      SCHEMA_VERSION = "1.0".freeze
+      VERIFICATION_KIND = "integration_verification".freeze
+      VERIFICATION_TAG = "chronos-integration-verification".freeze
+
+      def initialize(config, delivery_pipeline, logger = nil, options = {})
+        @config = config
+        @delivery_pipeline = delivery_pipeline
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        @uuid_generator = options[:uuid_generator] || proc { SecureRandom.uuid }
+        @notice_builder = options[:notice_builder] || Core::NoticeBuilder.new(config)
+        @serializer = options[:serializer] || Core::PayloadSerializer.new(
+          config,
+          nil,
+          :max_payload_size => proc { @delivery_pipeline.max_payload_size }
+        )
+      end
+
+      def call
+        verification_id = bounded(@uuid_generator.call, 128)
+        return local_failure("configuration_invalid", verification_id, configuration_guidance) unless configured?
+
+        event = build_event(verification_id)
+        transport_result = @delivery_pipeline.deliver_sync_result(event)
+        classify(transport_result, verification_id, event.event_id)
+      rescue StandardError => error
+        @logger.warn("Chronos integration verification failed: #{error.class}")
+        local_failure("verification_failed", verification_id, "Review the Chronos configuration and retry.")
+      end
+
+      private
+
+      def configured?
+        !@config.project_id.to_s.empty? && !@config.project_key.to_s.empty? && !@config.host.to_s.empty?
+      end
+
+      def build_event(verification_id)
+        marker = {
+          "schema_version" => SCHEMA_VERSION,
+          "verification_id" => verification_id,
+          "kind" => VERIFICATION_KIND,
+          "test" => true
+        }
+        notice = @notice_builder.call(
+          IntegrationVerificationError.new("Chronos integration verification test"),
+          :severity => "info",
+          :context => {"integration_verification" => marker},
+          :tags => [VERIFICATION_TAG],
+          :fingerprint => VERIFICATION_TAG
+        )
+        @serializer.call(notice)
+      end
+
+      def classify(result, verification_id, event_id)
+        return classify_success(result.response, verification_id, event_id) if result.success?
+        if inactive_response?(result, verification_id, event_id)
+          return project_inactive(result.response, verification_id, event_id)
+        end
+        return invalid_credentials(verification_id, event_id) if [401, 403].include?(result.status_code)
+        return rate_limited(verification_id, event_id) if result.status == :rate_limited
+        return receiver_unavailable(verification_id, event_id) if unavailable?(result)
+        return receiver_internal_error(verification_id, event_id) if result.status == :server_error
+
+        request_rejected(verification_id, event_id)
+      end
+
+      def classify_success(response, verification_id, event_id)
+        unless valid_acknowledgement?(response, verification_id, event_id)
+          return failure("invalid_response", verification_id, event_id,
+                         :receiver_status => "reachable",
+                         :message => "Chronos returned a response outside the verification contract.",
+                         :guidance => "Update Chronos to the integration verification response v1 contract.")
+        end
+
+        Core::IntegrationVerificationResult.new(
+          :success => true,
+          :status => "verified",
+          :verification_id => verification_id,
+          :credentials_valid => true,
+          :event => {"id" => event_id, "received" => true},
+          :project => safe_project(response["project"]),
+          :receiver => safe_receiver(response["receiver"]),
+          :error => nil
+        )
+      end
+
+      def valid_acknowledgement?(response, verification_id, event_id)
+        valid_response_structure?(response) &&
+          acknowledgement_matches?(response, verification_id, event_id) &&
+          active_project?(response["project"]) && operational_receiver?(response["receiver"])
+      end
+
+      def valid_response_structure?(response)
+        exact_keys?(response, %w(
+                      schema_version success status verification_id credentials_valid event_received
+                      event project receiver error
+                    )) &&
+          exact_keys?(response["event"], %w(id)) &&
+          exact_keys?(response["project"], %w(id name status environment)) &&
+          exact_keys?(response["receiver"], %w(name status received_at))
+      end
+
+      def acknowledgement_matches?(response, verification_id, event_id)
+        response["schema_version"] == SCHEMA_VERSION && response["verification_id"] == verification_id &&
+          response["status"] == "accepted" && response["success"] == true &&
+          response["credentials_valid"] == true && response["event_received"] == true &&
+          hash_value(response["event"])["id"] == event_id && response["error"].nil?
+      end
+
+      def active_project?(project)
+        hash_value(project)["id"] == @config.project_id.to_s && hash_value(project)["status"] == "active"
+      end
+
+      def operational_receiver?(receiver)
+        hash_value(receiver)["status"] == "operational"
+      end
+
+      def inactive_response?(result, verification_id, event_id)
+        response = result.response
+        result.status_code == 403 && valid_response_structure?(response) &&
+          inactive_state?(response) && inactive_correlation?(response, verification_id, event_id)
+      end
+
+      def inactive_state?(response)
+        response["schema_version"] == SCHEMA_VERSION && response["success"] == false &&
+          response["status"] == "project_inactive" && response["credentials_valid"] == true &&
+          response["event_received"] == false && hash_value(response["project"])["status"] == "inactive" &&
+          valid_error?(response["error"])
+      end
+
+      def inactive_correlation?(response, verification_id, event_id)
+        response["verification_id"] == verification_id && hash_value(response["event"])["id"] == event_id &&
+          hash_value(response["project"])["id"] == @config.project_id.to_s
+      end
+
+      def valid_error?(error)
+        exact_keys?(error, %w(code message guidance)) && error["code"] == "project_inactive"
+      end
+
+      def project_inactive(response, verification_id, event_id)
+        failure("project_inactive", verification_id, event_id,
+                :credentials_valid => true, :receiver_status => "reachable",
+                :message => "The Chronos project is inactive and did not accept the verification event.",
+                :guidance => "Activate the project in Chronos or select an active project, then retry.",
+                :project => safe_project(response["project"]))
+      end
+
+      def invalid_credentials(verification_id, event_id)
+        failure("invalid_credentials", verification_id, event_id,
+                :credentials_valid => false, :receiver_status => "reachable",
+                :message => "Chronos rejected the project credentials.",
+                :guidance => "Create an active project API key, then confirm project_id and project_key.")
+      end
+
+      def rate_limited(verification_id, event_id)
+        failure("rate_limited", verification_id, event_id,
+                :receiver_status => "reachable",
+                :message => "Chronos temporarily rate limited the verification request.",
+                :guidance => "Wait before retrying and review the project ingestion limits.")
+      end
+
+      def receiver_internal_error(verification_id, event_id)
+        failure("receiver_internal_error", verification_id, event_id,
+                :receiver_status => "error",
+                :message => "Chronos encountered an internal error while processing the verification.",
+                :guidance => "Retry later or contact the Chronos operator with the verification_id.")
+      end
+
+      def receiver_unavailable(verification_id, event_id)
+        failure("receiver_unavailable", verification_id, event_id,
+                :receiver_status => "unavailable",
+                :message => "The Chronos receiver is unavailable or could not be reached.",
+                :guidance => "Check the host, DNS, TLS, network access, and Chronos service status.")
+      end
+
+      def request_rejected(verification_id, event_id)
+        failure("request_rejected", verification_id, event_id,
+                :receiver_status => "reachable",
+                :message => "Chronos rejected the integration verification request.",
+                :guidance => "Confirm that the gem and Chronos support the verification v1 contract.")
+      end
+
+      def unavailable?(result)
+        [:network_error, :request_timeout, :circuit_open].include?(result.status) ||
+          [502, 503, 504].include?(result.status_code)
+      end
+
+      def failure(status, verification_id, event_id, options = {})
+        Core::IntegrationVerificationResult.new(
+          :success => false,
+          :status => status,
+          :verification_id => verification_id,
+          :credentials_valid => options[:credentials_valid],
+          :event => {"id" => event_id, "received" => false},
+          :project => options[:project],
+          :receiver => {"name" => "chronos", "status" => options[:receiver_status], "received_at" => nil},
+          :error => {"code" => status, "message" => options[:message], "guidance" => options[:guidance]}
+        )
+      end
+
+      def local_failure(status, verification_id, guidance)
+        failure(status, verification_id, nil,
+                :receiver_status => "not_checked",
+                :message => "Chronos integration verification could not be started.",
+                :guidance => guidance)
+      end
+
+      def configuration_guidance
+        "Configure a non-empty project_id, project_key, and HTTPS host before running verification."
+      end
+
+      def safe_project(value)
+        safe_fields(value, "id" => 128, "name" => 128, "status" => 32, "environment" => 128)
+      end
+
+      def safe_receiver(value)
+        safe_fields(value, "name" => 64, "status" => 32, "received_at" => 64)
+      end
+
+      def safe_fields(value, fields)
+        source = hash_value(value)
+        fields.each_with_object({}) do |(name, limit), result|
+          result[name] = source[name].nil? ? nil : bounded(source[name], limit)
+        end
+      end
+
+      def hash_value(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def exact_keys?(value, keys)
+        value.is_a?(Hash) && value.keys.sort == keys.sort
+      end
+
+      def bounded(value, limit)
+        text = value.to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+        return text if text.bytesize <= limit
+
+        text.byteslice(0, limit).to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/core/integration_verification_result.rb

@@ -0,0 +1,108 @@
+require "json"
+
+module Chronos
+  module Core
+    # Immutable result returned by an explicit Chronos integration verification.
+    #
+    # @responsibility Expose a bounded, JSON-safe verification outcome to Ruby and Rake callers.
+    # @motivation Report credential, receiver, and acknowledgement state without exposing raw responses.
+    # @limits It never includes project keys, response bodies, stack traces, or receiver internals.
+    # @collaborators VerifyIntegration and Chronos::RakeTasks.
+    # @thread_safety The object and all nested values are immutable after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   result = Chronos.verify_integration
+    #   puts result.to_json
+    # @errors Invalid input is normalized to safe empty values.
+    # @performance Construction visits only the small allowlisted verification response.
+    class IntegrationVerificationResult
+      SCHEMA_VERSION = "1.0".freeze
+
+      attr_reader :status, :verification_id, :credentials_valid, :event,
+                  :project, :receiver, :error
+
+      def initialize(attributes = {})
+        @success = attributes[:success] == true
+        @status = safe_string(attributes[:status], 64)
+        @verification_id = optional_string(attributes[:verification_id], 128)
+        @credentials_valid = boolean_or_nil(attributes[:credentials_valid])
+        @event = immutable_copy(hash_value(attributes[:event]))
+        @project = optional_hash(attributes[:project])
+        @receiver = optional_hash(attributes[:receiver])
+        @error = optional_hash(attributes[:error])
+        freeze
+      end
+
+      def success?
+        @success
+      end
+
+      def to_h
+        {
+          "schema_version" => SCHEMA_VERSION,
+          "success" => success?,
+          "status" => status,
+          "verification_id" => verification_id,
+          "credentials_valid" => credentials_valid,
+          "event_received" => event["received"] == true,
+          "event" => event,
+          "project" => project,
+          "receiver" => receiver,
+          "error" => error
+        }
+      end
+
+      def to_json(*arguments)
+        JSON.generate(to_h, *arguments)
+      end
+
+      private
+
+      def optional_hash(value)
+        value.is_a?(Hash) ? immutable_copy(value) : nil
+      end
+
+      def hash_value(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def boolean_or_nil(value)
+        [true, false].include?(value) ? value : nil
+      end
+
+      def optional_string(value, limit)
+        return nil if value.nil?
+
+        safe_string(value, limit)
+      end
+
+      def safe_string(value, limit)
+        text = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : ""
+        text = text.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+        return text if text.bytesize <= limit
+
+        text.byteslice(0, limit).to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+      rescue StandardError
+        ""
+      end
+
+      def immutable_copy(value)
+        copy = case value
+               when Hash
+                 value.each_with_object({}) do |(key, child), result|
+                   result[safe_string(key, 64)] = immutable_copy(child)
+                 end
+               when Array
+                 value.first(20).map { |child| immutable_copy(child) }
+               when String
+                 safe_string(value, 512)
+               when NilClass, TrueClass, FalseClass, Numeric
+                 value
+               else
+                 ""
+               end
+        copy.freeze
+      end
+    end
+  end
+end

data/lib/chronos/errors.rb

@@ -21,4 +21,15 @@ module Chronos
   # @example
   #   Chronos.configure { |config| config.project_key = nil }
   class ConfigurationError < Error; end
+
+  # Synthetic exception sent only by an explicit integration verification.
+  #
+  # @responsibility Give verification notices a stable, recognizable exception class.
+  # @motivation Let the Chronos receiver distinguish an integration check from an application failure.
+  # @limits It is never raised into the host application and carries no application data.
+  # @thread_safety A fresh instance is created for each verification.
+  # @compatibility Ruby 2.2.10 and newer legacy runtimes.
+  # @example
+  #   Chronos.verify_integration
+  class IntegrationVerificationError < Error; end
 end

data/lib/chronos/ports/transport.rb

@@ -8,7 +8,7 @@ module Chronos
     # @thread_safety Immutable after construction.
     # @compatibility Ruby 2.2.10 through Ruby 2.6.
     class TransportResult
-      attr_reader :status, :status_code, :retry_after, :error, :remote_configuration
+      attr_reader :status, :status_code, :retry_after, :error, :remote_configuration, :response
 
       def initialize(status, options = {})
         @status = status
@@ -16,6 +16,7 @@ module Chronos
         @retry_after = options[:retry_after]
         @error = options[:error]
         @remote_configuration = options[:remote_configuration]
+        @response = deep_freeze(options[:response])
         freeze
       end
 
@@ -26,6 +27,22 @@ module Chronos
       def retryable?
         [:request_timeout, :rate_limited, :server_error, :network_error].include?(status)
       end
+
+      private
+
+      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
+      rescue StandardError
+        nil
+      end
     end
 
     # Conceptual transport port implemented by delivery adapters.

data/lib/chronos/rails/railtie.rb

@@ -16,6 +16,11 @@ module Chronos
       initializer "chronos.install", :after => :load_config_initializers do |application|
         Chronos::Rails::Installer.new.install(application)
       end
+
+      rake_tasks do
+        require "chronos/rake_tasks"
+        Chronos::RakeTasks.install(:load_environment => true)
+      end
     end
   end
 end

data/lib/chronos/rake_tasks.rb

@@ -0,0 +1,41 @@
+require "json"
+require "rake"
+require "chronos"
+
+module Chronos
+  # Installs explicit Rake commands supplied by the Chronos gem.
+  #
+  # @responsibility Register the integration verification task with deterministic JSON output.
+  # @motivation Give Rails and plain Ruby operators one repeatable end-to-end credential check.
+  # @limits It never reads environment variables, prints credentials, or modifies application data.
+  # @collaborators Rake and Chronos.verify_integration.
+  # @thread_safety Installation checks the process-global Rake registry and is intended for boot time.
+  # @compatibility Rake versions compatible with Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   require "chronos/rake_tasks"
+  #   Chronos::RakeTasks.install
+  # @errors Verification failures produce JSON and a nonzero process status.
+  # @performance The task performs one explicit synchronous verification when invoked.
+  module RakeTasks
+    extend ::Rake::DSL
+
+    TASK_NAME = "chronos:verify_integration".freeze
+
+    def self.install(options = {})
+      return false if ::Rake::Task.task_defined?(TASK_NAME)
+
+      output = options[:output] || $stdout
+      exiter = options[:exit] || proc { |status| exit(status) }
+      load_environment = options[:load_environment] || ::Rake::Task.task_defined?("environment")
+      prerequisites = load_environment ? ["environment"] : []
+
+      desc "Send an identified fake error and verify Chronos credentials and ingestion"
+      task TASK_NAME => prerequisites do
+        result = Chronos.verify_integration
+        output.puts(JSON.generate(result.to_h))
+        exiter.call(1) unless result.success?
+      end
+      true
+    end
+  end
+end

data/lib/chronos/version.rb

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

data/lib/chronos.rb

@@ -7,6 +7,7 @@ require "chronos/ports"
 require "chronos/adapters"
 require "chronos/internal"
 require "chronos/core/notice"
+require "chronos/core/integration_verification_result"
 require "chronos/core/backtrace_parser"
 require "chronos/core/exception_cause_collector"
 require "chronos/core/runtime_info"
@@ -36,6 +37,7 @@ require "chronos/application/remote_configuration"
 require "chronos/application/ignore_policy"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
+require "chronos/application/verify_integration"
 require "chronos/application/apm_error_classifier"
 require "chronos/application/apm_aggregator"
 require "chronos/application/dependency_reporter"
@@ -95,6 +97,21 @@ module Chronos # rubocop:disable Metrics/ModuleLength
       false
     end
 
+    def verify_integration
+      agent = current_agent
+      return agent.verify_integration if agent
+
+      verification_failure(
+        "not_configured", "Chronos is not configured.",
+        "Run Chronos.configure before verifying the integration."
+      )
+    rescue StandardError
+      verification_failure(
+        "verification_failed", "Chronos integration verification failed locally.",
+        "Review the Chronos configuration and retry."
+      )
+    end
+
     def with_context(context = {})
       agent = current_agent
       return yield unless agent
@@ -186,6 +203,15 @@ module Chronos # rubocop:disable Metrics/ModuleLength
     def current_agent
       @mutex.synchronize { @agent }
     end
+
+    def verification_failure(status, message, guidance)
+      Core::IntegrationVerificationResult.new(
+        :success => false, :status => status, :credentials_valid => nil,
+        :event => {"id" => nil, "received" => false},
+        :receiver => {"name" => "chronos", "status" => "not_checked", "received_at" => nil},
+        :error => {"code" => status, "message" => message, "guidance" => guidance}
+      )
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.9.0.pre.3
+  version: 0.9.0.pre.4
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -72,6 +72,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.49.0
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.19.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.19.2
 description: Base do cliente Chronos para excecoes, telemetria e observabilidade em
   aplicacoes Ruby legadas.
 email:
@@ -90,6 +104,7 @@ files:
 - contracts/dependencies-v1.schema.json
 - contracts/deploy-v1.schema.json
 - contracts/event-v1.schema.json
+- contracts/integration-verification-response-v1.schema.json
 - contracts/rack-context-v1.schema.json
 - contracts/sidekiq-job-v1.schema.json
 - docs/adr/ADR-001-core-and-integrations.md
@@ -122,6 +137,7 @@ files:
 - docs/modules/deploy-tracking.md
 - docs/modules/external-http.md
 - docs/modules/ignore-rules.md
+- docs/modules/integration-verification.md
 - docs/modules/notice-pipeline.md
 - docs/modules/rack-context.md
 - docs/modules/rails-legacy.md
@@ -155,6 +171,7 @@ files:
 - lib/chronos/application/ignore_policy.rb
 - lib/chronos/application/remote_configuration.rb
 - lib/chronos/application/retry_policy.rb
+- lib/chronos/application/verify_integration.rb
 - lib/chronos/capistrano.rb
 - lib/chronos/configuration.rb
 - lib/chronos/configuration/apm_validation.rb
@@ -167,6 +184,7 @@ files:
 - lib/chronos/core/correlation_context.rb
 - lib/chronos/core/deploy_normalizer.rb
 - lib/chronos/core/exception_cause_collector.rb
+- lib/chronos/core/integration_verification_result.rb
 - lib/chronos/core/metric_aggregate.rb
 - lib/chronos/core/notice.rb
 - lib/chronos/core/notice_builder.rb
@@ -200,6 +218,7 @@ files:
 - lib/chronos/rails/installer.rb
 - lib/chronos/rails/notifications_subscriber.rb
 - lib/chronos/rails/railtie.rb
+- lib/chronos/rake_tasks.rb
 - lib/chronos/ruby.rb
 - lib/chronos/ruby/version.rb
 - lib/chronos/sidekiq.rb