alplus-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c59904cfc5232b665e00ba30cfb625b7cc6e5677a5c8c135ca323304ab3c2b42
+  data.tar.gz: 12a71a80e9afc040162858477d9989c64f68be877d4a2118f38a5b7eab54507a
+SHA512:
+  metadata.gz: b7774930fbb1e70090d82792b1b57c7b126d416cf1ec1096b8fda3c8d7b0e474765bb622028ec1066d87af4082474e257e2cdf9e4816f1c1ea178103a7f075fe
+  data.tar.gz: f23720f0f9ed1070ceb3f9af63e63898bdbf5a6b1977ecdb32dfe7983cee1fb84decfe285634aa2dee3cedfba13f28166f32fae5eb6a7235c397e15fdf5cf3f3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ALPLUS TECHNOLOGIES S.R.L.
+
+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,89 @@
+# alplus-ruby
+
+Error reporting for [AL+ Observe](https://alplus.dev). Ruby and Rails.
+
+Zero runtime dependencies: `Net::HTTP` and the stdlib only.
+
+## Install
+
+```ruby
+# Gemfile
+gem "alplus-ruby", require: "alplus"
+```
+
+Set `ALPLUS_KEY` (an ingest key with the `ingest` scope).
+
+## Rails
+
+Add the gem. The railtie installs `Alplus::RackMiddleware` and captures
+unhandled exceptions. No further wiring is required.
+
+Identify the current user in a `before_action`:
+
+```ruby
+Alplus.set_user(id: user.id, email: user.email)
+Alplus.set_tag("org_id", org.id)
+```
+
+## Capture
+
+```ruby
+begin
+  risky_operation!
+rescue => e
+  Alplus.capture_exception(e, context: { order_id: order.id })
+end
+
+Alplus.capture_message("low disk space", level: "warning")
+```
+
+Both methods return an `err_` event id and never raise.
+
+## Heartbeat
+
+```ruby
+Alplus.heartbeat(token)
+Alplus.heartbeat(token, state: "fail")
+```
+
+## Plain Rack
+
+```ruby
+use Alplus::RackMiddleware
+```
+
+## Config
+
+The key is read from `ALPLUS_KEY` by default. It is never logged.
+
+```ruby
+Alplus.configure do |config|
+  config.environment = "production"
+  config.release = ENV["GIT_SHA"]
+  config.before_send = ->(item) { item }
+end
+```
+
+`before_send` receives the built item. Return `nil` to drop it. A raise
+sends the original item.
+
+## Tests
+
+```ruby
+Alplus.configure { |c| c.test_mode = true }
+
+Alplus.capture_exception(error)
+Alplus.flush
+item = Alplus::Testing.events.first
+```
+
+Nothing hits the network. Set `config.enabled = false` to disable capture.
+
+## Development
+
+```
+cd sdks/ruby
+bundle install
+export ALPLUS_CONTRACT_DIR=../../sdks/contract
+bundle exec rspec
+```

data/lib/alplus/active_job.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Alplus
+  # Optional ActiveJob integration. Namespaced under `Alplus::ActiveJob`
+  # (not top-level) so it never collides with `::ActiveJob`. Safe to load
+  # unconditionally -- `alplus.rb` only `require_relative`s this file when
+  # `defined?(::ActiveJob::Base)` is already true, and `install!` re-checks
+  # that guard, so a host app that never loads ActiveJob never activates
+  # any of this. This gem's runtime dependency list stays empty either
+  # way: `active_support/concern` is part of ActiveJob's own dependency
+  # tree, never `require`d unless ActiveJob already pulled it in.
+  module ActiveJob
+    # Mixed into `::ActiveJob::Base` by `install!`. Wraps every job's
+    # `perform` in an `around_perform` hook: captures the exception with
+    # job context (class, queue, scrubbed arguments), then RE-RAISES so
+    # ActiveJob's own retry/discard handling (`retry_on`/`discard_on`)
+    # still runs unchanged -- this is an observer, not an error handler
+    # that swallows failures.
+    module ErrorReporting
+      extend ActiveSupport::Concern
+
+      included do
+        around_perform :alplus_capture_around_perform
+      end
+
+      private
+
+      def alplus_capture_around_perform
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        alplus_capture_job_exception(e)
+        raise
+      end
+
+      def alplus_capture_job_exception(exception)
+        Alplus.capture_exception(
+          exception,
+          mechanism: "active_job",
+          contexts: { job: alplus_job_context }
+        )
+      rescue StandardError
+        nil
+      end
+
+      def alplus_job_context
+        scrub_fields = Alplus.configuration.scrub_fields.map { |f| f.to_s.downcase }
+        {
+          class: self.class.name,
+          queue: (respond_to?(:queue_name) ? queue_name : nil),
+          job_id: (respond_to?(:job_id) ? job_id : nil),
+          arguments: Alplus::Scrubber.deep_scrub(arguments, scrub_fields)
+        }.compact
+      end
+    end
+
+    class << self
+      # Idempotent: mixing `ErrorReporting` into `::ActiveJob::Base` more
+      # than once is a no-op (Ruby's own `Module#include` is already
+      # idempotent for the same module, but `@installed` also skips the
+      # guard checks/log-free re-run cheaply).
+      def install!
+        return if @installed
+        return unless defined?(::ActiveJob::Base)
+
+        ::ActiveJob::Base.include(ErrorReporting)
+        @installed = true
+      end
+
+      # Test-only: lets a spec re-drive `install!`. Not called by
+      # production code.
+      def reset!
+        @installed = false
+      end
+    end
+  end
+end

data/lib/alplus/client.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Orchestrates one configuration's capture pipeline: builds the wire item,
+  # wraps it in an envelope, and hands it to the background worker (or, in
+  # test mode, sends it synchronously through the in-memory transport).
+  #
+  # Every public method is fail-safe: a bug anywhere in envelope building or
+  # dispatch is caught and logged, never raised into the host app (issue
+  # #14 story 8). The event id is always generated and returned first, so a
+  # caller can show "reference id err_..." even if the event was dropped.
+  class Client
+    # `sleeper:` is forwarded to the default `Transport` (never used when
+    # `config.transport`/`config.test_mode` supply a different one) purely
+    # as a test seam: with the real `Kernel#sleep`, a spec exercising a
+    # retried send would otherwise wait on real backoff wall-clock time.
+    # Defaults to `config.sleeper` so `Alplus.configure { |c| c.sleeper = ... }`
+    # reaches the module-level singleton client too, not just a directly
+    # constructed `Client.new`.
+    def initialize(config, sleeper: config.sleeper)
+      @config = config
+      @transport = config.transport || (config.test_mode ? TestTransport.new : Transport.new(config, sleeper: sleeper))
+      @worker = Worker.new(config, @transport, kind: :error)
+      # A SEPARATE worker (own queue, own thread) from `@worker` (issue
+      # #12 fix): see `Worker`'s class doc for why sharing one lane with
+      # error delivery was a defect (head-of-line blocking + silent drops
+      # under an error storm, exactly when crash-free data matters).
+      @session_worker = Worker.new(config, @transport, kind: :session)
+
+      @pending_window =
+        PendingWindow.new(config.resolved_post_error_log_window_ms) { |item| deliver_item(item) }
+    end
+
+    attr_reader :transport
+
+    # The enabled/sampled gate runs BEFORE dedup registration (issue #15
+    # defect): a sampled-out or disabled capture must not occupy the
+    # dedup slot, or it would suppress the NEXT (real) in-window capture
+    # of the same error.
+    #
+    # Dedup (issue #15) then runs BEFORE the scope merge / envelope build:
+    # the same exception object captured twice within the dedup window
+    # (e.g. by `RackMiddleware` auto-capture and a manual rescue further up
+    # the stack) returns the first call's id and is never re-queued — see
+    # `Dedup`.
+    #
+    # `contexts:`/`fingerprint:` and the ambient `Scope` (`set_user`,
+    # `set_tag`, `set_context`, `add_breadcrumb`) are issue #17: an explicit
+    # per-call `user:`/`tags:`/`contexts:`/`breadcrumbs:` here wins over
+    # whatever the ambient scope carries, field-by-field — see
+    # `ScopeMerge.merge`. `user:` defaults to the `Alplus::UNSET` sentinel,
+    # not `nil`, so a caller CAN pass `user: nil` to explicitly clear the
+    # ambient user for one capture.
+    def capture_exception(exception, level: "error", context: nil, contexts: nil, tags: nil, breadcrumbs: nil, user: Alplus::UNSET, mechanism: "generic", fingerprint: nil)
+      mark_session_outcome(level)
+      fresh_id = Id.generate_event_id
+      return fresh_id unless enabled?
+      return fresh_id if excluded?(exception)
+
+      resolved = Dedup.resolve(exception, fresh_id)
+      return resolved[:id] if resolved[:duplicate]
+
+      id = resolved[:id]
+      dispatch(id) { build_item(:exception_item, exception: exception, id: id, level: level, context: context, contexts: contexts, tags: tags, breadcrumbs: breadcrumbs, user: user, mechanism: mechanism, fingerprint: fingerprint) }
+      id
+    end
+
+    def capture_message(message, level: "info", context: nil, contexts: nil, tags: nil, breadcrumbs: nil, user: Alplus::UNSET, mechanism: "generic", fingerprint: nil)
+      mark_session_outcome(level)
+      id = Id.generate_event_id
+      return id unless enabled?
+
+      dispatch(id) { build_item(:message_item, message: message, id: id, level: level, context: context, contexts: contexts, tags: tags, breadcrumbs: breadcrumbs, user: user, mechanism: mechanism, fingerprint: fingerprint) }
+      id
+    end
+
+    # Flushes BOTH delivery lanes (issue #12: error and session are
+    # independent workers). A slow/stuck error lane still bounds this call
+    # by `timeout` for the session lane's own drain -- each `Worker#flush`
+    # call gets the full `timeout` budget rather than splitting it, since a
+    # caller flushing wants both drained, not a race between them.
+    def flush(timeout: 2)
+      # Seal the post-error log window first: flush means "send now with
+      # whatever after-lines were collected so far", never "wait".
+      @pending_window.seal_all!
+      error_flushed = @worker.flush(timeout: timeout)
+      session_flushed = @session_worker.flush(timeout: timeout)
+      error_flushed && session_flushed
+    rescue StandardError
+      false
+    end
+
+    # Offers a log-line breadcrumb to every exception item currently inside
+    # its post-error log window on this thread (issue #47). Never raises.
+    def notify_log_breadcrumb(crumb)
+      @pending_window.notify_log_breadcrumb(crumb)
+    end
+
+    # Reports a closed `Session` (issue #12) to `POST /e/sessions`, on its
+    # OWN background `Worker` (own queue, own thread) so a slow/failing
+    # `/e/errors` delivery can never delay or drop a queued session, or
+    # vice versa -- see `Worker`'s class doc. Unlike `capture_exception`/
+    # `capture_message`, never sampled or deduped — an accurate crash-free
+    # percentage needs every session counted, not a sample of them. Only
+    # gated on `config.valid?` (configured + enabled). Fail-safe: never
+    # raises.
+    def report_session(session)
+      return false unless @config.valid?
+
+      envelope = Envelope.wrap(config: @config, item: Envelope.session_item(session: session, config: @config))
+
+      if @config.test_mode
+        @transport.send_envelope(envelope, kind: :session)
+      else
+        @session_worker.enqueue(envelope)
+      end
+    rescue StandardError => e
+      @config.logger&.warn("[alplus] session report failed internally; dropped: #{e.class}: #{e.message}")
+      false
+    end
+
+    private
+
+    # Any `"error"`/`"fatal"`-level capture during the current request
+    # marks its `Session` (at least) `:errored` (issue #12) — a no-op if
+    # the session is already `:crashed`, or if no session is active (e.g.
+    # a background job, not a request under `RackMiddleware`). Runs
+    # BEFORE the `enabled?`/sampling gate below: whether or not this
+    # particular capture gets sent to `/e/errors`, the request genuinely
+    # did produce a handled error.
+    def mark_session_outcome(level)
+      Session.current&.mark_errored if %w[error fatal].include?(level.to_s)
+    end
+
+    # Single evaluation point for "would this capture actually be sent":
+    # `config.sampled?` draws a random number, so it must be called
+    # exactly once per capture — calling it again later (e.g. inside
+    # `dispatch`) could draw a different result than what already gated
+    # dedup registration.
+    def enabled?
+      @config.valid? && @config.sampled?
+    rescue StandardError
+      false
+    end
+
+    # Merges the ambient `Scope` with this call's explicit overrides, then
+    # delegates to `Envelope.exception_item`/`Envelope.message_item`.
+    def build_item(builder, id:, level:, context:, contexts:, tags:, breadcrumbs:, user:, mechanism:, fingerprint:, **item_args)
+      merged = ScopeMerge.merge(ambient: Scope.current.snapshot, user: user, tags: tags, contexts: contexts, breadcrumbs: breadcrumbs)
+      Envelope.public_send(
+        builder,
+        id: id,
+        config: @config,
+        level: level,
+        context: context,
+        contexts: merged[:contexts].empty? ? nil : merged[:contexts],
+        tags: merged[:tags].empty? ? nil : merged[:tags],
+        breadcrumbs: merged[:breadcrumbs].empty? ? nil : merged[:breadcrumbs],
+        user: merged[:user],
+        mechanism: mechanism,
+        fingerprint: fingerprint,
+        **item_args
+      )
+    end
+
+    # `id` is unused directly but kept as a named parameter for readability
+    # at call sites and future correlation logging. The enabled/sampled
+    # gate already ran in `capture_exception`/`capture_message` before
+    # dedup registration, so it is not repeated here.
+    def dispatch(_id)
+      item = yield
+      item = Scrubber.scrub(item, @config.scrub_fields)
+      item = apply_before_send(item)
+      return unless item
+
+      if item[:type] == "exception" && @pending_window.enabled?
+        # Post-error log window (issue #47): the item lingers so log lines
+        # written just after the error join it before delivery.
+        @pending_window.hold(item)
+      else
+        deliver_item(item)
+      end
+    rescue StandardError => e
+      @config.logger&.warn("[alplus] capture failed internally; event dropped: #{e.class}: #{e.message}")
+    end
+
+    def deliver_item(item)
+      envelope = Envelope.wrap(config: @config, item: item)
+
+      if @config.test_mode
+        @transport.send_envelope(envelope)
+      else
+        @worker.enqueue(envelope)
+      end
+    rescue StandardError => e
+      @config.logger&.warn("[alplus] delivery failed internally; event dropped: #{e.class}: #{e.message}")
+    end
+
+    # Exception class name, or the name of any ancestor, matches
+    # `config.excluded_exceptions`. Never raises: an internal error (e.g. a
+    # weird `class.name` override) is treated as "not excluded" so a
+    # scrubbing bug in this check can never silently swallow a real error.
+    def excluded?(exception)
+      names = @config.excluded_exceptions
+      return false if names.nil? || names.empty?
+
+      exception.class.ancestors.any? { |ancestor| names.include?(ancestor.name) }
+    rescue StandardError
+      false
+    end
+
+    # `config.before_send` runs AFTER the built-in scrubber (`Scrubber`),
+    # so a custom callback still sees redacted secrets, not raw ones. A
+    # raising callback must never break capture: on error, the ORIGINAL
+    # (already-scrubbed) item is sent instead of the callback's output.
+    def apply_before_send(item)
+      callback = @config.before_send
+      return item unless callback
+
+      begin
+        callback.call(item)
+      rescue StandardError => e
+        @config.logger&.warn("[alplus] before_send raised; sending original event: #{e.class}: #{e.message}")
+        item
+      end
+    end
+  end
+end

data/lib/alplus/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Holds ingest key, endpoint, environment/release tags, and safety knobs.
+  # The key is read from `ALPLUS_KEY` by default and is never logged —
+  # `#inspect`/`#to_s` omit it deliberately (issue #14 story 11).
+  class Configuration
+    DEFAULT_ENDPOINT = "https://ingest.alplus.dev"
+
+    attr_accessor :key, :endpoint, :environment, :release, :sample_rate,
+                  :enabled, :test_mode, :app_dirs, :max_queue_size,
+                  :open_timeout, :read_timeout, :logger, :transport, :sleeper,
+                  :before_send, :scrub_fields, :excluded_exceptions, :context_lines,
+                  :breadcrumbs_enabled, :logger_breadcrumbs_enabled,
+                  :post_error_log_window_ms
+
+    # The window `Client` actually uses: the explicit setting when given,
+    # otherwise 0 in test mode (synchronous delivery stays synchronous for
+    # every spec that does not opt in) and 2000 ms in a real process.
+    def resolved_post_error_log_window_ms
+      return post_error_log_window_ms.to_i unless post_error_log_window_ms.nil?
+
+      test_mode ? 0 : 2_000
+    end
+
+    def initialize
+      @key = ENV["ALPLUS_KEY"]
+      @endpoint = ENV["ALPLUS_ENDPOINT"] || DEFAULT_ENDPOINT
+      @environment = ENV["ALPLUS_ENVIRONMENT"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "production"
+      @release = ENV["ALPLUS_RELEASE"]
+      @sample_rate = 1.0
+      @enabled = true
+      @test_mode = false
+      @app_dirs = []
+      @max_queue_size = 100
+      @open_timeout = 2
+      @read_timeout = 5
+      @logger = nil
+      @transport = nil
+      # Issue (SDK parity #1): called with the wire item hash just before
+      # enqueue. Return a (possibly modified) hash to send it, or `nil` to
+      # drop the event entirely. A raising callback never breaks capture --
+      # `Client` rescues it and sends the original item. `nil` by default
+      # (no-op).
+      @before_send = nil
+      # Deep-walked (case-insensitive substring match) across
+      # `context`/`contexts`/`tags`/`user` before `before_send` runs; a
+      # matching value is replaced with `"[FILTERED]"`. See `Scrubber`.
+      @scrub_fields = Scrubber::DEFAULT_SCRUB_FIELDS.dup
+      # Exception class names (or an ancestor's) to never send at all --
+      # e.g. `"ActionController::RoutingError"`. Empty by default: a
+      # non-Rails host app gets no surprise silent drops.
+      @excluded_exceptions = []
+      # Lines of source before/after each in_app frame's line to attach
+      # (`Stack`). `0` disables source-context capture entirely.
+      @context_lines = 3
+      # Auto-breadcrumbs from `ActiveSupport::Notifications` (Rails only,
+      # see `Railtie`). Ignored outside Rails.
+      @breadcrumbs_enabled = true
+      # Log-line breadcrumbs from an attached logger (issue #47,
+      # `LoggerBreadcrumbs`; the Railtie attaches `Rails.logger`).
+      @logger_breadcrumbs_enabled = true
+      # Post-error log window in ms (issue #47): an exception item lingers
+      # this long so log lines written just after the error (Rails' own
+      # exception logging included) join its breadcrumb timeline, marked
+      # `after_error`. `0` disables. `nil` (the default) resolves to 0 in
+      # test mode -- specs that exercise the window opt in explicitly --
+      # and 2000 otherwise. `flush`/`close` seal pending items immediately.
+      @post_error_log_window_ms = nil
+      # Injection point for the default `Transport`'s retry backoff sleep
+      # (issue #15/#16 follow-up): overridable per-`Configuration` so a
+      # spec exercising `Alplus.capture_exception`/`.heartbeat` against a
+      # retried response never waits on real wall-clock backoff.
+      @sleeper = method(:sleep)
+    end
+
+    def valid?
+      !enabled.nil? && enabled && !key.to_s.strip.empty?
+    end
+
+    def sampled?
+      sample_rate >= 1.0 || rand < sample_rate
+    end
+
+    # Never expose the key. A future maintainer adding a field here must not
+    # add it to this list without checking it isn't a secret.
+    def inspect
+      "#<Alplus::Configuration endpoint=#{endpoint.inspect} environment=#{environment.inspect} " \
+        "release=#{release.inspect} enabled=#{enabled.inspect} test_mode=#{test_mode.inspect}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/alplus/dedup.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Exception dedup (issue #15), mirroring
+  # `packages/sdk/src/core/observe/dedup.ts`'s `resolveDedupId`: the same
+  # error captured twice within a short window (auto-capture AND a manual
+  # `capture_exception` for the same raised exception, e.g. the Rack
+  # middleware re-raising into a Rails handler that also reports it)
+  # produces ONE event, not two.
+  #
+  # The JS SDK keys identity-bearing errors in a `WeakMap` so a dedup entry
+  # never outlives (or pins alive) the error object. Ruby's
+  # `ObjectSpace::WeakMap` holds its VALUES weakly too (not just keys) with
+  # no other strong referent to a plain dedup-entry object, so a value
+  # stashed there is eligible for GC before the next lookup -- unusable for
+  # this. Instead, the dedup entry is stashed directly on the error object
+  # itself via a hidden instance variable: it lives and dies with the
+  # exact same object, which is a stronger and simpler guarantee than a
+  # WeakMap gives (zero separate table to leak or prune for this path).
+  #
+  # A raised String/Symbol/Number/boolean/nil can't hold an instance
+  # variable (and has no reference identity worth keying on regardless --
+  # two unrelated `"boom"` literals are different objects but the same
+  # *error*), so those use a small bounded value-keyed Hash instead, same
+  # split as the JS SDK's `isWeakKeyable`.
+  module Dedup
+    WINDOW_SECONDS = 2.0
+    # Bounds the primitive-keyed fallback so a flood of distinct thrown
+    # strings can't grow it unboundedly.
+    VALUE_CACHE_MAX = 50
+    VALUE_KEYABLE_CLASSES = [String, Symbol, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+    IVAR = :@__alplus_dedup_entry__
+    private_constant :IVAR
+
+    Entry = Struct.new(:id, :expires_at)
+
+    @value_map = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Returns `{id:, duplicate:}` — the fresh id for a new error, or the
+      # PREVIOUS capture's id (and `duplicate: true`) if `error` was
+      # already captured within the window. Never raises: on any internal
+      # failure (e.g. a frozen error object rejecting the ivar write),
+      # treats it as a fresh, non-duplicate capture rather than risk
+      # silently dropping a real error.
+      def resolve(error, fresh_id)
+        now = monotonic_now
+        @mutex.synchronize do
+          if value_keyable?(error)
+            resolve_value_keyed(error, fresh_id, now)
+          else
+            resolve_identity_keyed(error, fresh_id, now)
+          end
+        end
+      rescue StandardError
+        { id: fresh_id, duplicate: false }
+      end
+
+      # Test-only: clears the value-keyed table between examples. The
+      # identity path needs no reset — a fresh `Exception.new` each example
+      # carries no leftover ivar.
+      def reset!
+        @mutex.synchronize { @value_map.clear }
+      end
+
+      private
+
+      def resolve_identity_keyed(error, fresh_id, now)
+        existing = error.instance_variable_defined?(IVAR) ? error.instance_variable_get(IVAR) : nil
+        if existing && existing.expires_at > now
+          { id: existing.id, duplicate: true }
+        else
+          error.instance_variable_set(IVAR, Entry.new(fresh_id, now + WINDOW_SECONDS))
+          { id: fresh_id, duplicate: false }
+        end
+      end
+
+      def resolve_value_keyed(error, fresh_id, now)
+        prune_expired(now)
+        key = value_key(error)
+        existing = @value_map[key]
+        if existing && existing.expires_at > now
+          { id: existing.id, duplicate: true }
+        else
+          @value_map.delete(@value_map.keys.first) if @value_map.size >= VALUE_CACHE_MAX
+          @value_map[key] = Entry.new(fresh_id, now + WINDOW_SECONDS)
+          { id: fresh_id, duplicate: false }
+        end
+      end
+
+      def prune_expired(now)
+        @value_map.delete_if { |_key, entry| entry.expires_at <= now }
+      end
+
+      def value_keyable?(error)
+        VALUE_KEYABLE_CLASSES.any? { |klass| error.is_a?(klass) }
+      end
+
+      def value_key(error)
+        "#{error.class}:#{error.inspect}"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end