pgbus 0.19.4 → 0.20.0

data/lib/pgbus/workflow/sweep.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The dispatcher's workflow housekeeping.
+    #
+    # repair (every config.workflow_sweep_interval):
+    # - an in_progress step past its stall_at (started_at + the step's
+    #   timeout:, or workflow_stall_threshold) gets workflow_stall_action,
+    #   with StepStalled recorded. A dead worker is usually caught sooner, on
+    #   redelivery (StepExecution); this catches a live but hung step, and
+    #   every crash when the visibility heartbeat is off.
+    # - a scheduled step of a ready run, due more than workflow_stall_threshold
+    #   ago and not sent within it, is sent again by bumping enqueued_at (the
+    #   model callback re-fires). No queue inspection: a duplicate message is
+    #   a no-op at the claim.
+    # - a waiting step of a waiting run past its timeout_at (wait_timeout:)
+    #   gets its on_timeout (WaitTimeout), so a timeout fires within one
+    #   workflow_sweep_interval of its deadline.
+    # - a fan_out step still waiting on a batch that finished more than
+    #   workflow_stall_threshold ago lost its BatchFinishedJob (dead-lettered,
+    #   or never sent): the sweep resolves it as the callback would have.
+    # - pgbus.workflow.gauge: runs by class and status, and by class and stuck
+    #   reason (waiting_overdue: waiting longer than
+    #   workflow_waiting_visibility_threshold on a step without a timeout).
+    #
+    # cleanup (hourly): finished and cancelled runs older than
+    # workflow_retention are deleted in batches; their steps and events go
+    # with them (ON DELETE CASCADE).
+    module Sweep
+      BATCH_SIZE = 500
+
+      # The schema probe's memo (a true answer is kept for the life of the
+      # process), read and written under the lock; the probe itself runs
+      # outside it.
+      @schema_lock = Mutex.new
+      @tables_ready = false
+      @waiting_ready = false
+
+      class << self
+        def repair(config: Pgbus.configuration, now: Time.current)
+          return nil unless tables_ready?
+
+          threshold = config.workflow_stall_threshold
+          summary = { stalled: repair_stalled(now: now, config: config), resent: resend_overdue(now: now, threshold: threshold) }
+          waiting = waiting_ready?
+          summary[:timed_out] = waiting ? WaitTimeout.expire_due(now: now) : 0
+          summary[:fan_outs] = waiting ? FanOut.resolve_lost(now: now, grace: threshold) : 0
+          emit_gauge(now: now, threshold: threshold, waiting_threshold: (config.workflow_waiting_visibility_threshold if waiting))
+          summary
+        end
+
+        def cleanup(retention: Pgbus.configuration.workflow_retention, now: Time.current, batch_size: BATCH_SIZE)
+          return 0 unless retention&.positive? && tables_ready?
+
+          cutoff = now - retention
+          deleted = 0
+          loop do
+            ids = WorkflowEntry.stale(before: cutoff).order(:id).limit(batch_size).pluck(:id)
+            break if ids.empty?
+
+            deleted += WorkflowEntry.where(id: ids).delete_all
+          end
+          deleted
+        end
+
+        # True once the three workflow tables exist (pgbus:add_workflows).
+        def tables_ready?
+          return true if @schema_lock.synchronize { @tables_ready }
+
+          ready = begin
+            [WorkflowEntry, WorkflowStep, WorkflowEvent].all?(&:table_exists?)
+          rescue StandardError => e
+            Pgbus.logger.debug { "[Pgbus] Workflow table probe failed: #{e.class}: #{e.message}" }
+            false
+          end
+          @schema_lock.synchronize { @tables_ready = true } if ready
+          ready
+        end
+
+        # True once the waiting-step schema exists (pgbus:add_workflow_signals,
+        # or an add_workflows that carries it): the signals table and the
+        # step columns. Asked of the database through the connection, not the
+        # schema cache (which keeps a negative answer). A process that loaded
+        # the step model before the migration still needs a restart to see
+        # the new columns, as for any column added under a running app.
+        def waiting_ready?
+          return true if @schema_lock.synchronize { @waiting_ready }
+
+          ready = begin
+            connection = WorkflowStep.connection
+            connection.table_exists?(WorkflowSignal.table_name) && connection.column_exists?(WorkflowStep.table_name, :timeout_at)
+          rescue StandardError => e
+            Pgbus.logger.debug { "[Pgbus] Workflow waiting-step schema probe failed: #{e.class}: #{e.message}" }
+            false
+          end
+          @schema_lock.synchronize { @waiting_ready = true } if ready
+          ready
+        end
+
+        # Specs only.
+        def reset_tables_ready!
+          @schema_lock.synchronize do
+            @tables_ready = false
+            @waiting_ready = false
+          end
+        end
+
+        private
+
+        def repair_stalled(now:, config:)
+          WorkflowStep.stalled(now: now).order(:id).limit(BATCH_SIZE).pluck(:id, :workflow_id).count do |id, workflow_id|
+            stall(id, workflow_id, now: now, config: config)
+          end
+        end
+
+        # Re-checked under the run's lock: the step may have finished since
+        # the query.
+        def stall(id, workflow_id, now:, config:)
+          Runner.locked(workflow_id) do |record, notes|
+            step = record && WorkflowStep.find_by(id: id)
+            next false unless step&.status == "in_progress" && step.stall_at && step.stall_at < now
+
+            StepOutcome.stall!(record, step, detection: "sweep", notes: notes, config: config)
+            true
+          end
+        end
+
+        def resend_overdue(now:, threshold:)
+          WorkflowStep.overdue(threshold: threshold, now: now).order(:id).limit(BATCH_SIZE).to_a.each do |step|
+            step.update!(enqueued_at: now)
+          end.size
+        end
+
+        def emit_gauge(now:, threshold:, waiting_threshold: nil)
+          statuses = WorkflowEntry.status_counts
+          stuck = WorkflowEntry.stuck_reason_counts(threshold: threshold, now: now, waiting_threshold: waiting_threshold)
+          classes = (statuses.keys.map(&:first) + stuck.keys.map(&:first) + Workflow.registered_classes.map(&:name)).uniq.sort
+          Instrumentation.instrument(
+            "pgbus.workflow.gauge",
+            statuses: zero_filled(classes, States::WORKFLOW, statuses, :status),
+            stuck: zero_filled(classes, States::STUCK_REASONS, stuck, :reason)
+          )
+        end
+
+        # Every class × every value, so a count that drops to zero is
+        # reported as zero instead of keeping its last value.
+        def zero_filled(classes, values, counts, key)
+          classes.product(values).map do |klass, value|
+            { workflow_class: klass, key => value, count: counts.fetch([klass, value], 0) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/test_helpers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # Run workflow steps inline in a spec, ignoring their wait:.
+    #
+    #   RSpec.configure { |config| config.include Pgbus::Workflow::TestHelpers }
+    #
+    #   wf = SignupWorkflow.start!(user)
+    #   perform_next_step(wf)           # runs :welcome now
+    #   run_step_inline(wf, :reminder)  # runs :reminder, raising if another step is next
+    #   speedrun_workflow(wf)           # runs every step until the run stops being ready
+    #   expect(wf.status).to eq("finished")
+    #
+    #   deliver_signal(wf, :shipped, payload: { at: Time.current })  # signal!, then the step it wakes
+    #   complete_fan_out(wf)            # every member of the waiting fan_out's batch completes
+    #   expire_wait(wf)                 # the waiting step's on_timeout applies now
+    #
+    # Each step runs through the real StepJob (claim, guards, policies, the
+    # audit trail) against the test database; the StepJob messages the
+    # model callback sends meanwhile go to whatever adapter the test uses
+    # and are not needed.
+    module TestHelpers
+      class Error < Workflow::Error; end
+
+      # Runs the run's scheduled step now. Returns the reloaded workflow.
+      def perform_next_step(workflow)
+        TestHelpers.ensure_ready!(workflow)
+        step = TestHelpers.scheduled_step(workflow) || raise(Error, "#{workflow.inspect} has no scheduled step")
+        TestHelpers.perform(step, workflow)
+        workflow.reload
+      end
+
+      # Runs the run's scheduled step when it is +step_name+; raises when the
+      # run is on another step.
+      def run_step_inline(workflow, step_name)
+        TestHelpers.ensure_ready!(workflow)
+        step = TestHelpers.scheduled_step(workflow)
+        unless step&.step_name == step_name.to_s
+          raise Error, "#{workflow.inspect} is not about to run #{step_name} (scheduled: #{step&.step_name || "nothing"})"
+        end
+
+        TestHelpers.perform(step, workflow)
+        workflow.reload
+      end
+
+      # Runs scheduled steps one after another until the run is no longer
+      # ready: it stops at paused, finished and cancelled, and raises
+      # Pgbus::Workflow::StepWaiting on waiting, naming what the step waits
+      # for (deliver_signal, complete_fan_out or expire_wait moves it on).
+      def speedrun_workflow(workflow, max_steps: 1_000)
+        max_steps.times do
+          case workflow.reload.status
+          when "ready" then perform_next_step(workflow)
+          when "waiting" then raise StepWaiting, "#{workflow.inspect} #{TestHelpers.waiting_for(workflow)}"
+          when "performing"
+            raise Error, "#{workflow.inspect} is performing: speedrun_workflow cannot move it on"
+          else return workflow
+          end
+        end
+        status = workflow.reload.status
+        raise StepWaiting, "#{workflow.inspect} #{TestHelpers.waiting_for(workflow)}" if status == "waiting"
+        return workflow unless %w[ready performing].include?(status)
+
+        raise Error, "#{workflow.inspect} was still #{workflow.status} after #{max_steps} steps"
+      end
+
+      # signal! the run, then run the step it scheduled (the waiting step it
+      # woke, or the step that claims a buffered signal). Returns the
+      # reloaded workflow.
+      # A redelivery (duplicate_delivery?) woke nothing, so it runs nothing.
+      def deliver_signal(workflow, name, payload: {}, idempotency_key: nil)
+        signal = workflow.signal!(name, payload: payload, idempotency_key: idempotency_key, actor: "test_helpers")
+        return workflow.reload if signal.duplicate_delivery?
+
+        perform_next_step(workflow)
+      end
+
+      # Completes every member of the batch the run's waiting fan_out step
+      # waits on (Pgbus::Batch.job_completed, as the executor does), then
+      # runs the batch's BatchFinishedJob inline. The members do not run.
+      # Returns the reloaded workflow.
+      def complete_fan_out(workflow)
+        step = TestHelpers.waiting_step(workflow)
+        raise Error, "#{workflow.inspect} is not waiting on a fan_out batch" unless step&.batch_id
+
+        if Pgbus::Batch.executions_migrated?
+          Pgbus::BatchExecution.where(batch_id: step.batch_id).order(:id).pluck(:job_id).each do |job_id|
+            Pgbus::Batch.job_completed(step.batch_id, job_id: job_id)
+          end
+        else
+          Pgbus::Batch.find(step.batch_id)&.pending_jobs.to_i.times { Pgbus::Batch.job_completed(step.batch_id) }
+        end
+        BatchFinishedJob.new(step.id).perform_now
+        workflow.reload
+      end
+
+      # Applies the waiting step's on_timeout now, whatever its timeout_at.
+      # Returns the reloaded workflow.
+      def expire_wait(workflow)
+        step = TestHelpers.waiting_step(workflow)
+        raise Error, "#{workflow.inspect} has no waiting step with a wait_timeout:" unless step&.timeout_at
+
+        Runner.locked(workflow.workflow_id) do |record, notes|
+          WaitTimeout.fire!(record, WorkflowStep.find(step.id), notes: notes)
+        end
+        workflow.reload
+      end
+
+      # A paused or finished run's scheduled step is not claimable: running
+      # it would silently do nothing (and pull its wait forward for resume!).
+      def self.ensure_ready!(workflow)
+        status = workflow.reload.status
+        return if status == "ready"
+        raise StepWaiting, "#{workflow.inspect} #{waiting_for(workflow)}" if status == "waiting"
+
+        hint = case status
+               when "paused" then "resume! it first"
+               when "finished", "cancelled" then "it is over; rerun! starts a new run"
+               when "performing" then "a step is still running"
+               else "nothing inline can move it on"
+               end
+        raise Error, "#{workflow.inspect} is #{status}, not ready: #{hint}"
+      end
+
+      def self.waiting_step(workflow)
+        WorkflowStep.where(workflow_id: workflow.workflow_id, status: "waiting").order(:id).last
+      end
+
+      # "is waiting for signal shipped (deliver_signal …)" / "… batch (complete_fan_out …)".
+      def self.waiting_for(workflow)
+        step = waiting_step(workflow)
+        return "is waiting" unless step
+        return "is waiting on step #{step.step_name}'s batch #{step.batch_id}: complete_fan_out moves it on" if step.batch_id
+
+        "is waiting on step #{step.step_name} for signal #{step.wait_for}: deliver_signal moves it on" \
+          "#{", expire_wait times it out" if step.timeout_at}"
+      end
+
+      def self.scheduled_step(workflow)
+        WorkflowStep.where(workflow_id: workflow.workflow_id, status: "scheduled").order(:id).last
+      end
+
+      # A step still waiting is pulled forward through run_now!, so the audit
+      # trail records the skipped wait (actor "test_helpers").
+      def self.perform(step, workflow)
+        workflow.run_now!(actor: "test_helpers", reason: "run inline by a test helper") if step.scheduled_at > Time.current
+        StepJob.new(step.id).perform_now
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/wait_timeout.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # wait_timeout: on a wait_for: step (issue #541). The dispatcher's
+    # workflow sweep finds waiting steps of waiting runs whose timeout_at
+    # passed and applies their on_timeout under the run's row lock, so a
+    # timeout fires within config.workflow_sweep_interval of its deadline:
+    #
+    #   :pause!  the step fails with WaitTimedOut and the run pauses
+    #   :cancel! the run is cancelled
+    #   :skip!   the step is skipped and the run moves on
+    #   :run     the step is scheduled again; its body runs with
+    #            received_signal nil and timed_out? true
+    #
+    # A signal that arrives after the timeout fired stays pending, like any
+    # signal no step waits for. A paused run's wait does not time out until
+    # it is resumed.
+    module WaitTimeout
+      module_function
+
+      # Drains every due wait, Sweep::BATCH_SIZE at a time (at most
+      # +max_batches+ of them per sweep, so one sweep cannot run unbounded).
+      def expire_due(now: Time.current, limit: Sweep::BATCH_SIZE, max_batches: 20)
+        total = 0
+        max_batches.times do
+          batch = WorkflowStep.wait_expired(now: now).order(:id).limit(limit).pluck(:id, :workflow_id)
+          total += expire_batch(batch, now: now)
+          break if batch.size < limit
+        end
+        total
+      end
+
+      def expire_batch(batch, now:)
+        batch.count do |id, workflow_id|
+          Runner.locked(workflow_id) do |record, notes|
+            step = record && WorkflowStep.find_by(id: id)
+            next false unless record&.status == "waiting" && step&.status == "waiting" && step.timeout_at && step.timeout_at < now
+
+            fire!(record, step, notes: notes, now: now)
+            true
+          end
+        end
+      end
+
+      # Applies the step's on_timeout now (the sweep, and expire_wait in
+      # TestHelpers). Returns the action applied.
+      def fire!(record, step, notes:, now: Time.current)
+        definition = record.workflow_klass&.workflow_steps&.fetch(step.step_name)
+        action = definition&.on_timeout || :pause!
+        Runner.event!(record, "wait_timed_out", actor: Runner::SYSTEM_ACTOR, step: step,
+                                                details: { wait_for: step.wait_for, action: action.to_s,
+                                                           timeout_at: step.timeout_at&.utc&.iso8601(3) }.compact)
+        notes.instrument("pgbus.workflow.wait_timed_out",
+                         Runner.payload_for(record, step_name: step.step_name, attempt: step.attempt, action: action.to_s))
+        apply(record, step, action, notes: notes, now: now)
+        action
+      end
+
+      def apply(record, step, action, notes:, now:)
+        return Waiting.wake!(record, step, now: now, timeout_at: [step.timeout_at, now].compact.min) if action == :run
+
+        error = action == :pause! ? timed_out_error(step, now) : nil
+        Waiting.resolve!(record, step, FlowControl::Outcome.for(action), notes: notes, error: error)
+      end
+
+      def timed_out_error(step, now)
+        WaitTimedOut.new("#{step.step_name} waited for #{step.wait_for} since #{step.waiting_since&.utc&.iso8601} " \
+                         "and timed out at #{(step.timeout_at || now).utc.iso8601}")
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/waiting.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The waiting state wait_for: steps and fan_out steps share (issue #541),
+    # every move under the run's row lock:
+    #
+    #   park!    in_progress → waiting   the gate found no signal, or the
+    #                                    fan_out batch opened (run: park)
+    #   wake!    waiting → scheduled     a signal it matches arrived, or the
+    #                                    wait timed out with on_timeout: :run
+    #                                    (run: wake); the model callback sends
+    #                                    the StepJob once the write commits
+    #   resolve! waiting → (an outcome)  the batch finished, the wait timed
+    #                                    out, or an operator skipped it: the
+    #                                    outcome is applied by StepOutcome as
+    #                                    for any finished attempt (run: resolve,
+    #                                    then advance, finish, step_pause, ...)
+    #
+    # A run an outside pause! reached first stays paused (hold): the step row
+    # moves, nothing runs, and resume! picks it up.
+    module Waiting
+      module_function
+
+      # False when the attempt had already lost its in_progress row (stalled
+      # or cancelled while it ran).
+      # A fan_out's +output+ (the body's output(...)) waits on the row.
+      def park!(record, step, now:, batch_id: nil, wait_for: nil, timeout_at: nil, output: nil) # rubocop:disable Naming/PredicateMethod
+        attrs = { waiting_since: now, stall_at: nil, batch_id: batch_id, wait_for: wait_for, timeout_at: timeout_at }
+        attrs[:output] = output if output
+        return false if WorkflowStep.park!(step.id, **attrs).zero?
+
+        step.assign_attributes(status: "waiting", **attrs)
+        Runner.transition!(record, paused?(record) ? :hold : :park)
+        Runner.event!(record, "step_waiting", actor: Runner::SYSTEM_ACTOR, step: step,
+                                              details: { wait_for: wait_for, batch_id: batch_id,
+                                                         timeout_at: timeout_at&.utc&.iso8601(3) }.compact)
+        true
+      end
+
+      # A paused run's step is written without the model callback, so no
+      # StepJob goes out that its claim would only drop; resume! sends it.
+      def wake!(record, step, now:, **attrs)
+        if paused?(record)
+          step.update_columns(status: "scheduled", scheduled_at: now, **attrs)
+          Runner.transition!(record, :hold)
+        else
+          step.update!(status: "scheduled", scheduled_at: now, **attrs)
+          Runner.transition!(record, :wake)
+        end
+      end
+
+      # Returns false when the row was no longer waiting.
+      def resolve!(record, step, outcome, notes:, error: nil)
+        return false if WorkflowStep.unpark!(step.id).zero?
+
+        step.assign_attributes(status: "in_progress")
+        Runner.transition!(record, :resolve) unless paused?(record)
+        output = step.respond_to?(:output) ? step.output : nil
+        StepOutcome.apply(record, step, outcome, notes: notes, error: error, output: output)
+      end
+
+      # start! (and rerun!) of a class with waiting steps needs their schema.
+      def check_schema!(klass)
+        definitions = klass.workflow_steps.definitions
+        fan_out = definitions.any? { |definition| definition.kind == "fan_out" }
+        return unless fan_out || definitions.any?(&:waits_for_signal?)
+
+        unless Sweep.waiting_ready?
+          raise WaitingStepsUnmigrated, "#{klass.name} has waiting steps (fan_out or wait_for:): run " \
+                                        "`rails generate pgbus:add_workflow_signals` and migrate first"
+        end
+        return unless fan_out && !Batch.callback_jobs_migrated?
+
+        raise BatchCallbacksUnmigrated, "#{klass.name} has a fan_out step, whose batch resumes the run through a " \
+                                        "callback job: run `rails generate pgbus:add_batch_callback_jobs` and migrate first"
+      end
+
+      def paused?(record) = record.status == "paused"
+    end
+  end
+end

data/lib/pgbus/workflow.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/indifferent_access"
+
+module Pgbus
+  # A durable multi-step workflow (issue #540). Subclass it, declare steps,
+  # start a run:
+  #
+  #   class SignupWorkflow < Pgbus::Workflow
+  #     cancel_if { subject.nil? || subject.closed? }
+  #     on_exception Net::OpenTimeout, action: :reattempt!, wait: 15.seconds, max_reattempts: 5
+  #
+  #     step :welcome do
+  #       WelcomeMailer.with(user: subject).welcome.deliver_later
+  #     end
+  #
+  #     step :reminder, wait: 2.days, skip_if: -> { subject.onboarded? } do
+  #       ReminderMailer.with(user: subject).remind.deliver_later
+  #     end
+  #   end
+  #
+  #   wf = SignupWorkflow.start!(user, plan: "pro")
+  #   wf.pause!(actor: "alice", reason: "SMTP down") / wf.resume! / wf.cancel!
+  #
+  # Each step attempt is a pgbus_workflow_steps row and one
+  # Pgbus::Workflow::StepJob message, sent after the row commits. The step
+  # body runs on a fresh instance of the class, with +subject+ and
+  # +arguments+. Pgbus::WorkflowEntry is the run's row; this class is the
+  # DSL and the handle.
+  class Workflow
+    class Error < Pgbus::Error; end
+
+    # A second start! for a subject that already has an ongoing run of this
+    # class. #workflow is the run that holds the slot.
+    class AlreadyRunning < Error
+      attr_reader :workflow
+
+      def initialize(message = nil, workflow: nil)
+        super(message)
+        @workflow = workflow
+      end
+    end
+
+    # A transition the States table does not allow from the workflow's state.
+    class InvalidTransition < Error; end
+
+    # resume!/resume_at! on a workflow that is not paused.
+    class NotPaused < InvalidTransition; end
+
+    # A row names a step the class does not define (and no removed_step
+    # gravestone covers it), or resume_at! names an unknown step.
+    class StepNotDefined < Error; end
+
+    # Recorded on a step whose worker died or that outlived its stall_at.
+    class StepStalled < Error; end
+
+    # Arguments or a step output over config.workflow_max_payload_size.
+    class PayloadTooLarge < Error; end
+
+    # A step-only verb or reader (reattempt!, finished!, output,
+    # step_idempotency_key, received_signal) called outside a step body.
+    class NotInStep < Error; end
+
+    # signal! on a finished or cancelled run, or by subject when the subject
+    # has no ongoing run of the class (missing: :raise).
+    class NotOngoing < InvalidTransition; end
+
+    # Recorded on a fan_out step whose batch had dead-lettered members.
+    class FanOutFailed < Error; end
+
+    # Recorded on a waiting step whose wait_timeout: passed with on_timeout: :pause!.
+    class WaitTimedOut < Error; end
+
+    # start! of a class with a fan_out step before the batch callback-job
+    # columns exist (rails generate pgbus:add_batch_callback_jobs).
+    class BatchCallbacksUnmigrated < Error; end
+
+    # start! of a class with a fan_out or wait_for: step before the
+    # waiting-step schema exists (rails generate pgbus:add_workflow_signals).
+    class WaitingStepsUnmigrated < Error; end
+
+    # speedrun_workflow reached a step that waits for a signal or a batch.
+    class StepWaiting < Error; end
+
+    extend DSL
+    include FlowControl
+    include Instance
+
+    # Class-level declarations: frozen values replaced whole by the DSL, set
+    # while the class body loads and only read afterwards.
+    # rubocop:disable ThreadSafety/ClassAndModuleAttributes -- written only by the class body at load, each a frozen value replaced whole
+    class_attribute :_workflow_steps, instance_accessor: false, instance_predicate: false, default: Steps::EMPTY
+    class_attribute :_cancel_conditions, instance_accessor: false, instance_predicate: false, default: [].freeze
+    class_attribute :_exception_policies, instance_accessor: false, instance_predicate: false, default: [].freeze
+    class_attribute :_step_job_options, instance_accessor: false, instance_predicate: false, default: {}.freeze
+    # rubocop:enable ThreadSafety/ClassAndModuleAttributes
+
+    class << self
+      def inherited(subclass)
+        super
+        Registry.register(subclass)
+      end
+
+      # Every subclass that has a name, once (what the insights page lists).
+      def registered_classes = Registry.classes
+
+      # Start a run: the workflow row and its first step row, in one
+      # transaction; the first StepJob is sent once that commits.
+      #
+      #   SignupWorkflow.start!(user, plan: "pro")    # arguments["plan"]
+      #   CheckoutWorkflow.start!(order, idempotency_key: "checkout-#{order.id}")
+      #
+      # +idempotency_key+ is reserved: with one, a second start! with the same
+      # key returns the first run (any status) with duplicate_start? true.
+      # Raises AlreadyRunning when the subject already has an ongoing run.
+      def start!(subject = nil, idempotency_key: nil, **arguments)
+        Runner.start(self, subject: subject, arguments: arguments, idempotency_key: idempotency_key)
+      end
+
+      # The run with this workflow_id, as an instance of the class that
+      # started it; nil when there is none, or when that class is not this
+      # one or a subclass of it. Pgbus::Workflow.find finds any run (as a
+      # bare Pgbus::Workflow when its class no longer exists, so it can still
+      # be cancelled).
+      def find(workflow_id)
+        record = WorkflowEntry.find_by(workflow_id: workflow_id)
+        return nil unless record
+
+        klass = record.workflow_klass || Workflow
+        klass <= self ? klass.new(record) : nil
+      end
+
+      # Signal the ongoing run of this class for +subject+ (a webhook that
+      # knows the order, not the run):
+      #
+      #   OrderWorkflow.signal!(order, :payment_confirmed, payload: { amount: 42 }, idempotency_key: event.id,
+      #                         missing: :ignore)
+      #
+      # The one-ongoing-per-subject index means at most one run matches. With
+      # none (never started, or already over), missing: :raise raises
+      # NotOngoing and missing: :ignore returns nil. A subject-less run is
+      # signalled through its handle: find(workflow_id).signal!.
+      def signal!(subject, name, payload: {}, idempotency_key: nil, missing: :raise, actor: nil, reason: nil)
+        raise ArgumentError, "missing: must be :raise or :ignore, got #{missing.inspect}" unless %i[raise ignore].include?(missing)
+        if subject.nil?
+          raise ArgumentError, "#{self.name}.signal! needs a subject; signal a subject-less run through its handle " \
+                               "(#{self.name}.find(workflow_id).signal!)"
+        end
+
+        attrs = Payload.subject_attributes(subject)
+        record = WorkflowEntry.ongoing.find_by(workflow_class: self.name, subject_type: attrs[:subject_type],
+                                               subject_id: attrs[:subject_id])
+        raise NotOngoing, "#{self.name} has no ongoing run for #{attrs[:subject_type]} #{attrs[:subject_id]}" unless record
+
+        new(record).signal!(name, payload: payload, idempotency_key: idempotency_key, actor: actor, reason: reason)
+      rescue NotOngoing
+        raise if missing == :raise
+
+        nil
+      end
+
+      # How many ongoing runs still sit on each removed step:
+      # { "reminder" => 3 }. A gravestone can go once its count is zero.
+      def removed_steps_in_flight
+        names = _workflow_steps.removed_names
+        return {} if names.empty?
+
+        counts = WorkflowEntry.ongoing.where(workflow_class: name, current_step: names).group(:current_step).count
+        names.to_h { |step_name| [step_name, counts.fetch(step_name, 0)] }
+      end
+    end
+
+    attr_reader :record
+
+    def initialize(record, duplicate_start: false)
+      @record = record
+      @duplicate_start = duplicate_start
+      @step_context = nil
+    end
+  end
+end