pgbus 0.19.3 → 0.20.0

data/lib/pgbus/configuration/workflow_settings.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Configuration
+    # Workflows (issue #540): durable multi-step Pgbus::Workflow runs.
+    #
+    #   config.workflow_queue = "workflows"             # where StepJob messages go
+    #   config.workflow_retention = 30.days             # finished/cancelled runs kept this long; nil keeps them
+    #   config.workflow_sweep_interval = 5.minutes      # how often the dispatcher repairs stuck steps
+    #   config.workflow_stall_threshold = 1.hour        # an in_progress step older than this is stalled
+    #   config.workflow_stall_action = :pause           # :pause, :reattempt or :cancel a stalled step
+    #   config.workflow_max_payload_size = 131_072      # bytes: arguments and step outputs
+    #   config.workflow_error_backtrace_lines = 50      # backtrace lines kept on a failed step
+    #   config.workflow_waiting_visibility_threshold = 7.days # a step waiting this long without a
+    #                                                   # wait_timeout: counts as stuck (waiting_overdue)
+    #   config.workflow_subject_url = ->(type, id) { "/admin/#{type.underscore.pluralize}/#{id}" }
+    #                                                   # the dashboard's subject link (nil: plain text)
+    module WorkflowSettings
+      WORKFLOW_STALL_ACTIONS = %i[pause reattempt cancel].freeze
+
+      attr_reader :workflow_queue, :workflow_retention, :workflow_sweep_interval, :workflow_stall_threshold,
+                  :workflow_stall_action, :workflow_waiting_visibility_threshold
+      attr_accessor :workflow_max_payload_size, :workflow_error_backtrace_lines, :workflow_subject_url
+
+      def workflow_queue=(value)
+        name = value.to_s
+        raise Pgbus::ConfigurationError, "workflow_queue must be a non-empty queue name" if value.nil? || name.strip.empty?
+
+        @workflow_queue = name
+      end
+
+      def workflow_retention=(value)
+        @workflow_retention = coerce_duration!(value, :workflow_retention)
+      end
+
+      def workflow_sweep_interval=(value)
+        @workflow_sweep_interval = coerce_duration!(value, :workflow_sweep_interval)
+      end
+
+      def workflow_stall_threshold=(value)
+        @workflow_stall_threshold = coerce_duration!(value, :workflow_stall_threshold)
+      end
+
+      def workflow_waiting_visibility_threshold=(value)
+        @workflow_waiting_visibility_threshold = coerce_duration!(value, :workflow_waiting_visibility_threshold)
+      end
+
+      def workflow_stall_action=(value)
+        action = value.respond_to?(:to_sym) ? value.to_sym : value
+        unless WORKFLOW_STALL_ACTIONS.include?(action)
+          raise Pgbus::ConfigurationError,
+                "workflow_stall_action must be one of #{WORKFLOW_STALL_ACTIONS.map(&:inspect).join(", ")}, got #{value.inspect}"
+        end
+
+        @workflow_stall_action = action
+      end
+
+      private
+
+      def initialize_workflow_settings
+        @workflow_queue = "default"
+        @workflow_retention = 30 * 24 * 3600 # 30 days
+        @workflow_sweep_interval = 300 # 5 minutes
+        @workflow_stall_threshold = 3600 # 1 hour
+        @workflow_stall_action = :pause
+        @workflow_max_payload_size = 131_072 # 128 KB
+        @workflow_error_backtrace_lines = 50
+        @workflow_waiting_visibility_threshold = 7 * 24 * 3600 # 7 days
+        @workflow_subject_url = nil
+      end
+
+      def validate_workflow_settings!
+        { workflow_sweep_interval: workflow_sweep_interval, workflow_stall_threshold: workflow_stall_threshold,
+          workflow_waiting_visibility_threshold: workflow_waiting_visibility_threshold,
+          workflow_retention: workflow_retention }.each do |name, value|
+          next if value.nil? && name == :workflow_retention
+          next if value.is_a?(Numeric) && value.positive? && value.finite?
+
+          raise Pgbus::ConfigurationError, "#{name} must be a finite number of seconds > 0"
+        end
+
+        begin
+          QueueNameValidator.validate!(queue_name(workflow_queue))
+        rescue ArgumentError => e
+          raise Pgbus::ConfigurationError, "workflow_queue #{workflow_queue.inspect}: #{e.message}"
+        end
+
+        { workflow_max_payload_size: workflow_max_payload_size,
+          workflow_error_backtrace_lines: workflow_error_backtrace_lines }.each do |name, value|
+          raise Pgbus::ConfigurationError, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+        end
+
+        return if workflow_subject_url.nil? || workflow_subject_url.respond_to?(:call)
+
+        raise Pgbus::ConfigurationError, "workflow_subject_url must respond to #call (a Proc/lambda) or be nil"
+      end
+    end
+  end
+end

data/lib/pgbus/configuration.rb

@@ -7,6 +7,7 @@ module Pgbus
     include PresenceSettings
     include StreamAuthorization
     include DeploySettings
+    include WorkflowSettings
 
     # Connection settings
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
@@ -215,10 +216,16 @@ module Pgbus
 
     # Web dashboard
     attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source,
-                  :insights_default_minutes, :base_controller_class, :return_to_app_url,
+                  :insights_default_minutes, :base_controller_class, :return_to_app_url, :web_actor,
                   :metrics_enabled,
                   :web_filter_parameters, :web_filter_sensitive
 
+    # The MCP server's workflow write tools (issue #550): pgbus_workflow_resume,
+    # _cancel, _skip_step, _resume_at, _run_now and _signal. Off by default, and
+    # then they are never built, so tools/list cannot show them. Read once, when
+    # Pgbus::MCP::Server.build runs (pgbus mcp, Pgbus::MCP.rack_app).
+    attr_accessor :mcp_write_tools
+
     # HTTP health endpoints (liveness/readiness for orchestrators like
     # Kubernetes). `health_port` nil (default) leaves the standalone server in
     # the supervisor disabled — mount Pgbus::Web::HealthApp in the host Rails
@@ -365,6 +372,7 @@ module Pgbus
       @recurring_enabled = true
       @recurring_execution_retention = 7 * 24 * 3600 # 7 days
       initialize_deploy_settings
+      initialize_workflow_settings
 
       @zombie_detection = true
 
@@ -380,7 +388,13 @@ module Pgbus
       @require_primary = false
       @connection_guc_mode = :options
 
+      @mcp_write_tools = false
+
       @web_auth = nil
+      # ->(request) { String or nil }: who an operator action on the dashboard
+      # is recorded as ("dashboard:<name>"; nil → "dashboard"). web_auth only
+      # answers allow/deny, so the name comes from here.
+      @web_actor = nil
       @web_refresh_interval = 5000
       @web_per_page = 25
       @web_live_updates = true
@@ -941,12 +955,14 @@ module Pgbus
       end
 
       raise Pgbus::ConfigurationError, "require_primary must be true or false" unless [true, false].include?(require_primary)
+      raise Pgbus::ConfigurationError, "mcp_write_tools must be true or false" unless [true, false].include?(mcp_write_tools)
 
       validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
       validate_fair_share!
       validate_deploy_settings!
+      validate_workflow_settings!
 
       self
     end
@@ -1062,8 +1078,10 @@ module Pgbus
 
       # web_auth gates the dashboard; a non-callable value silently leaves it
       # open (mirror streams_presence_member).
-      unless web_auth.nil? || web_auth.respond_to?(:call)
-        raise Pgbus::ConfigurationError, "web_auth must respond to #call (a Proc/lambda) or be nil"
+      { web_auth: web_auth, web_actor: web_actor }.each do |name, value|
+        next if value.nil? || value.respond_to?(:call)
+
+        raise Pgbus::ConfigurationError, "#{name} must respond to #call (a Proc/lambda) or be nil"
       end
 
       raise Pgbus::ConfigurationError, "error_reporters must be an Array" unless error_reporters.is_a?(Array)

data/lib/pgbus/generators/migration_detector.rb

@@ -57,6 +57,22 @@ module Pgbus
         pgbus_batches
       ].freeze
 
+      # The three tables pgbus:add_workflows creates (issue #540).
+      WORKFLOW_TABLES = %w[pgbus_workflows pgbus_workflow_steps pgbus_workflow_events].freeze
+
+      # The waiting-step columns pgbus:add_workflow_signals adds to
+      # pgbus_workflow_steps (issue #541), with the pgbus_workflow_signals table.
+      WORKFLOW_WAITING_COLUMNS = %w[batch_id wait_for signal_id waiting_since timeout_at].freeze
+      WORKFLOW_WAITING_INDEXES = Ractor.make_shareable(
+        [
+          %w[pgbus_workflow_steps idx_pgbus_workflow_steps_batch],
+          %w[pgbus_workflow_steps idx_pgbus_workflow_steps_timeout],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_idempotency],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_pending],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_claimed]
+        ]
+      )
+
       # generator_key → Rails generator name. Passed to Thor's invoke.
       #
       # Note: uniqueness_keys invokes add_uniqueness_keys, which only
@@ -78,6 +94,8 @@ module Pgbus
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
         add_deploy_tasks: "pgbus:add_deploy_tasks",
+        add_workflows: "pgbus:add_workflows",
+        add_workflow_signals: "pgbus:add_workflow_signals",
         add_failed_events_index: "pgbus:add_failed_events_index",
         add_processed_event_completion: "pgbus:add_processed_event_completion",
         add_batch_executions: "pgbus:add_batch_executions",
@@ -101,6 +119,8 @@ module Pgbus
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
         add_deploy_tasks: "deploy tasks + runs tables (one-time jobs run after a rollover)",
+        add_workflows: "workflow tables (durable multi-step workflows: runs, step attempts, audit trail)",
+        add_workflow_signals: "waiting workflow steps (fan_out, wait_for: signals, wait timeouts)",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
         add_processed_event_completion: "completed_at on pgbus_processed_events (two-phase idempotency claim)",
         add_batch_executions: "batch execution-row tracking (self-healing completion, on_failure rename)",
@@ -130,6 +150,7 @@ module Pgbus
           *outbox_migrations,
           *recurring_migrations,
           *deploy_tasks_migrations,
+          *workflows_migrations,
           *failed_events_index_migrations,
           *processed_event_completion_migrations,
           *batch_executions_migrations,
@@ -226,6 +247,25 @@ module Pgbus
         [:add_deploy_tasks]
       end
 
+      # The add_workflows template uses if_not_exists throughout, so a
+      # half-present set of the three tables is safe to queue again.
+      #
+      # add_workflows carries the waiting-step schema too, so a database with
+      # no steps table needs only that one; a steps table without the columns
+      # (or a missing signals table) predates waiting steps.
+      def workflows_migrations
+        migrations = []
+        migrations << :add_workflows unless WORKFLOW_TABLES.all? { |table| table_exists?(table) }
+        return migrations unless table_exists?("pgbus_workflow_steps")
+
+        columns = column_names("pgbus_workflow_steps")
+        waiting = WORKFLOW_WAITING_COLUMNS.all? { |column| columns.include?(column) } &&
+                  table_exists?("pgbus_workflow_signals") &&
+                  WORKFLOW_WAITING_INDEXES.all? { |table, index| index_exists?(table, index) }
+        migrations << :add_workflow_signals unless waiting
+        migrations
+      end
+
       def failed_events_index_migrations
         # pgbus_failed_events is created by pgbus:install, but the
         # unique (queue_name, msg_id) index was added later via its own

data/lib/pgbus/instrumentation.rb

@@ -54,6 +54,38 @@ module Pgbus
   #   pgbus.batch_sweep            — dispatcher stalled-batch sweep
   #                                  payload: stalled_for, stale_executions, orphan_rows,
   #                                  started_batches, finished_batches
+  #   pgbus.workflow.step          — a workflow step attempt ended (body, guard, stall)
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  outcome (completed | reattempted | skipped | paused |
+  #                                  cancelled | finished_early), status (the step row's),
+  #                                  error_class (nil without an error), duration (seconds
+  #                                  the body ran; 0.0 for a guard; nil for a stall),
+  #                                  pickup_latency (seconds from scheduled_at to the claim)
+  #   pgbus.workflow_finished      — a workflow run finished
+  #                                  payload: workflow_class, workflow_id
+  #   pgbus.workflow_paused        — a workflow run paused (an exception, a stall, pause!)
+  #                                  payload: workflow_class, workflow_id, step_name,
+  #                                  error_class (nil for a manual pause)
+  #   pgbus.workflow_cancelled     — a workflow run was cancelled
+  #                                  payload: workflow_class, workflow_id, step_name
+  #   pgbus.workflow.stall_detected — a step was stalled on the redelivery of the message that
+  #                                  claimed it (detection: "redelivery": its worker died, or
+  #                                  its heartbeat lapsed) or after it outlived its stall_at
+  #                                  (detection: "sweep")
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  detection
+  #   pgbus.workflow.signal        — signal! stored a signal on a run (or found it stored:
+  #                                  a redelivery with the same idempotency key)
+  #                                  payload: workflow_class, workflow_id, name, duplicate,
+  #                                  woke (true when it woke the step waiting for it)
+  #   pgbus.workflow.wait_timed_out — a waiting step's wait_timeout: passed; its on_timeout
+  #                                  applied (the sweep, or TestHelpers#expire_wait)
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  action (pause! | cancel! | skip! | run)
+  #   pgbus.workflow.gauge         — emitted by each dispatcher workflow sweep
+  #                                  payload: statuses ([{ workflow_class:, status:, count: }]),
+  #                                  stuck ([{ workflow_class:, reason:, count: }]), zero-filled
+  #                                  across every known class; reasons include waiting_overdue
   #
   module Instrumentation
     module_function

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -4,7 +4,7 @@
   ],
   "dashboard": {
     "title": "Pgbus",
-    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\n",
+    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, and stuck workflows.\n",
     "visuals": [
       {
         "type": "timeseries",
@@ -393,6 +393,133 @@
             "tags": []
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow steps per outcome",
+        "description": "Workflow step attempts by class, step and outcome (completed, reattempted, skipped, paused, cancelled, finished_early).",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_steps_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow step run time (seconds)",
+        "description": "Mean and p95 run time of each workflow step's body, in seconds.",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_step_duration_seconds",
+            "fields": [
+              {
+                "field": "MEAN"
+              },
+              {
+                "field": "P95"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflows by status",
+        "description": "Workflow runs per class and status, from each dispatcher sweep.",
+        "line_label": "%workflow_class% - %status%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "status",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Stuck workflows",
+        "description": "Ongoing workflow runs that need a person, by class and reason (paused_error, stalled, paused_manual, overdue).",
+        "line_label": "%workflow_class% - %reason%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows_stuck",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "reason",
+                "value": "*"
+              }
+            ]
+          }
+        ]
       }
     ]
   }

data/lib/pgbus/integrations/appsignal/event_span.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "pgbus/integrations/appsignal/span_subscriber"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The `<Handler>#handle` transaction around pgbus.event_processed, and
+      # the fallback for an error pgbus.event_failed reports from outside it
+      # (an event that could not be built never reaches the span).
+      class EventSpan < SpanSubscriber
+        private
+
+        def frame_key = :pgbus_appsignal_event_span
+
+        def attached_key = :pgbus_appsignal_event_span_error
+
+        def describe(transaction, payload)
+          transaction.set_action_if_nil("#{payload[:handler] || "UnknownHandler"}#handle")
+          apply_queue_start(transaction, payload[:published_at])
+          transaction.add_tags(handler_tags(payload))
+        end
+
+        # The processed count is taken at finish whether or not the handler
+        # raised, as Metrics::Subscriber does: a raised handler counts as
+        # processed and, through pgbus.event_failed, as failed.
+        def finished(payload, duration)
+          tags = { handler: payload[:handler], routing_key: payload[:routing_key] }
+          ::Appsignal.add_distribution_value("pgbus_event_duration_ms", duration, tags)
+          ::Appsignal.increment_counter("pgbus_event_count", 1, tags.merge(status: "processed"))
+        end
+
+        def handler_tags(payload)
+          {
+            "handler" => payload[:handler],
+            "routing_key" => payload[:routing_key],
+            "attempts" => payload[:read_ct]
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/integrations/appsignal/job_span.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "pgbus/integrations/appsignal/span_subscriber"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The `<JobClass>#perform` transaction around pgbus.executor.execute
+      # (deserialize + perform + archive), and the fallback for an error
+      # pgbus.job_failed reports from outside it.
+      class JobSpan < SpanSubscriber
+        private
+
+        def frame_key = :pgbus_appsignal_job_span
+
+        def attached_key = :pgbus_appsignal_job_span_error
+
+        def describe(transaction, payload)
+          transaction.set_action_if_nil("#{payload[:job_class] || "UnknownJob"}#perform")
+          apply_queue_start(transaction, payload[:enqueued_at])
+          transaction.add_tags(job_tags(payload))
+          transaction.add_params_if_nil { { arguments: payload[:arguments] } } if payload.key?(:arguments)
+        end
+
+        def finished(payload, duration)
+          ::Appsignal.add_distribution_value(
+            "pgbus_job_duration_ms",
+            duration,
+            { queue: payload[:queue], job_class: payload[:job_class] }
+          )
+        end
+
+        def job_tags(payload)
+          tags = {
+            "queue" => payload[:queue],
+            "job_class" => payload[:job_class],
+            "attempts" => payload[:read_ct]
+          }
+          tags["active_job_id"] = payload[:job_id] if payload[:job_id]
+          tags["provider_job_id"] = payload[:provider_job_id] if payload[:provider_job_id]
+          tags["request_id"] = payload[:provider_job_id] || payload[:job_id]
+          tags.compact
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/integrations/appsignal/span_subscriber.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The AppSignal transaction of one unit of work: a job (JobSpan, on
+      # pgbus.executor.execute) or an event handler (EventSpan, on
+      # pgbus.event_processed).
+      #
+      # An ActiveSupport::Notifications listener that responds to #start and
+      # #finish is called on both sides of the instrumented block (the Evented
+      # subscriber). A finish-only block subscriber runs after the block has
+      # returned, so the transaction it opened was never current while the job
+      # ran: job code had nothing to attach to, and pgbus.job_failed, fired
+      # later, found no transaction to put its error on (issue #552). Here
+      # #start opens the transaction before the block runs, so job and handler
+      # code, and the Rails error reporter, find it current; #finish records
+      # the exception the block raised (the instrumenter puts it in
+      # payload[:exception_object]) and completes the transaction.
+      #
+      # Like AppSignal's own ActiveJob hook, a transaction that is already
+      # current is reused and left to its owner to complete.
+      #
+      # The frame lives in Thread.current[], which is fiber-local, so start and
+      # finish pair up per job under execution_mode: :async, the same way
+      # AppSignal keeps its current transaction. A span opened inside another
+      # of its kind (a handler calling another handler's #process) keeps the
+      # enclosing frame and restores it at finish, so the outer span still
+      # completes its transaction. An instance holds no state of its own.
+      # Nothing an AppSignal call raises reaches the job: it is logged at warn
+      # level.
+      #
+      # Subclasses define #frame_key and #attached_key (the fiber-local slots),
+      # #describe(transaction, payload) (action, queue start, tags) and
+      # #finished(payload, duration_ms) (the span's metrics).
+      class SpanSubscriber
+        BACKGROUND_JOB = "background_job"
+
+        # owned: this span created the transaction, so it completes it.
+        # previous: the enclosing span's frame, restored at finish.
+        Frame = Struct.new(:started_at, :owned, :previous)
+
+        def start(_name, _id, payload)
+          frame = Thread.current[frame_key] = Frame.new(monotonic_now, false, Thread.current[frame_key])
+          guard do
+            frame.owned = !::Appsignal::Transaction.current?
+            transaction = frame.owned ? ::Appsignal::Transaction.create(BACKGROUND_JOB) : ::Appsignal::Transaction.current
+            describe(transaction, payload)
+          end
+        end
+
+        def finish(_name, _id, payload)
+          frame = Thread.current[frame_key]
+          guard do
+            Thread.current[attached_key] = attach(payload[:exception_object])
+            finished(payload, monotonic_now - frame.started_at)
+          end
+        ensure
+          guard do
+            Thread.current[frame_key] = frame.previous
+            ::Appsignal::Transaction.complete_current! if frame.owned
+          end
+        end
+
+        # pgbus.job_failed and pgbus.event_failed fire after #finish. An error
+        # the span recorded is already on its transaction. One raised before
+        # the span opened (a message body that is not JSON, an event that
+        # cannot be built, a dead-letter move that failed) had no transaction,
+        # so it is reported on one of its own, named and tagged like the span's
+        # (or added to a transaction that is current, which is left as it is).
+        def report_unattached(error, payload)
+          attached = Thread.current[attached_key]
+          Thread.current[attached_key] = nil
+          return if error.nil? || error.equal?(attached)
+          return ::Appsignal::Transaction.current.set_error(error) if ::Appsignal::Transaction.current?
+
+          ::Appsignal.report_error(error) do |transaction|
+            transaction.set_namespace(BACKGROUND_JOB)
+            describe(transaction, payload)
+          end
+        end
+
+        private
+
+        # Returns the exception it recorded, nil when there was none.
+        def attach(error)
+          return unless error && ::Appsignal::Transaction.current?
+
+          ::Appsignal::Transaction.current.set_error(error)
+          error
+        end
+
+        # AppSignal expects queue-start as Unix epoch milliseconds. Pgbus
+        # carries it as either an ISO-8601 String or a Time — both happen
+        # in practice (executor passes the JSON string, handler passes a
+        # parsed Time).
+        def apply_queue_start(transaction, value)
+          return unless value
+
+          millis =
+            case value
+            when Time
+              (value.to_f * 1_000).to_i
+            when String
+              (Time.parse(value).to_f * 1_000).to_i
+            when Numeric
+              value.to_i
+            end
+          transaction.set_queue_start(millis) if millis
+        rescue ArgumentError
+          # Unparseable timestamp — skip rather than blow up.
+        end
+
+        def guard
+          yield
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus::AppSignal] subscriber error: #{e.class}: #{e.message}" }
+        end
+
+        def monotonic_now
+          ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :float_millisecond)
+        end
+      end
+    end
+  end
+end