hawk-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 917927100fe40addf2591185b4a00783f4bc53cee3311f521c8c1aeb7633ecc6
+  data.tar.gz: 83af5651bb2fa4f112faf997dcda6c01982112ecc6de2113bd5564c46c2a1288
+SHA512:
+  metadata.gz: f0d2a287b931372819ddf3d8ae6f14e2e3284ecdb2475d235f58dbe77776b171398fdfcd3cf815b2fae0691c5cdd3b68d395aa1c17f504b7f78497fff77e68f2
+  data.tar.gz: db9adaf226efcdea53862e25c0f184d5e53fd918afd084e88333f11d586c195a516dc0f21b49b71c0559c72698735f84b9035a7155458d0f9ac2b6b3d3fc9172

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-10-29
+
+Initial release of the Hawk Ruby error reporting gem.
+
+- Report exceptions and messages with backtraces, source snippets, breadcrumbs, user data, context, severity, and application release identifiers.
+- Add optional Rack, Rails, Rails error reporter, Action Cable, Active Job, Solid Queue, Sidekiq, Resque, Delayed Job, and Rake integration.
+- Provide bounded asynchronous delivery, execution-local scopes, duplicate suppression, fork recovery, privacy filters, and event hooks.
+- Ship RBS signatures and enforce complete type coverage, 100% line and branch coverage, and measured CRAP scores no greater than 10.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonid Svyatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# Hawk Ruby
+
+Ruby error reporting for [Hawk](https://hawk.so), with optional Rails and background job integrations.
+
+The gem reports exceptions, messages, backtraces, source snippets, breadcrumbs, users, context, and application releases. It uses Hawk's native collector format.
+
+## Install
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "hawk-ruby", "~> 0.1.0", require: "hawk"
+```
+
+```sh
+bundle install
+```
+
+To test a built artifact locally:
+
+```sh
+gem build hawk-ruby.gemspec
+gem install ./hawk-ruby-0.1.0.gem
+```
+
+The core requires CRuby 3.3 or later and packaged standard libraries. Rails and job frameworks are optional.
+
+## Configure and capture
+
+Copy the integration token from your Hawk project into `HAWK_TOKEN`.
+
+```ruby
+require "hawk"
+
+Hawk.init do |config|
+  config.token = ENV.fetch("HAWK_TOKEN")
+  config.release = ENV["HAWK_RELEASE"]
+end
+
+Hawk.set_context(component: "checkout")
+Hawk.set_user(id: "customer-42")
+Hawk.add_breadcrumb(message: "Payment started", category: "checkout")
+
+Hawk.capture do
+  perform_checkout
+end
+
+Hawk.capture_message("Checkout recovered", level: :warning)
+Hawk.flush(timeout: 5.0)
+```
+
+`Hawk.capture` reports an escaping exception and raises the same exception again. You can also call `Hawk.capture_exception(error)` from a rescue handler.
+
+A missing or empty token disables reporting. A malformed nonempty token raises `Hawk::ConfigurationError` during initialization.
+
+## Rails and background jobs
+
+Use `require: "hawk/rails"` in your Gemfile for Rails. Initialize Hawk in `config/initializers/hawk.rb` before workers start.
+
+Rails enables request capture, `Rails.error`, Action Cable, Active Job, and safe notification breadcrumbs. Solid Queue works through Active Job.
+
+Load each additional adapter explicitly:
+
+```ruby
+require "hawk/rack"
+require "hawk/rake"
+require "hawk/sidekiq"
+require "hawk/resque"
+require "hawk/delayed_job"
+```
+
+Rails also detects loaded job backends during initialization. The adapters preserve native retries, arguments, and failure storage.
+
+See [integrations](docs/integrations.md) for placement, supported versions, propagation limits, and exclusions.
+
+## Delivery and privacy
+
+The default client uses one background thread and a queue of 100 events. Capture never waits for queue space. Each delivery makes one bounded HTTP attempt.
+
+The queue is held in memory. An accepted capture ID confirms local acceptance. `flush` confirms that pending attempts finished, including failed attempts.
+
+Request bodies, headers, cookies, and job arguments are excluded by default. Sensitive keys are filtered before hooks run. Review [configuration](docs/configuration.md) before enabling additional data.
+
+Source snippets are enabled within configured source roots. Set `send_source = false` to exclude them.
+
+## Development checks
+
+```sh
+bundle exec rake check:fast
+bundle exec rake check:coverage
+bundle exec rake check:crap
+bundle exec rake check:audit
+bundle exec rake test:package
+```
+
+Coverage runs the 13 compatibility lanes for the current Ruby. Install their bundles first with `bundle install --gemfile gemfiles/NAME.gemfile`.
+
+The CI workflow defines 39 runtime combinations across Ruby 3.3, 3.4, and 4.0. It enforces complete types, 100% line and branch coverage, and measured CRAP scores at most 10.
+
+Use `bundle exec rake check:complexity` for local complexity feedback without coverage. See [verification](docs/verification.md) for observed results and remaining acceptance gaps.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/docs/configuration.md

@@ -0,0 +1,160 @@
+# Configuration
+
+Configure the default client once, before requests or jobs begin. Reinitialization closes the previous default client.
+
+```ruby
+Hawk.init do |config|
+  config.token = ENV.fetch("HAWK_TOKEN")
+  config.environment = "production"
+  config.enabled_environments = ["production", "staging"]
+  config.source_roots = [File.expand_path("..", __dir__)]
+  config.filter_parameters = ["session_id", /private_/i]
+end
+```
+
+## Identity and capture policy
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `token` | `ENV['HAWK_TOKEN']` | Hawk project integration token |
+| `endpoint` | Derived HTTPS collector | Custom HTTPS endpoint; HTTP permits loopback IP literals only |
+| `environment` | `RAILS_ENV`, `RACK_ENV`, or `development` | Event environment |
+| `enabled_environments` | `nil` | All environments; an array restricts capture |
+| `release` | `HAWK_RELEASE` or `REVISION` | Application revision attached to events |
+| `detect_release` | `false` | Detect Git revision once during initialization, with a one-second deadline |
+| `sample_rate` | `1.0` | Capture probability between zero and one |
+| `ignored_exceptions` | `[]` | Exception ancestor names to exclude |
+| `global_errors` | `true` | Capture uncaught main-process exceptions and drain at exit |
+| `context`, `user` | `{}`, `nil` | Initial explicit context and user |
+
+Automatic reporting excludes `SystemExit`, `SignalException`, and `Interrupt`. Manual exception capture remains available for those classes.
+
+Automatic request reporting also excludes routing errors, missing actions, and missing Active Record records. Explicit `Rails.error.report` calls remain reportable.
+
+## Delivery
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `delivery_mode` | `:async` | Use one queue worker; `:sync` performs the attempt in the caller |
+| `queue_capacity` | `100` | Maximum waiting events; a full queue rejects new captures |
+| `connect_timeout` | `1.0` | Connection timeout in seconds |
+| `read_timeout`, `write_timeout` | `2.0` | Socket timeouts in seconds |
+| `flush_timeout` | `5.0` | Default flush and close deadline |
+| `limit_cooldown` | `60.0` | Default cooldown after collector limits |
+
+Each HTTP attempt has an additional five-second total deadline. Redirects and ambiguous transport failures are not retried.
+
+Collector responses must contain a successful HTTP status of 200 and a JSON body with `code: 200` and `error: false`.
+
+Responses with status 402 or 429 pause sends. Valid `Retry-After` seconds or dates are bounded to 300 seconds.
+
+`Hawk.flush(timeout: 5.0)` waits for pending attempts. `Hawk.close(timeout: 5.0)` also stops accepting new events.
+
+A false return means the operation could not finish within its contract. A true flush does not establish successful receipt by Hawk.
+
+Forked children discard inherited queues and recreate synchronization before use. Parents retain their own queues. Abrupt termination can lose pending events.
+
+## Scope and independent clients
+
+Scopes are local to each client, thread, and fiber. `with_scope` copies current values and restores the parent scope after the block.
+
+```ruby
+Hawk.with_scope do |scope|
+  scope.set_context(order_id: "order-42")
+  scope.set_user(id: "customer-42")
+  Hawk.capture_message("Order accepted")
+end
+
+configuration = Hawk::Configuration.new
+configuration.token = ENV.fetch("OTHER_HAWK_TOKEN")
+other = Hawk::Client.build(configuration)
+other.capture_exception(RuntimeError.new("Independent project"))
+other.close
+```
+
+Automatic request, channel, and job boundaries start fresh scopes. Explicit global configuration supplies their initial context.
+
+Events receive an anonymous user identifier when no explicit identifier exists. That identifier is scoped to the execution and is not propagated to jobs.
+
+Manual captures can repeat. Automatic captures suppress repeated propagation of the same exception object within one execution.
+
+Owned request and job boundaries retain at most 256 exception identities and reject additional automatic reports within that boundary. Outside those boundaries, the ledger evicts its oldest identity so long-running reporting continues. An evicted exception can be reported again.
+
+## Privacy and limits
+
+| Setting | Default |
+| --- | --- |
+| `include_headers`, `include_cookies` | `false` |
+| `include_request_body`, `include_job_arguments` | `false` |
+| `propagate_job_context` | `true` |
+| `filter_parameters` | `[]` |
+| `send_source` | `true` |
+| `source_roots` | `[Dir.pwd]` |
+
+Built-in filtering covers sensitive key names, including passwords, secrets, authorization, API keys, and payment cards. Add application-specific names to `filter_parameters`.
+
+Rails also applies `config.filter_parameters`. Opted-in raw bodies and cookie strings need explicit filtering or exclusion when their contents contain secrets.
+
+Cookie headers are excluded from generic header capture. Only `include_cookies` enables the dedicated cookie field. Rails filters receive each original parameter or context tree once; stored breadcrumbs and propagated job values retain their filtered state.
+
+The SDK uses parsed parameters already present in the request environment. It does not read or rewind the request input stream.
+
+Source files must resolve inside a configured root. Source extraction excludes missing files, symlink escapes, nonregular files, and files over 1 MiB.
+
+Events contain at most 100 backtrace frames, 10 causes, and 50 breadcrumbs. Source excerpts contain at most 11 lines.
+
+JSON copying bounds depth, collection width, strings, and total nodes. It does not call application serializers or `inspect`.
+
+Encoded events are limited to 256 KiB. Size reduction removes source snippets and optional detail before reducing backtraces. Events that remain oversized are dropped.
+
+## Hooks and breadcrumbs
+
+`before_send` receives detached, filtered event data without the integration token. Return a hash to send, or `nil` to drop.
+
+`before_breadcrumb` receives a detached, filtered breadcrumb. Return a hash to retain it, or `nil` to drop.
+
+```ruby
+Hawk.init do |config|
+  config.before_send = ->(event) { event.merge("title" => "Application failure") }
+  config.before_breadcrumb = ->(entry) { entry }
+  config.breadcrumbs_logger = true
+  config.breadcrumbs_http = true
+  config.logger_error_level = Logger::ERROR
+end
+```
+
+Hook errors or invalid results drop only the affected event or breadcrumb. Hooks can add data, so their output needs the same privacy review as application logging.
+
+Automatic Logger, HTTP, and Rails breadcrumb instrumentation is suppressed while SDK hooks run. Application logging and message-block evaluation continue normally.
+
+Logger and Net::HTTP breadcrumbs require opt-in. Logger messages use normal Logger evaluation. HTTP breadcrumbs omit queries, credentials, headers, and bodies.
+
+Rails notifications record operation names and timing. SQL text, bindings, mail content, and job arguments are excluded by default.
+
+`breadcrumbs_rails` defaults to true with Rails. Set `logger_error_level` to convert qualifying logger messages into events; it defaults to disabled.
+
+## Integration controls and diagnostics
+
+Set entries in `integrations` to false to disable `:rails`, `:rack`, `:rake`, `:action_cable`, `:active_job`, `:sidekiq`, `:resque`, or `:delayed_job`.
+
+The `:rails` switch also controls Rails error reports, Cable, Active Job, and Rails breadcrumbs after reinitialization. Direct backend adapters retain their own switches.
+
+`diagnostic_callback` receives counter snapshots. `diagnostic_logger` receives sanitized warning messages with the same counters.
+
+```ruby
+Hawk.init do |config|
+  config.diagnostic_callback = ->(counts) { report_delivery_counters(counts) }
+end
+
+Hawk.client.diagnostics.snapshot
+```
+
+Counters include `sent`, `failed`, `overflow`, `filtered`, and `duplicate_overflow`. Only observed counters appear. Diagnostic failures do not replace application results.
+
+## Releases
+
+Set `HAWK_RELEASE` to the revision deployed with the application. Use the same identifier when uploading commit metadata through [Hawk's release uploader](https://github.com/codex-team/hawk.releases).
+
+The uploader documents the `codex-team/hawk.releases@v1` action with `release` and `token` inputs. Run it during deployment.
+
+[Hawk associates events and releases by matching release names](https://docs.hawk.so/releases). This gem attaches the identifier; deployment tooling uploads the commit metadata.

data/docs/integrations.md

@@ -0,0 +1,149 @@
+# Integrations
+
+Load optional adapters before workers start. Keep their framework gems in the application's Gemfile.
+
+## Supported versions
+
+| Component | Tested versions |
+| --- | --- |
+| CRuby | 3.3.11, 3.4.9, 4.0.9 |
+| Rails, Active Job, Action Cable | 7.2.4, 8.0.5.1, 8.1.4 |
+| Rack | 2.2.24, 3.2.7 |
+| Sidekiq | 7.3.10, 8.1.7 |
+| Resque | 2.7.0 |
+| Delayed Job, Active Record backend | 4.2.0, 4.1.11 |
+| Solid Queue | 1.7.0 |
+| Rake | 13.4.2 |
+
+Sidekiq 8.1.7 and Rails 7.2.4 cannot share a bundle: their `connection_pool` requirements conflict. Sidekiq 7 runs with Rails 7.2 and 8.1.
+
+The adapters guard their supported framework versions. Resque activation requires version 2.7.0. The core uses normal RubyGems or Bundler activation.
+
+## Rack
+
+```ruby
+require "hawk/rack"
+
+Hawk.init { |config| config.token = ENV.fetch("HAWK_TOKEN") }
+use Hawk::Rack
+run Application.new
+```
+
+Place Hawk inside middleware that consumes application exceptions. It must receive the escaping error to report it.
+
+The middleware retains request scope through response iteration, callable streaming bodies, and close. File bodies retain their `to_path` protocol.
+
+Request metadata includes method, path, available parsed parameters, request ID, controller, and action. Raw query strings and request input streams are excluded.
+
+Use `Hawk::Rack.new(app, client: other_client)` for an independent project client.
+
+## Rails requests and framework reports
+
+Use `require: "hawk/rails"` in your Gemfile. The Railtie inserts Hawk inside `ActionDispatch::DebugExceptions`.
+
+```ruby
+# config/initializers/hawk.rb
+Hawk.init do |config|
+  config.token = ENV.fetch("HAWK_TOKEN")
+  config.environment = Rails.env
+  config.release = ENV["HAWK_RELEASE"]
+end
+```
+
+If Rails is already loaded, requiring `hawk` also discovers its Railtie. Rails filtering runs before the application's `before_send` hook.
+
+The subscriber records explicit `Rails.error.report` calls, including handled errors and severity. Request dispatch reports share ownership with middleware to prevent duplicates.
+
+Automatic requests exclude `ActionController::RoutingError`, `AbstractController::ActionNotFound`, `ActionController::UnknownAction`, and `ActiveRecord::RecordNotFound`.
+
+Explicit framework reports and manual captures can still report those exceptions.
+
+## Action Cable
+
+The Rails adapter wraps channel actions, subscription changes, and connection open and close operations. Each invocation receives a fresh scope.
+
+Application rescue handlers keep their normal return values and behavior. Hawk observes errors consumed by Cable's handler path.
+
+Metadata includes the channel or connection class and operation. Message bodies and inferred application identities are excluded.
+
+## Active Job and Solid Queue
+
+Rails activates the Active Job adapter. It covers direct execution, backend execution, deserialization errors, terminal discards, and exhausted retries.
+
+Native retry schedules and application rescue handlers remain unchanged. Intermediate handled retries generate events only when Rails explicitly reports them.
+
+```ruby
+Hawk.with_scope do
+  Hawk.set_context(section: "checkout")
+  Hawk.set_user(id: "customer-42")
+  ReceiptJob.perform_later("order-42")
+end
+```
+
+The serialized job receives a separate `hawk` field containing versioned explicit context and user data. Job arguments remain unchanged.
+
+Metadata is filtered, JSON-only, and limited to 8 KiB. Malformed, oversized, or unknown-version metadata is ignored.
+
+Version 1 metadata is filtered by its producer. Consumers preserve that state, including when a job enqueues another job. Use the same custom Rails privacy filters on producers and consumers; a consumer-only filter change does not transform previously queued values. New explicit scope values and event overrides receive filtering normally.
+
+Automatic request metadata, breadcrumbs, and anonymous users are not propagated. Set `propagate_job_context = false` to disable propagation.
+
+Solid Queue uses this same Active Job contract. Tests exercise its database-backed claim and execution paths.
+
+## Sidekiq
+
+```ruby
+require "hawk/sidekiq"
+```
+
+Client middleware adds versioned context under a separate top-level `hawk` field. Server middleware starts an execution scope.
+
+The backend handler covers failures before server middleware. A failed native attempt produces one automatic event across both paths.
+
+Each failed retry attempt is independently reportable. Active Job retries that Rails handles internally follow the Active Job policy.
+
+The adapter retains native payload arguments and retry behavior. Raw arguments require `include_job_arguments = true`.
+
+## Resque
+
+```ruby
+require "hawk/resque"
+```
+
+The adapter wraps job execution and delegates failure creation to the configured backend. Failed constantization and other failures before execution reach that backend path.
+
+Forked children reset inherited delivery state and flush their own events before Resque exits. A parent does not resend its queued events from a child.
+
+Direct Resque arguments and queue payloads remain unchanged. Direct jobs start fresh explicit scopes because this adapter adds no arbitrary queue metadata.
+
+Active Job wrappers retain their own serialized context. Raw direct arguments require opt-in.
+
+## Delayed Job
+
+```ruby
+require "hawk/delayed_job"
+```
+
+Load the adapter before starting a worker. Its plugin observes perform, error, and failure callbacks, including handler deserialization failures.
+
+Native attempts, retry times, and terminal failure state remain unchanged. Direct job YAML and database columns remain unchanged.
+
+Active Job wrappers carry their own versioned context. Direct jobs start fresh scopes without adding attributes to application payload objects.
+
+## Rake and process shutdown
+
+```ruby
+require "hawk/rake"
+```
+
+The Rake adapter reports escaping task failures and retains original task behavior. Nested task failures share automatic-report ownership.
+
+Core initialization installs one process exit hook when `global_errors` is enabled. It reports eligible uncaught main-process errors and attempts a bounded drain.
+
+Handled application errors require an explicit capture. For independently managed clients, call `close` during application shutdown.
+
+## Scope of this SDK
+
+This SDK implements Hawk error reporting. Tracing, profiling, metrics, cron monitoring, and standalone log ingestion are outside its scope.
+
+Delivery uses an in-memory queue and one attempt per event. Job backends own retries. Use delivery counters to distinguish accepted captures from successful collector responses.

data/docs/releasing.md

@@ -0,0 +1,23 @@
+# Releasing
+
+The `release.yml` workflow publishes version tags after the complete CI matrix passes. The tag must match `Hawk::VERSION` and belong to `main`.
+
+RubyGems trusts the `svyatov/hawk.ruby` repository, the `release.yml` workflow, and the `release` environment. The environment permits `v*` tags.
+
+The workflow builds the gem once, generates its checksum and GitHub provenance attestation, and stores the artifact for 14 days. Publishing downloads those exact bytes.
+
+To cut a version:
+
+1. Update the version, changelog, and installation example. Run the checks and merge to `main`.
+2. Create an annotated version tag, for example `git tag -a v0.1.0 -m 'Release 0.1.0'`.
+3. Push the tag with `git push origin v0.1.0` and monitor the Release workflow.
+
+## Recover a partial publication
+
+Use GitHub's failed-jobs rerun, for example `gh run rerun RUN_ID --failed --repo svyatov/hawk.ruby`. This preserves the successful build and its archived artifact.
+
+If RubyGems already has the version, publication continues only when its SHA256 matches the archived gem. A mismatch or failed registry lookup stops the release.
+
+GitHub releases start as drafts. A retry verifies the tag and commit, uploads missing assets, and publishes the draft. Existing assets must have matching checksums; they are never replaced.
+
+Do not rebuild a published version or move its tag. If the archived artifact has expired, recover and verify the original published bytes before completing the GitHub release.

data/docs/verification.md

@@ -0,0 +1,85 @@
+# Verification
+
+## Local acceptance
+
+The implementation was tested on macOS with CRuby 3.3.11, 3.4.9, and 4.0.9.
+
+All 39 supported runtime combinations passed. Each Ruby's 13 lanes reached 100% line and branch coverage after merging fresh subprocess and fork reports.
+
+The matrix includes separate Rack 2 and 3 bundles, all three Rails versions, Cable, Active Job, and real job backend fixtures.
+
+Redis fixtures start isolated servers. Database fixtures use temporary SQLite files. Tests do not reuse application queues or databases.
+
+| Gate | Observed result |
+| --- | --- |
+| RuboCop 1.92.2 | No offenses |
+| Steep 2.1.0 and Ruby Signature (RBS) 4.2.0 | 37 runtime files, zero untyped calls, valid signatures |
+| SimpleCov 1.3.2 | 100% executable lines and branches |
+| crap4ruby 0.2.1 | All method scores measured, maximum CRAP 7, limit 10 |
+| bundler-audit 0.9.3 | 13 lockfiles, no reported vulnerabilities after database refresh |
+
+Negative gate fixtures reject omitted files, duplicate statistics, failed analysis, untyped calls, invalid counts, unchecked casts, and blanket suppressions.
+
+Coverage fixtures reject stale revisions, changed sources, missing lanes, missing runtime files, and uncovered lines or branches. CRAP checks reject unknown method scores.
+
+Steep internal crashes fail the gate even when Steep returns a successful exit status. Coverage receipts bind CRAP input to the verified source hashes and report hash.
+
+## Resolved framework fixtures
+
+| Family | Resolved versions |
+| --- | --- |
+| Rails | 7.2.4, 8.0.5.1, 8.1.4 |
+| Rack | 2.2.24, 3.2.7 |
+| Sidekiq | 7.3.10, 8.1.7 |
+| Resque | 2.7.0 |
+| Delayed Job and its Active Record backend | 4.2.0, 4.1.11 |
+| Solid Queue and SQLite | 1.7.0, 2.10.2 |
+| Rake | 13.4.2 |
+
+Sidekiq 7 uses Rails 7.2 and 8.1 fixtures. Sidekiq 8 uses Rails 8.1. Bundler rejects Sidekiq 8.1.7 with Rails 7.2.4 because their `connection_pool` requirements conflict.
+
+The matrix is defined in `script/test_lanes.rb`. GitHub Actions consumes that definition and requires all 39 lanes before coverage merging.
+
+## Installed artifact acceptance
+
+Independent runtime QA passed 44 public-interface scenarios on Ruby 4.0.9, including Rails reports and Active Job propagation.
+
+The pass reproduced two defects and verified their fixes: request metadata timing and nonstandard hook exceptions. Regression tests cover both paths.
+
+Final-review regressions and focused public-interface QA also verify cookie controls, Rails parameter roots, bounded duplicate retention, hook logging, integration reinitialization, and filtered job propagation.
+
+`bundle exec rake test:package` builds the gem and installs it into a temporary gem home with only runtime dependencies.
+
+The fixture loads the installed artifact in a core-only Bundler environment. It checks plain-load thread behavior and sends one event to a loopback collector.
+
+The checker compares every packaged runtime file with its checked source, validates installed RBS signatures, and tests isolation from missing optional dependencies.
+
+The package excludes development dependencies, external framework signatures, test fixtures, execution ledgers, coverage reports, and planning documents.
+
+## Reproduce
+
+Install the core bundle and each framework bundle first. Run these checks from the repository root:
+
+```sh
+bundle exec rake check:fast
+bundle exec rake check:coverage
+bundle exec rake check:crap
+bundle exec rake check:audit
+bundle exec rake test:package
+```
+
+Use `mise exec ruby@3.3.11 --` or `mise exec ruby@3.4.9 --` before the commands to select another installed Ruby.
+
+Coverage manifests contain a run identifier, commit, lane, and hashes of all runtime sources. Old runs cannot satisfy the merge gate after sources change.
+
+## Remaining acceptance gaps
+
+Remote Linux results are recorded in the [CI and release workflow runs](https://github.com/svyatov/hawk.ruby/actions). Each release requires the complete CI matrix before publication.
+
+Live Hawk ingestion and UI rendering are unverified. No dedicated live-test token was supplied or used.
+
+Live acceptance must inspect backtraces, source snippets, users, context, breadcrumbs, severity, and grouping in a dedicated Hawk project.
+
+Release association also requires deployment-time commit metadata uploaded with the same release identifier. Local collector tests do not verify that association.
+
+The collector protocol and Ruby event routing were checked against Hawk's documentation and server sources. Live verification remains necessary before a production rollout.

data/lib/hawk/boundary.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Adapters share report ownership while retaining their own execution scopes.
+  module Boundary
+    def self.run(client, kind:, metadata:, inherit: false, &block)
+      client.with_boundary(kind: kind, metadata: metadata, inherit: inherit) do
+        protect(client, kind, &block)
+      end
+    end
+
+    def self.resume(client, scope, &block)
+      client.using_scope(scope) { protect(client, :request, &block) }
+    end
+
+    def self.protect(client, kind)
+      yield
+    rescue Exception => e # rubocop:disable Lint/RescueException -- Preserve original errors across execution boundaries.
+      client.report(e, mechanism: kind.to_s)
+      client.remember_escape(e)
+      raise
+    end
+
+    private_class_method :protect
+  end
+end

data/lib/hawk/breadcrumbs/logger.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Hawk
+  module Breadcrumbs
+    # Logger keeps control of level filtering and lazy block evaluation.
+    module Logger
+      LEVELS = %i[debug info warning error fatal unknown].freeze
+
+      def self.install
+        ::Logger.prepend(Methods) unless ::Logger.ancestors.include?(Methods)
+      end
+
+      def self.record(client, severity, message)
+        normalized = Hawk::JSONValue.normalize(message)
+        text = normalized.is_a?(String) ? normalized : JSON.generate(normalized)
+        level = LEVELS.fetch(severity, :unknown)
+        if client.configuration.breadcrumbs_logger
+          client.add_breadcrumb(category: "logger", message: text,
+                                level: level.to_s)
+        end
+        threshold = client.configuration.logger_error_level
+        client.capture_message(text, level: level) if threshold && severity >= threshold
+      rescue StandardError
+        nil
+      end
+
+      def self.empty_message?(message)
+        case message
+        when nil then true
+        else false
+        end
+      end
+
+      def self.message(value, progname)
+        empty_message?(value) ? progname : value
+      end
+
+      # Calls through Logger's public add entry point, including its log alias.
+      module Methods
+        def add(severity, message = nil, progname = nil, &block)
+          client = Hawk::Breadcrumbs.client(:logger)
+          severity ||= ::Logger::UNKNOWN
+          return super unless client && severity >= level
+
+          if block && Logger.empty_message?(message)
+            # Explicit arguments avoid Steep 2.1's crash with a replacement block.
+            super(severity, message, progname) do # rubocop:disable Style/SuperArguments
+              value = block.call
+              Logger.record(client, severity, value)
+              value
+            end
+          else
+            result = super
+            Logger.record(client, severity, Logger.message(message, progname))
+            result
+          end
+        end
+        alias log add
+      end
+    end
+  end
+end