pgbus 0.19.4 → 0.20.0

data/lib/generators/pgbus/templates/add_workflows.rb.erb

@@ -0,0 +1,150 @@
+class AddPgbusWorkflows < ActiveRecord::Migration<%= migration_version %>
+  # if_not_exists throughout: pgbus:update queues this migration when any of
+  # the three core tables is missing, so a half-present schema must not fail
+  # it. The waiting-step columns and pgbus_workflow_signals (issue #541) are
+  # here too, so a fresh install needs no pgbus:add_workflow_signals.
+  # up/down rather than change: Rails 7.1 cannot reverse an add_foreign_key
+  # that names its primary_key, and dropping the tables drops the keys.
+  def up
+    # One row per workflow run (Pgbus::WorkflowEntry).
+    create_table :pgbus_workflows, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :subject_type
+      t.string :subject_id
+      t.string :subject_gid
+      t.jsonb :arguments, null: false, default: {}
+      t.string :status, null: false, default: "ready"
+      t.string :current_step
+      t.jsonb :step_job_options, null: false, default: {}
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.datetime :paused_at
+      t.datetime :finished_at
+      t.datetime :cancelled_at
+      t.string :idempotency_key
+      t.string :definition_digest, null: false
+      t.string :rerun_of_workflow_id
+      t.datetime :created_at, null: false
+      t.datetime :updated_at, null: false
+    end
+
+    add_index :pgbus_workflows, :workflow_id,
+      unique: true, name: "idx_pgbus_workflows_workflow_id", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
+      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      name: "idx_pgbus_workflows_one_ongoing", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflows_idempotency", if_not_exists: true
+    add_index :pgbus_workflows, [:status, :updated_at],
+      name: "idx_pgbus_workflows_status", if_not_exists: true
+    add_index :pgbus_workflows, [:workflow_class, :status, :created_at],
+      name: "idx_pgbus_workflows_class_status", if_not_exists: true
+    add_index :pgbus_workflows, [:subject_type, :subject_id],
+      name: "idx_pgbus_workflows_subject", if_not_exists: true
+
+    # One row per step attempt (Pgbus::WorkflowStep).
+    create_table :pgbus_workflow_steps, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :step_name, null: false
+      t.integer :attempt, null: false, default: 1
+      t.string :status, null: false, default: "scheduled"
+      t.string :job_id
+      t.bigint :msg_id
+      t.datetime :scheduled_at, null: false
+      t.datetime :enqueued_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.datetime :stall_at
+      t.string :outcome
+      t.jsonb :output
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.jsonb :error_causes
+      t.string :worker
+      t.string :app_revision
+      # Waiting steps (fan_out, wait_for:): also added by pgbus:add_workflow_signals.
+      t.string :batch_id
+      t.string :wait_for
+      t.bigint :signal_id
+      t.datetime :waiting_since
+      t.datetime :timeout_at
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_steps, [:workflow_id, :step_name, :attempt],
+      unique: true, name: "idx_pgbus_workflow_steps_attempt", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:status, :scheduled_at],
+      name: "idx_pgbus_workflow_steps_scheduled", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:status, :stall_at],
+      name: "idx_pgbus_workflow_steps_stall", if_not_exists: true
+    add_index :pgbus_workflow_steps, [:workflow_class, :step_name, :finished_at],
+      name: "idx_pgbus_workflow_steps_insights", if_not_exists: true
+    # A steps table that predates waiting steps lacks these columns (the
+    # queued pgbus:add_workflow_signals adds them and their indexes).
+    if column_exists?(:pgbus_workflow_steps, :batch_id)
+      add_index :pgbus_workflow_steps, :batch_id,
+        name: "idx_pgbus_workflow_steps_batch", if_not_exists: true
+    end
+    if column_exists?(:pgbus_workflow_steps, :timeout_at)
+      add_index :pgbus_workflow_steps, [:status, :timeout_at],
+        name: "idx_pgbus_workflow_steps_timeout", if_not_exists: true
+    end
+    add_foreign_key :pgbus_workflow_steps, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+
+    # Append-only audit trail: one row per transition or operator action
+    # (Pgbus::WorkflowEvent).
+    create_table :pgbus_workflow_events, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.bigint :step_id
+      t.string :step_name
+      t.integer :attempt
+      t.string :event, null: false
+      t.string :actor, null: false
+      t.text :reason
+      t.jsonb :details, null: false, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_events, [:workflow_id, :id],
+      name: "idx_pgbus_workflow_events_workflow", if_not_exists: true
+    add_foreign_key :pgbus_workflow_events, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+
+    # One row per signal delivered to a run (Pgbus::WorkflowSignal):
+    # pending → claimed → consumed.
+    create_table :pgbus_workflow_signals, if_not_exists: true do |t|
+      t.string :workflow_id, null: false
+      t.string :name, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.string :idempotency_key
+      t.string :status, null: false, default: "pending"
+      t.bigint :claimed_by_step_id
+      t.datetime :created_at, null: false
+      t.datetime :claimed_at
+      t.datetime :consumed_at
+    end
+
+    add_index :pgbus_workflow_signals, [:workflow_id, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflow_signals_idempotency", if_not_exists: true
+    add_index :pgbus_workflow_signals, [:workflow_id, :name, :status],
+      name: "idx_pgbus_workflow_signals_pending", if_not_exists: true
+    add_index :pgbus_workflow_signals, [:workflow_id, :status, :claimed_by_step_id],
+      name: "idx_pgbus_workflow_signals_claimed", if_not_exists: true
+    add_foreign_key :pgbus_workflow_signals, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade, if_not_exists: true
+  end
+
+  def down
+    drop_table :pgbus_workflow_signals, if_exists: true
+    drop_table :pgbus_workflow_events, if_exists: true
+    drop_table :pgbus_workflow_steps, if_exists: true
+    drop_table :pgbus_workflows, if_exists: true
+  end
+end

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -211,6 +211,129 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     add_index :pgbus_deploy_task_runs, :run_at,
       name: "idx_pgbus_deploy_task_runs_cleanup"
 
+    # Workflows (Pgbus::Workflow): one row per run, one per step attempt, and
+    # the append-only audit trail. At most one ongoing run per (class, subject).
+    create_table :pgbus_workflows do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :subject_type
+      t.string :subject_id
+      t.string :subject_gid
+      t.jsonb :arguments, null: false, default: {}
+      t.string :status, null: false, default: "ready"
+      t.string :current_step
+      t.jsonb :step_job_options, null: false, default: {}
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.datetime :paused_at
+      t.datetime :finished_at
+      t.datetime :cancelled_at
+      t.string :idempotency_key
+      t.string :definition_digest, null: false
+      t.string :rerun_of_workflow_id
+      t.datetime :created_at, null: false
+      t.datetime :updated_at, null: false
+    end
+
+    add_index :pgbus_workflows, :workflow_id,
+      unique: true, name: "idx_pgbus_workflows_workflow_id"
+    add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
+      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      name: "idx_pgbus_workflows_one_ongoing"
+    add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflows_idempotency"
+    add_index :pgbus_workflows, [:status, :updated_at],
+      name: "idx_pgbus_workflows_status"
+    add_index :pgbus_workflows, [:workflow_class, :status, :created_at],
+      name: "idx_pgbus_workflows_class_status"
+    add_index :pgbus_workflows, [:subject_type, :subject_id],
+      name: "idx_pgbus_workflows_subject"
+
+    create_table :pgbus_workflow_steps do |t|
+      t.string :workflow_id, null: false
+      t.string :workflow_class, null: false
+      t.string :step_name, null: false
+      t.integer :attempt, null: false, default: 1
+      t.string :status, null: false, default: "scheduled"
+      t.string :job_id
+      t.bigint :msg_id
+      t.datetime :scheduled_at, null: false
+      t.datetime :enqueued_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.datetime :stall_at
+      t.string :outcome
+      t.jsonb :output
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+      t.jsonb :error_causes
+      t.string :worker
+      t.string :app_revision
+      t.string :batch_id
+      t.string :wait_for
+      t.bigint :signal_id
+      t.datetime :waiting_since
+      t.datetime :timeout_at
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_steps, [:workflow_id, :step_name, :attempt],
+      unique: true, name: "idx_pgbus_workflow_steps_attempt"
+    add_index :pgbus_workflow_steps, [:status, :scheduled_at],
+      name: "idx_pgbus_workflow_steps_scheduled"
+    add_index :pgbus_workflow_steps, [:status, :stall_at],
+      name: "idx_pgbus_workflow_steps_stall"
+    add_index :pgbus_workflow_steps, [:workflow_class, :step_name, :finished_at],
+      name: "idx_pgbus_workflow_steps_insights"
+    add_index :pgbus_workflow_steps, :batch_id,
+      name: "idx_pgbus_workflow_steps_batch"
+    add_index :pgbus_workflow_steps, [:status, :timeout_at],
+      name: "idx_pgbus_workflow_steps_timeout"
+    add_foreign_key :pgbus_workflow_steps, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
+    create_table :pgbus_workflow_events do |t|
+      t.string :workflow_id, null: false
+      t.bigint :step_id
+      t.string :step_name
+      t.integer :attempt
+      t.string :event, null: false
+      t.string :actor, null: false
+      t.text :reason
+      t.jsonb :details, null: false, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pgbus_workflow_events, [:workflow_id, :id],
+      name: "idx_pgbus_workflow_events_workflow"
+    add_foreign_key :pgbus_workflow_events, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
+    create_table :pgbus_workflow_signals do |t|
+      t.string :workflow_id, null: false
+      t.string :name, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.string :idempotency_key
+      t.string :status, null: false, default: "pending"
+      t.bigint :claimed_by_step_id
+      t.datetime :created_at, null: false
+      t.datetime :claimed_at
+      t.datetime :consumed_at
+    end
+
+    add_index :pgbus_workflow_signals, [:workflow_id, :idempotency_key],
+      unique: true, where: "idempotency_key IS NOT NULL",
+      name: "idx_pgbus_workflow_signals_idempotency"
+    add_index :pgbus_workflow_signals, [:workflow_id, :name, :status],
+      name: "idx_pgbus_workflow_signals_pending"
+    add_index :pgbus_workflow_signals, [:workflow_id, :status, :claimed_by_step_id],
+      name: "idx_pgbus_workflow_signals_claimed"
+    add_foreign_key :pgbus_workflow_signals, :pgbus_workflows,
+      column: :workflow_id, primary_key: :workflow_id, on_delete: :cascade
+
     # Stream queue registry — records which PGMQ queues back streams (vs jobs).
     # Stream and job queues share the pgbus_ namespace, so maintenance
     # (per-stream retention, orphan sweep) and wildcard workers rely on this
@@ -245,6 +368,10 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
     execute "SELECT pgmq.drop_queue('pgbus_default')"
 
     drop_table :pgbus_stream_queues
+    drop_table :pgbus_workflow_signals
+    drop_table :pgbus_workflow_events
+    drop_table :pgbus_workflow_steps
+    drop_table :pgbus_workflows
     drop_table :pgbus_deploy_task_runs
     drop_table :pgbus_deploy_tasks
     drop_table :pgbus_recurring_executions

data/lib/pgbus/active_job/delivery.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module ActiveJob
+    # The PGMQ delivery of the job running in this fiber:
+    #
+    #   Pgbus::ActiveJob::Delivery.current # => { msg_id: 42, read_ct: 2, queue_name: "default" }
+    #
+    # Set by Executor#execute around perform_now and cleared after, also when
+    # the job raises; nil outside the executor (perform_now in a test, a
+    # top-level inline-adapter job). A job run inline from inside an executing
+    # job sees the enclosing job's delivery; StepJob only acts on it when the
+    # step row's msg_id matches, so that is harmless. Fiber-local (Thread.current[]), so concurrent jobs under
+    # execution_mode: :async each see their own. Pgbus::Workflow::StepJob reads
+    # read_ct to tell a redelivery after a worker died from a first delivery.
+    #
+    # The three values sit in three fiber-locals and the Hash is built only
+    # when read: setting them allocates nothing, which keeps the executor's
+    # per-job allocation budget (spec/pgbus/active_job/executor_allocation_budget_spec.rb).
+    module Delivery
+      MSG_ID_KEY = :pgbus_delivery_msg_id
+      READ_CT_KEY = :pgbus_delivery_read_ct
+      QUEUE_NAME_KEY = :pgbus_delivery_queue_name
+
+      module_function
+
+      def current
+        msg_id = Thread.current[MSG_ID_KEY]
+        return nil if msg_id.nil?
+
+        { msg_id: msg_id, read_ct: Thread.current[READ_CT_KEY], queue_name: Thread.current[QUEUE_NAME_KEY] }
+      end
+
+      def with(msg_id:, read_ct:, queue_name:)
+        previous_msg_id = Thread.current[MSG_ID_KEY]
+        previous_read_ct = Thread.current[READ_CT_KEY]
+        previous_queue_name = Thread.current[QUEUE_NAME_KEY]
+        Thread.current[MSG_ID_KEY] = msg_id
+        Thread.current[READ_CT_KEY] = read_ct
+        Thread.current[QUEUE_NAME_KEY] = queue_name
+        yield
+      ensure
+        Thread.current[MSG_ID_KEY] = previous_msg_id
+        Thread.current[READ_CT_KEY] = previous_read_ct
+        Thread.current[QUEUE_NAME_KEY] = previous_queue_name
+      end
+    end
+  end
+end

data/lib/pgbus/active_job/executor.rb

@@ -99,7 +99,9 @@ module Pgbus
           # `batch` (and `batch.enqueue` for open batches) work inside a job.
           assign_batch_id(job, payload)
           Pgbus.logger.debug { "[Pgbus::Executor] running #{log_tag(message, queue_name)} job_class=#{job_class}" }
-          with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) { execute_job(job) }
+          with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) do
+            Delivery.with(msg_id: msg_id, read_ct: read_count, queue_name: queue_name) { execute_job(job) }
+          end
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
           # message carries the batch tag and signals on its own outcome.

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