alplus-ruby 0.1.0

data/lib/alplus/envelope.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Alplus
+  # Builds the `POST /e/errors` wire envelope. Mirrors
+  # `packages/sdk/src/core/observe/{client,envelope}.ts` (the TypeScript
+  # SDK) and the Elixir SDK (#13): `{header: {key, sdk, sent_at}, items: [...]}`
+  # with one item per request. Kept additive-only per docs/BUILD.md §5 —
+  # every field here already exists in the accepted server shape.
+  #
+  # Per-field caps mirror the JS SDK's own write-boundary caps
+  # (`envelope.ts`'s `MAX_*` constants) so an oversized field is trimmed
+  # HERE, per field, and the event still sends — the same trade-off the JS
+  # SDK makes. `Transport::MAX_ENVELOPE_BYTES`'s whole-envelope check stays
+  # a last-resort safety net for the case these per-field caps still don't
+  # fit (should be unreachable in practice, same as the JS SDK's own
+  # comment on its equivalent guard).
+  module Envelope
+    MAX_ENVELOPE_BYTES = 1_048_576
+    MAX_MESSAGE_CHARS = 4_096
+    MAX_EXCEPTION_VALUE_CHARS = 4_096
+    MAX_STACK_TRACE_CHARS = 16_384
+    MAX_CONTEXT_CHARS = 8_192
+    MAX_TAGS_CHARS = 4_096
+    SERVER_MAX_BREADCRUMBS = 100
+    MAX_BREADCRUMB_MESSAGE_CHARS = 2_048
+    MAX_BREADCRUMB_CATEGORY_CHARS = 128
+    # The server's `errorItemSchema.user` is `.strict()` with only `id`/
+    # `email` (packages/schemas/src/observe/error-envelope.ts) — an
+    # unrecognized key rejects the whole item, so `cap_user` below picks
+    # only these two rather than forwarding an arbitrary hash. The JS SDK
+    # passes `user` through uncapped (no `MAX_USER_*` there); this cap is
+    # an SDK-side addition for the same defensive-write-boundary discipline
+    # every other free-text field already gets here.
+    MAX_USER_FIELD_CHARS = 256
+    # Mirrors the server's `errorItemSchema.fingerprint`
+    # (`z.array(z.string().max(256)).min(1).max(16)`, issue #17).
+    MAX_FINGERPRINT_ENTRIES = 16
+    MAX_FINGERPRINT_CHARS = 256
+    # The server accepts an exception `cause` chain up to depth 5 counting
+    # the top-level exception (`Alplus.Observe.ErrorEnvelope`); walk at most
+    # 4 causes so a cyclic or absurd chain can never build an over-deep item.
+    MAX_CAUSE_DEPTH = 4
+
+    module_function
+
+    def wrap(config:, item:)
+      {
+        header: {
+          key: config.key,
+          sdk: { name: Alplus::SDK_NAME, version: Alplus::VERSION, platform: "ruby" },
+          sent_at: Time.now.utc.iso8601
+        },
+        items: [item]
+      }
+    end
+
+    # Builds a `POST /e/sessions` wire item (issue #12) from an
+    # `Alplus::Session`. Carries no PII: `session.id` is opaque and used
+    # server-side only for in-window ingest dedup, then discarded (never
+    # stored raw) — matching `Alplus.Observe.SessionEnvelope`, the server
+    # parser.
+    def session_item(session:, config:)
+      {
+        id: session.id,
+        status: session.status.to_s,
+        started_at: session.started_at.iso8601,
+        duration_ms: ((Time.now.utc - session.started_at) * 1000).round,
+        release: config.release,
+        environment: config.environment
+      }.compact
+    end
+
+    # `frames:` overrides the normal `Stack.frames_for(exception, ...)`
+    # capture with an already-built wire frame array, for callers that
+    # already have wire-shaped frames (mirrors the Elixir SDK's
+    # `Envelope.build_frame(%{} = wire_frame, _)` passthrough). Real capture
+    # callers never pass this; it exists so the golden-envelope contract
+    # spec (issue #18) can call this REAL function with the golden's
+    # literal, cross-language-reproducible frames instead of a real
+    # backtrace tied to one language's stack-trace format.
+    def exception_item(id:, exception:, config:, level: "error", context: nil, contexts: nil, tags: nil, breadcrumbs: nil, user: nil, mechanism: "generic", fingerprint: nil, frames: nil)
+      frames ||= Stack.frames_for(exception, app_dirs: config.app_dirs, context_lines: config.context_lines.to_i)
+      exc = { type: exception.class.name, value: cap_text(exception.message.to_s, MAX_EXCEPTION_VALUE_CHARS) }
+      capped_frames = cap_frames(frames, MAX_STACK_TRACE_CHARS)
+      exc[:stacktrace] = { frames: capped_frames } unless capped_frames.empty?
+      cause = build_cause(exception.cause, config, MAX_CAUSE_DEPTH)
+      exc[:cause] = cause if cause
+
+      base_item(id: id, type: "exception", level: level, config: config, mechanism: mechanism, context: context, contexts: contexts, tags: tags, breadcrumbs: breadcrumbs, user: user, fingerprint: fingerprint)
+        .merge(exception: exc)
+    end
+
+    # Walks `Exception#cause` into the wire `cause` chain (Honeybadger/
+    # Sentry-style "caused by"). Each cause carries its own type, message,
+    # and backtrace. Depth-bounded; a `cause` loop (possible via handwritten
+    # `cause` overrides) terminates at the bound instead of hanging.
+    def build_cause(exception, config, depth)
+      return nil if exception.nil? || depth <= 0
+
+      built = { type: exception.class.name, value: cap_text(exception.message.to_s, MAX_EXCEPTION_VALUE_CHARS) }
+      frames = Stack.frames_for(exception, app_dirs: config.app_dirs, context_lines: config.context_lines.to_i)
+      capped_frames = cap_frames(frames, MAX_STACK_TRACE_CHARS)
+      built[:stacktrace] = { frames: capped_frames } unless capped_frames.empty?
+      nested = build_cause(exception.cause, config, depth - 1)
+      built[:cause] = nested if nested
+      built
+    end
+
+    def message_item(id:, message:, config:, level: "info", context: nil, contexts: nil, tags: nil, breadcrumbs: nil, user: nil, mechanism: "generic", fingerprint: nil)
+      base_item(id: id, type: "message", level: level, config: config, mechanism: mechanism, context: context, contexts: contexts, tags: tags, breadcrumbs: breadcrumbs, user: user, fingerprint: fingerprint)
+        .merge(message: cap_text(message.to_s, MAX_MESSAGE_CHARS))
+    end
+
+    # `context:` is the free-text convenience that folds into
+    # `contexts.extra` (and, per capture, always REPLACES whatever ambient
+    # `extra` context the caller's scope carried — it does not deep-merge
+    # with it); `contexts:` is the arbitrary named-map form. Both fold into
+    # one `contexts` wire key, matching the JS SDK and fixing this SDK's
+    # previous `context`-only shape (issue #17).
+    def base_item(id:, type:, level:, config:, mechanism:, context:, contexts:, tags:, breadcrumbs:, user:, fingerprint:)
+      item = {
+        id: id,
+        type: type,
+        timestamp: Time.now.utc.iso8601,
+        level: level.to_s,
+        release: config.release,
+        environment: config.environment,
+        mechanism: mechanism
+      }
+      named_contexts = contexts ? contexts.dup : {}
+      named_contexts[:extra] = context if context && !context.empty?
+      item[:contexts] = cap_context(named_contexts, MAX_CONTEXT_CHARS) unless named_contexts.empty?
+      capped_tags = cap_tags(tags, MAX_TAGS_CHARS)
+      item[:tags] = capped_tags if capped_tags
+      capped_crumbs = cap_breadcrumbs(breadcrumbs, SERVER_MAX_BREADCRUMBS)
+      item[:breadcrumbs] = capped_crumbs if capped_crumbs && !capped_crumbs.empty?
+      capped_user = cap_user(user)
+      item[:user] = capped_user if capped_user
+      capped_fingerprint = cap_fingerprint(fingerprint)
+      item[:fingerprint] = capped_fingerprint if capped_fingerprint
+      item.compact
+    end
+
+    # Truncates a string to at most `max_length` characters. Passes
+    # non-strings through `#to_s` first; callers already do this, kept
+    # defensive here since a truncated field is safer than a raise.
+    def cap_text(value, max_length)
+      value = value.to_s
+      return value if value.length <= max_length
+
+      value[0, max_length]
+    end
+
+    # Caps a JSON-ish hash by its serialized size. A value whose
+    # serialization exceeds `max_chars` is REPLACED by a small truncation
+    # marker rather than cut mid-string, mirroring the JS SDK's
+    # `capContext` — a partial JSON string is unparseable, which is worse
+    # than a shorter one.
+    def cap_context(value, max_chars)
+      serialized = JSON.generate(value)
+      return value if serialized.bytesize <= max_chars
+
+      { _truncated: true, _original_chars: serialized.bytesize }
+    end
+
+    # Drops the tags object entirely (with a debug-log warning) rather than
+    # send a truncated `Hash` that would no longer round-trip as one — same
+    # trade-off the JS SDK's `capTags` makes. Returns `nil` for a `nil`/
+    # empty input so the caller can omit the key.
+    def cap_tags(tags, max_chars)
+      return nil if tags.nil? || tags.empty?
+      return tags if JSON.generate(tags).bytesize <= max_chars
+
+      nil
+    end
+
+    # Drops trailing frames until the serialized array fits `max_chars`,
+    # mirroring the JS SDK's `capFrames`/the server's `capFramesToBudget`.
+    #
+    # Binary-searches the cut point (O(log n) `JSON.generate` calls)
+    # instead of popping one frame and re-serializing the whole array per
+    # pop (O(n) calls, each itself O(n)) — a deep recursive backtrace can
+    # carry thousands of frames, where the naive approach is noticeably
+    # slow.
+    def cap_frames(frames, max_chars)
+      return frames if frames.empty? || JSON.generate(frames).bytesize <= max_chars
+
+      low = 0
+      high = frames.length - 1
+      while low < high
+        mid = (low + high + 1) / 2
+        if JSON.generate(frames.first(mid)).bytesize <= max_chars
+          low = mid
+        else
+          high = mid - 1
+        end
+      end
+      frames.first(low)
+    end
+
+    # Builds the wire `user` object: only `id`/`email` (accepts either
+    # symbol or string keys from the caller), each length-capped, matching
+    # the server's `.strict()` `errorItemSchema.user` — any other key would
+    # get the whole item rejected, so unrecognized keys are dropped rather
+    # than forwarded. Returns `nil` for a `nil`/empty input, or if neither
+    # recognized key is present, so the caller can omit the wire key.
+    def cap_user(user)
+      return nil if user.nil? || user.empty?
+
+      id = user[:id] || user["id"]
+      email = user[:email] || user["email"]
+      built = {}
+      built[:id] = cap_text(id, MAX_USER_FIELD_CHARS) if id
+      built[:email] = cap_text(email, MAX_USER_FIELD_CHARS) if email
+      built.empty? ? nil : built
+    end
+
+    # Caps breadcrumb count to the server's own ceiling (keeping the most
+    # recent ones) and per-breadcrumb message/category length.
+    def cap_breadcrumbs(breadcrumbs, max_count)
+      return nil if breadcrumbs.nil?
+
+      breadcrumbs.last(max_count).map do |crumb|
+        crumb = crumb.dup
+        crumb[:message] = cap_text(crumb[:message], MAX_BREADCRUMB_MESSAGE_CHARS) if crumb[:message]
+        crumb[:category] = cap_text(crumb[:category], MAX_BREADCRUMB_CATEGORY_CHARS) if crumb[:category]
+        crumb
+      end
+    end
+
+    # Caps the custom fingerprint override to the server's own bounds:
+    # at most `MAX_FINGERPRINT_ENTRIES` entries, each at most
+    # `MAX_FINGERPRINT_CHARS` characters. Returns `nil` for a `nil`/empty
+    # input so the caller can omit the wire key.
+    def cap_fingerprint(fingerprint)
+      return nil if fingerprint.nil? || fingerprint.empty?
+
+      fingerprint.first(MAX_FINGERPRINT_ENTRIES).map { |part| cap_text(part.to_s, MAX_FINGERPRINT_CHARS) }
+    end
+  end
+end

data/lib/alplus/heartbeat.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "securerandom"
+
+module Alplus
+  # Cron/job liveness pings against Monitor's `GET|POST /h/:token`
+  # (issue #16; docs/ARCHITECTURE.md §8): the token is the auth (recognized
+  # → 202 even paused, unrecognized → 404); `?state=start|finish|fail`, an
+  # unrecognized state falls back to `finish` (still records the run,
+  # matching the Elixir SDK) rather than silently no-op-ing. Mirrors
+  # `packages/sdk/src/core/heartbeat.ts`'s wire contract and reuses `Retry`
+  # (issue #15) for backoff/`Retry-After` instead of duplicating it — see
+  # `Retry`'s comment on why Ruby shares this where the JS SDK deliberately
+  # doesn't.
+  #
+  # `Alplus.heartbeat` (the public entry point in `alplus.rb`) calls `ping`
+  # synchronously on the caller's thread: a cron/job runner is not a web
+  # request, and the caller (typically the very last statement of a job)
+  # wants the ping actually sent before the process exits, not fired into
+  # a background thread that may never run. This DOES block the caller
+  # briefly — bounded to `HEARTBEAT_MAX_ATTEMPTS` attempts and a
+  # `HEARTBEAT_MAX_RETRY_AFTER_SECONDS` cap on any 429 `Retry-After`
+  # (ignoring a server-requested wait beyond that), so a slow ingest
+  # endpoint can add at most ~2s, never `Transport`'s full ~30s budget.
+  module Heartbeat
+    VALID_STATES = %w[start finish fail].freeze
+    HEARTBEAT_MAX_ATTEMPTS = 2
+    HEARTBEAT_MAX_RETRY_AFTER_SECONDS = 2
+
+    # Matches the JS SDK's `PING_ID_PATTERN` shape closely enough for a
+    # server-side idempotency key; not validated against a caller-supplied
+    # override here since nothing in this SDK accepts one from outside yet.
+    module_function
+
+    # Never raises: an internal error, network failure, or retryable
+    # non-ok response is retried (bounded, see module doc) and then
+    # swallowed, logged via `config.logger` if the retry budget is
+    # exhausted. Returns `nil` always.
+    #
+    # The SAME `ping_id` is reused on every retry attempt within one call
+    # (issue #16 defect): ingest dedups a retried ping on `ping_id`, so
+    # reusing it — instead of minting a fresh id per HTTP attempt — is what
+    # keeps a retried fail/finish from being processed as two separate
+    # events (a duplicate incident/notification).
+    def ping(token, state: "finish", config: Alplus.configuration, sleeper: method(:sleep), ping_id: nil)
+      resolved_state = VALID_STATES.include?(state.to_s) ? state.to_s : "finish"
+      resolved_ping_id = ping_id || generate_ping_id
+      uri = build_uri(token, resolved_state, resolved_ping_id, config)
+
+      result = Retry.perform(
+        sleeper: sleeper,
+        max_attempts: HEARTBEAT_MAX_ATTEMPTS,
+        max_retry_after_seconds: HEARTBEAT_MAX_RETRY_AFTER_SECONDS
+      ) { |_attempt| post(uri, config) }
+
+      if result.outcome == :exhausted
+        detail = result.error ? "#{result.error.class}: #{result.error.message}" : "status #{result.response&.code}"
+        config.logger&.warn("[alplus] heartbeat exhausted #{HEARTBEAT_MAX_ATTEMPTS} attempt(s) (token #{token.inspect}, state #{resolved_state.inspect}): #{detail}")
+      end
+      nil
+    rescue StandardError => e
+      config.logger&.warn("[alplus] heartbeat failed internally: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def generate_ping_id
+      SecureRandom.uuid
+    end
+
+    # Exposed for tests asserting the exact URL shape; not otherwise part
+    # of the public surface.
+    def build_uri(token, state, ping_id, config)
+      base = config.endpoint.to_s.sub(%r{/+\z}, "")
+      uri = URI.parse("#{base}/h/#{URI.encode_www_form_component(token)}")
+      uri.query = URI.encode_www_form(state: state, ping_id: ping_id)
+      uri
+    end
+
+    def post(uri, config)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = config.open_timeout
+      http.read_timeout = config.read_timeout
+
+      http.request(Net::HTTP::Post.new(uri.request_uri))
+    end
+  end
+end

data/lib/alplus/id.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Alplus
+  # Client-side event id generation for Observe. `POST /e/errors` treats
+  # `items[].id` as the idempotency key and requires it to be generated
+  # client-side, `err_`-prefixed, before the event leaves the process.
+  #
+  # This mirrors packages/sdk/src/core/id.ts (TypeScript SDK) byte-for-byte
+  # in shape: a time-ordered UUIDv7 (RFC 9562) — 48-bit millisecond Unix
+  # timestamp, version nibble (0111), 74 bits of randomness, variant bits (10).
+  module Id
+    module_function
+
+    def uuidv7
+      bytes = SecureRandom.random_bytes(16).bytes
+      ts = (Time.now.to_f * 1000).to_i
+
+      bytes[0] = (ts >> 40) & 0xff
+      bytes[1] = (ts >> 32) & 0xff
+      bytes[2] = (ts >> 24) & 0xff
+      bytes[3] = (ts >> 16) & 0xff
+      bytes[4] = (ts >> 8) & 0xff
+      bytes[5] = ts & 0xff
+      bytes[6] = 0x70 | (bytes[6] & 0x0f) # version 7
+      bytes[8] = 0x80 | (bytes[8] & 0x3f) # variant 10
+
+      hex = bytes.map { |b| format("%02x", b) }.join
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+
+    # Generates the `err_`-prefixed, client-generated UUIDv7 every Observe
+    # event carries — the same prefix/shape the JS and Elixir SDKs emit.
+    def generate_event_id
+      "err_#{uuidv7}"
+    end
+
+    # Generates a `ses_`-prefixed UUIDv7 session id for the
+    # `POST /e/sessions` wire protocol (issue #12). Opaque and used only
+    # for in-window ingest dedup — never persisted past that, never a PII
+    # carrier.
+    def generate_session_id
+      "ses_#{uuidv7}"
+    end
+  end
+end

data/lib/alplus/logger_breadcrumbs.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Records application log lines as breadcrumbs (issue #47): every
+  # `Logger#add` on an attached logger becomes a `log`-category breadcrumb
+  # on the current thread's `Scope` ring (before-error context) and is
+  # offered to any pending exception item inside its post-error log window
+  # (after-error context). Attached to `Rails.logger` by the Railtie;
+  # usable on any stdlib-compatible logger via `attach`.
+  #
+  # Excluded on purpose: the SDK's own `[alplus]` diagnostics (the timeline
+  # must hold the application's output, not the SDK talking to itself), and
+  # non-String messages (the block form is not evaluated here — evaluating
+  # it early would change the host's lazy-logging semantics).
+  module LoggerBreadcrumbs
+    SEVERITY_LEVEL = {
+      0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal"
+    }.freeze
+    SDK_INTERNAL_PREFIX = "[alplus]"
+
+    # Prepended onto the logger's singleton class so both a plain
+    # `::Logger` and Rails' `ActiveSupport::BroadcastLogger` (whose `add`
+    # fans out to its broadcasts) are covered by one seam.
+    module Recorder
+      def add(severity, message = nil, progname = nil, &block)
+        Alplus::LoggerBreadcrumbs.record(severity, message, progname)
+        super
+      end
+    end
+
+    module_function
+
+    def attach(logger)
+      return if logger.nil? || logger.singleton_class.ancestors.include?(Recorder)
+
+      logger.singleton_class.prepend(Recorder)
+    end
+
+    # Never raises, and never re-enters (a breadcrumb path that itself logs
+    # would otherwise recurse through the patched `add`).
+    def record(severity, message, progname)
+      config = Alplus.configuration
+      return unless config&.logger_breadcrumbs_enabled
+      return if Thread.current[:alplus_recording_log_breadcrumb]
+
+      text = message.is_a?(String) ? message : (progname if progname.is_a?(String) && message.nil?)
+      return if text.nil? || text.empty? || text.start_with?(SDK_INTERNAL_PREFIX)
+
+      Thread.current[:alplus_recording_log_breadcrumb] = true
+      level = SEVERITY_LEVEL.fetch(severity, "info")
+      Scope.current.add_breadcrumb(category: "log", message: text, level: level)
+      Alplus.initialized_client&.notify_log_breadcrumb(
+        category: "log",
+        message: Envelope.cap_text(text, Envelope::MAX_BREADCRUMB_MESSAGE_CHARS),
+        level: level,
+        ts: Time.now.utc.iso8601(3)
+      )
+    rescue StandardError
+      nil
+    ensure
+      Thread.current[:alplus_recording_log_breadcrumb] = nil
+    end
+  end
+end

data/lib/alplus/notifications_subscriber.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Auto-breadcrumbs from `ActiveSupport::Notifications` (Rails only):
+  # pushes a small, bounded set of framework events into the current
+  # request's `Scope` as breadcrumbs, so a captured exception's timeline
+  # shows "what happened just before this" without the host app calling
+  # `Alplus.add_breadcrumb` by hand (mirrors Sentry's/AppSignal's
+  # instrumentation breadcrumbs).
+  #
+  # Wired from `Railtie#install!` (guarded there too) -- a total no-op
+  # outside Rails/`ActiveSupport`, and never subscribed twice even if a
+  # host process boots more than one `Rails::Application` (test suites do
+  # this routinely).
+  #
+  # Deliberately a SMALL, fixed event list: more events means more noise
+  # per request and a bigger cut of the `Scope`'s bounded breadcrumb ring
+  # buffer (`Scope::MAX_BREADCRUMBS`) spent on framework chatter instead of
+  # the host app's own `add_breadcrumb` calls.
+  module NotificationsSubscriber
+    EVENTS = %w[sql.active_record process_action.action_controller start_processing.action_controller].freeze
+
+    class << self
+      # Idempotent: a second call (e.g. a second `Rails::Application` boot
+      # in the same process, common in test suites) is a no-op.
+      def install!
+        return if @installed
+        return unless defined?(::ActiveSupport::Notifications)
+
+        EVENTS.each do |event_name|
+          ::ActiveSupport::Notifications.subscribe(event_name) do |*args|
+            handle(event_name, ::ActiveSupport::Notifications::Event.new(*args))
+          end
+        end
+        @installed = true
+      end
+
+      # Test-only: lets a spec re-install (e.g. against a stubbed
+      # `Scope`/`Configuration`) without carrying state from a previous
+      # example. Not called by production code.
+      def reset!
+        @installed = false
+      end
+
+      # Fail-safe: instrumentation must never break the request it is
+      # observing. Any error here (a payload shape this Rails version
+      # doesn't produce, a `Scope` write racing shutdown, etc.) is
+      # swallowed.
+      def handle(event_name, notification)
+        return unless breadcrumbs_enabled?
+
+        breadcrumb = build_breadcrumb(event_name, notification)
+        return unless breadcrumb
+
+        Scope.current.add_breadcrumb(**breadcrumb)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def breadcrumbs_enabled?
+        Alplus.configuration.breadcrumbs_enabled
+      rescue StandardError
+        false
+      end
+
+      def build_breadcrumb(event_name, notification)
+        case event_name
+        when "sql.active_record"
+          sql_breadcrumb(notification)
+        when "process_action.action_controller"
+          process_action_breadcrumb(notification)
+        when "start_processing.action_controller"
+          start_processing_breadcrumb(notification)
+        end
+      end
+
+      # `payload[:binds]` (the actual bound parameter VALUES -- e.g. a
+      # looked-up email or password hash) is deliberately never read here.
+      # Only the query name and the (already-parameterized, `?`-holed)
+      # `payload[:sql]` text are kept.
+      def sql_breadcrumb(notification)
+        payload = notification.payload
+        return nil if payload[:name] == "SCHEMA"
+
+        { message: payload[:sql].to_s, category: "query", level: "info",
+          data: { name: payload[:name], duration_ms: notification.duration.round(1) }.compact }
+      end
+
+      def process_action_breadcrumb(notification)
+        payload = notification.payload
+        { message: "#{payload[:controller]}##{payload[:action]}", category: "http", level: "info",
+          data: { status: payload[:status], method: payload[:method] }.compact }
+      end
+
+      # No request params in the breadcrumb data: params routinely carry
+      # user-entered PII, and this event fires before the built-in
+      # scrubber (`Scrubber`, which only walks `context`/`contexts`/
+      # `tags`/`user` at capture time) ever sees it.
+      def start_processing_breadcrumb(notification)
+        payload = notification.payload
+        { message: "#{payload[:method]} #{payload[:path]}", category: "http", level: "info" }
+      end
+    end
+  end
+end

data/lib/alplus/pending_window.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Alplus
+  # The post-error log window (issue #47): a built exception item is held
+  # here for a short, bounded window before delivery, and log-line
+  # breadcrumbs recorded on the SAME thread during the window are appended
+  # to it, marked `data: { after_error: true }`.
+  #
+  # Same-thread attribution is the correctness rule: under a concurrent
+  # server, another request's log lines must never pollute this error's
+  # timeline. Rails logs the unhandled exception (DebugExceptions) on the
+  # request thread AFTER `RackMiddleware` re-raises, which is exactly the
+  # window this class keeps open — a request-end seal would run too early
+  # to see that line.
+  #
+  # One lazily-spawned sealer thread sleeps until the earliest deadline and
+  # seals due entries; it exits when the list drains and respawns on the
+  # next hold. `seal_all!` (called by `Client#flush`/`#close`) seals
+  # everything immediately — the window delays delivery, never loses events.
+  class PendingWindow
+    MAX_AFTER_ERROR_BREADCRUMBS = 20
+    # The server ceiling (`Envelope::SERVER_MAX_BREADCRUMBS`).
+    MAX_TOTAL_BREADCRUMBS = Envelope::SERVER_MAX_BREADCRUMBS
+
+    Entry = Struct.new(:item, :thread, :deadline, :appended, keyword_init: true)
+
+    def initialize(window_ms, &deliver)
+      @window_ms = window_ms
+      @deliver = deliver
+      @entries = []
+      @mutex = Mutex.new
+      @sealer = nil
+    end
+
+    def enabled?
+      @window_ms.positive?
+    end
+
+    def hold(item)
+      entry = Entry.new(item: item, thread: Thread.current, deadline: monotonic_now + (@window_ms / 1000.0), appended: 0)
+      @mutex.synchronize { @entries << entry }
+      ensure_sealer_running
+    end
+
+    # Appends a log-line breadcrumb to every pending entry captured on the
+    # calling thread, within the per-entry and total bounds. Never raises.
+    def notify_log_breadcrumb(crumb)
+      @mutex.synchronize do
+        @entries.each do |entry|
+          next unless entry.thread == Thread.current
+          next if entry.appended >= MAX_AFTER_ERROR_BREADCRUMBS
+
+          crumbs = (entry.item[:breadcrumbs] ||= [])
+          next if crumbs.length >= MAX_TOTAL_BREADCRUMBS
+
+          crumbs << crumb.merge(data: (crumb[:data] || {}).merge(after_error: true))
+          entry.appended += 1
+        end
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def seal_all!
+      entries = @mutex.synchronize { @entries.slice!(0..) }
+      entries.each { |entry| @deliver.call(entry.item) }
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def ensure_sealer_running
+      @mutex.synchronize do
+        next if @sealer&.alive?
+
+        @sealer = Thread.new { sealer_loop }
+        @sealer.name = "alplus-pending-sealer" if @sealer.respond_to?(:name=)
+      end
+    end
+
+    def sealer_loop
+      loop do
+        due, sleep_for = @mutex.synchronize do
+          now = monotonic_now
+          due_entries = @entries.select { |entry| entry.deadline <= now }
+          @entries -= due_entries
+          next_deadline = @entries.map(&:deadline).min
+          [due_entries, next_deadline && (next_deadline - now)]
+        end
+
+        due.each { |entry| @deliver.call(entry.item) }
+        break if sleep_for.nil?
+
+        sleep([sleep_for, 0.01].max)
+      end
+    rescue StandardError
+      # The sealer must never crash the host app; entries left behind are
+      # still delivered by the next `seal_all!` (flush/close).
+      nil
+    end
+  end
+end