pgbus 0.19.4 → 0.20.0

data/lib/pgbus/workflow/runner.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+
+module Pgbus
+  class Workflow
+    # The transitions every caller shares: start!, the outside verbs, the
+    # StepJob and the sweep. Each change happens under the workflow row lock
+    # (WorkflowEntry.lock_for) as a guarded UPDATE whose WHERE status IN (...)
+    # comes from the States table, and writes its WorkflowEvent in the same
+    # transaction. Instrumentation and error reports wait until it commits.
+    module Runner
+      DEFAULT_ACTOR = "app"
+      SYSTEM_ACTOR = "system"
+
+      # Instrumentation events and error reports collected inside a
+      # transaction, sent once it is over.
+      class Notes
+        def initialize
+          @entries = []
+        end
+
+        def instrument(event, payload) = @entries << [:instrument, event, payload]
+
+        def report(error, context) = @entries << [:report, error, context]
+
+        def flush
+          entries = @entries
+          @entries = []
+          entries.each do |kind, subject, detail|
+            kind == :instrument ? Instrumentation.instrument(subject, detail) : ErrorReporter.report(subject, detail)
+          end
+        end
+
+        # Sends now, or, when the transition ran inside an app's transaction
+        # on the same connection, once that transaction commits (and never
+        # if it rolls back): what is reported must have happened.
+        def flush_after_commit(connection)
+          return flush unless connection.transaction_open?
+
+          connection.add_transaction_record(AfterCommit.new(self))
+        end
+
+        # The transaction-record interface ActiveRecord calls on commit and
+        # rollback (the one after_commit callbacks use), on 7.1 and later;
+        # ActiveRecord.after_all_transactions_commit needs 7.2.
+        class AfterCommit
+          def initialize(notes)
+            @notes = notes
+          end
+
+          def trigger_transactional_callbacks? = true
+
+          def has_transactional_callbacks? = true # rubocop:disable Naming/PredicatePrefix -- ActiveRecord's name
+
+          def before_committed!; end
+
+          def committed!(*, **) = @notes.flush
+
+          def rolledback!(*, **); end
+
+          def add_to_transaction(*); end
+        end
+      end
+
+      module_function
+
+      # --- start! and rerun! --------------------------------------------
+
+      def start(klass, subject:, arguments:, idempotency_key: nil)
+        attrs = run_attributes(klass, idempotency_key: idempotency_key)
+                .merge(Payload.subject_attributes(subject))
+                .merge(arguments: Payload.dump(arguments, what: "arguments of #{klass.name}"))
+        insert_run(klass, attrs, actor: DEFAULT_ACTOR)
+      end
+
+      # A finished or cancelled run started again: same subject and
+      # arguments (copied as stored, not reloaded), no idempotency key.
+      def rerun(workflow, actor:, reason: nil)
+        WorkflowEntry.transaction do
+          old = WorkflowEntry.lock_for(workflow.workflow_id) || raise(ActiveRecord::RecordNotFound,
+                                                                      "workflow #{workflow.workflow_id} is gone")
+          States.check!(:rerun, old.status)
+          klass = old.workflow_klass || raise(StepNotDefined, "#{old.workflow_class} is not a Pgbus::Workflow class any more")
+          attrs = run_attributes(klass, rerun_of: old.workflow_id)
+                  .merge(old.attributes.symbolize_keys.slice(:subject_type, :subject_id, :subject_gid, :arguments))
+          rerun = insert_run(klass, attrs, actor: actor, reason: reason)
+          event!(old, "rerun", actor: actor, reason: reason, details: { rerun_workflow_id: rerun.workflow_id })
+          rerun
+        end
+      end
+
+      def run_attributes(klass, idempotency_key: nil, rerun_of: nil)
+        raise ArgumentError, "an anonymous workflow class cannot start: give it a constant name" unless klass.name
+
+        first = klass.workflow_steps.first
+        raise ArgumentError, "#{klass.name} declares no steps" unless first
+
+        Waiting.check_schema!(klass)
+
+        now = Time.current
+        { workflow_id: SecureRandom.uuid, workflow_class: klass.name, status: "ready", current_step: first.name,
+          step_job_options: klass.step_job_options.transform_keys(&:to_s), idempotency_key: idempotency_key&.to_s,
+          definition_digest: klass.definition_digest, rerun_of_workflow_id: rerun_of, created_at: now, updated_at: now }
+      end
+
+      # The run row and its first step row in one transaction (a savepoint
+      # inside an app transaction, so a unique violation leaves the app's
+      # transaction usable). The first StepJob goes out when it commits.
+      def insert_run(klass, attrs, actor:, reason: nil)
+        record, duplicate = WorkflowEntry.transaction(requires_new: true) do
+          next [existing_run(klass, attrs), true] unless WorkflowEntry.insert_run!(attrs)
+
+          record = WorkflowEntry.find_by!(workflow_id: attrs[:workflow_id])
+          event!(record, "started", actor: actor, reason: reason, details: { rerun_of: attrs[:rerun_of_workflow_id] }.compact)
+          first = klass.workflow_steps.first
+          schedule!(record, first.name, at: Time.current + first.wait, actor: actor)
+          [record, false]
+        end
+        klass.new(record, duplicate_start: duplicate)
+      rescue ActiveRecord::RecordNotUnique
+        # ON CONFLICT only absorbs the idempotency index. Two concurrent
+        # starts with the same key and subject can instead trip the
+        # one-ongoing index first; by then the winner has committed, so its
+        # key is visible: that is still a duplicate start, not a second run.
+        existing = attrs[:idempotency_key] && existing_run(klass, attrs, required: false)
+        return klass.new(existing, duplicate_start: true) if existing
+
+        holder = WorkflowEntry.ongoing.find_by(workflow_class: klass.name, subject_type: attrs[:subject_type],
+                                               subject_id: attrs[:subject_id])
+        raise AlreadyRunning.new("#{klass.name} already has an ongoing run for #{attrs[:subject_type]} " \
+                                 "#{attrs[:subject_id]} (#{holder&.workflow_id})", workflow: holder && klass.new(holder))
+      end
+
+      def existing_run(klass, attrs, required: true)
+        scope = WorkflowEntry.where(workflow_class: klass.name, idempotency_key: attrs[:idempotency_key])
+        required ? scope.take! : scope.take
+      end
+
+      # --- outside verbs ------------------------------------------------
+
+      # pause!, cancel!, resume!, resume_at!, run_now!, reschedule! on a run.
+      # Returns the updated row; raises the States table's error when the
+      # verb is not legal in the run's state.
+      def apply(workflow, verb, actor:, reason: nil, **options)
+        locked(workflow.workflow_id) do |record, notes|
+          raise ActiveRecord::RecordNotFound, "workflow #{workflow.workflow_id} is gone" unless record
+
+          States.check!(verb, record.status)
+          OutsideVerbs.public_send(verb, record, notes, actor: actor, reason: reason, **options)
+          record
+        end
+      end
+
+      # --- shared helpers -----------------------------------------------
+
+      # Runs the block in a transaction with the run's row locked (nil when
+      # the run is gone), and sends what the block noted once it commits.
+      #
+      # The notes are enrolled inside the transition's own transaction, the
+      # way a saved model is: they go out when that transaction's work really
+      # commits, whether it is a top-level transaction, part of an app's
+      # joinable one, or a savepoint inside a non-joinable one (Rails'
+      # transactional tests), and never on a rollback.
+      def locked(workflow_id)
+        notes = Notes.new
+        WorkflowEntry.transaction do
+          result = yield WorkflowEntry.lock_for(workflow_id), notes
+          notes.flush_after_commit(WorkflowEntry.connection)
+          result
+        end
+      end
+
+      # The guarded UPDATE for +verb+: WHERE status IN (States.from(verb)).
+      # Under the row lock it cannot lose once the caller checked the state;
+      # 0 rows raises rather than letting a transition pass silently.
+      def transition!(record, verb, **attrs)
+        to = States.to(verb)
+        updated = WorkflowEntry.transition!(record.workflow_id, from: States.from(verb), to: to, **attrs)
+        raise InvalidTransition, "#{verb} found workflow #{record.workflow_id} outside #{States.from(verb).join("/")}" if updated.zero?
+
+        record.assign_attributes(attrs.merge(status: to))
+        to
+      end
+
+      def event!(record, event, actor:, reason: nil, step: nil, details: {})
+        WorkflowEvent.record!(workflow_id: record.workflow_id, event: event, actor: actor, reason: reason, step: step,
+                              details: details)
+      end
+
+      # A new attempt row of +step_name+ (its after-commit callback sends the
+      # StepJob), with its step_scheduled event. A job_options wait:/wait_until:
+      # (class or step) is folded into scheduled_at here, once, so the sweep
+      # does not take a deliberately delayed step for a lost one and
+      # run_now!/reschedule! move the one time that counts.
+      def schedule!(record, step_name, at:, actor:) # rubocop:disable Naming/MethodParameterName
+        at = job_delay_floor(record, step_name, at)
+        step = WorkflowStep.insert_next!(workflow_id: record.workflow_id, workflow_class: record.workflow_class,
+                                         step_name: step_name, scheduled_at: at)
+        event!(record, "step_scheduled", actor: actor, step: step, details: { scheduled_at: at.utc.iso8601(3) })
+        step
+      end
+
+      def job_delay_floor(record, step_name, at) # rubocop:disable Naming/MethodParameterName
+        options = record.workflow_klass&.step_job_options_for(step_name) || {}
+        [at, options[:wait] && (Time.current + options[:wait]), options[:wait_until]].compact.max
+      end
+
+      # "hostname:pid", stamped on every attempt a worker claims.
+      def worker_tag = "#{Socket.gethostname}:#{::Process.pid}"
+
+      def payload_for(record, **extra)
+        { workflow_class: record.workflow_class, workflow_id: record.workflow_id }.merge(extra)
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/signal_matcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # Which signal a `wait_for:` step takes:
+    #
+    #   step :capture, wait_for: :payment_confirmed do ... end
+    #   step :ship, wait_for: Pgbus::Workflow::SignalMatcher.new(:shipped) { |payload| payload[:region] == "eu" }
+    #   step :ship, wait_for: EuShipment.new          # any object answering matches?(signal)
+    #
+    # A matcher runs under the workflow row lock (when the step reaches its
+    # gate, and when signal! looks for a waiting step), so it must be fast
+    # and free of side effects. It gets a Pgbus::WorkflowSignal whose
+    # +payload+ has indifferent access.
+    class SignalMatcher
+      attr_reader :signal_name, :condition
+
+      # A name becomes a matcher; a matcher, or anything answering matches?,
+      # is kept as it is.
+      def self.coerce(value)
+        return value if value.respond_to?(:matches?)
+        return new(value) if (value.is_a?(Symbol) || value.is_a?(String)) && !value.to_s.strip.empty?
+
+        raise ArgumentError, "wait_for: takes a signal name, a Pgbus::Workflow::SignalMatcher or an object " \
+                             "answering matches?(signal), got #{value.inspect}"
+      end
+
+      # What the step row's wait_for column shows: the signal name, else the
+      # matcher's class.
+      def self.label(matcher)
+        return matcher.signal_name.to_s if matcher.respond_to?(:signal_name) && matcher.signal_name
+
+        matcher.class.name.to_s
+      end
+
+      def initialize(name, &condition)
+        raise ArgumentError, "a SignalMatcher needs a signal name, got #{name.inspect}" if name.to_s.strip.empty?
+
+        @signal_name = -name.to_s.strip
+        @condition = condition
+        freeze
+      end
+
+      def matches?(signal)
+        return false unless signal.name.to_s.strip == signal_name
+
+        condition.nil? || (condition.call(signal.payload) ? true : false)
+      end
+
+      def to_s = signal_name
+    end
+  end
+end

data/lib/pgbus/workflow/signals.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # Signals (issue #541): what a wait_for: step waits for.
+    #
+    # deliver (signal!) stores the signal under the run's row lock and, when
+    # the run's current step is waiting for a signal it matches, claims it
+    # for that step and wakes it. Otherwise it stays pending (buffered).
+    #
+    # gate runs in the StepJob after the claim and the guards, under the same
+    # lock: a signal this step already holds (woken by signal!, or claimed by
+    # an earlier attempt that reattempted or paused on a failure), else the
+    # oldest pending one its matcher takes, else the step parks as waiting.
+    #
+    # A claimed signal is consumed when its step ends, except when that
+    # attempt reattempts or fails into a pause: the next attempt runs with it.
+    module Signals
+      module_function
+
+      # Returns [record, signal]. A redelivery with a stored idempotency key
+      # returns the stored signal (duplicate_delivery? true) and does nothing
+      # else. A blank key is no key: "" would otherwise dedup every signal
+      # sent with it against the first.
+      def deliver(workflow_id, name, payload:, idempotency_key:, actor:, reason: nil)
+        name = signal_name!(name)
+        serialized = Payload.dump(payload || {}, what: "payload of signal #{name}")
+        key = idempotency_key.to_s.presence
+        Runner.locked(workflow_id) do |record, notes|
+          raise ActiveRecord::RecordNotFound, "workflow #{workflow_id} is gone" unless record
+
+          States.check!(:signal, record.status)
+          signal = WorkflowSignal.insert_signal!(workflow_id: workflow_id, name: name, payload: serialized, idempotency_key: key)
+          signal ||= duplicate(record, key)
+          received!(record, signal, actor: actor, reason: reason, notes: notes)
+          [record, signal]
+        end
+      end
+
+      # The gate of a wait_for: step. True when the body runs (with a signal,
+      # or timed out), false when the step parked. Sets received_signal and
+      # timed_out? on +workflow+.
+      def gate(record, step, definition, workflow, now: Time.current)
+        if timed_out?(step, now)
+          workflow.send(:enter_wait, signal: nil, timed_out: true)
+          return true
+        end
+
+        signal = WorkflowSignal.held_by_step(record.workflow_id, step.step_name) || match(record, definition.wait_for)
+        return park(record, step, definition, now) unless signal
+
+        claim!(record, step, signal, actor: Runner::SYSTEM_ACTOR) if signal.status == "pending"
+        step.update_columns(signal_id: signal.id) unless step.signal_id == signal.id
+        workflow.send(:enter_wait, signal: signal, timed_out: false)
+        true
+      end
+
+      # The step's attempt ended (StepOutcome.apply): consume the signal it
+      # holds, unless the next attempt runs with it.
+      def settle(step, status, column, now:)
+        return unless step.respond_to?(:signal_id) && step.signal_id
+        return if column == "reattempted" || (status == "failed" && column == "paused")
+
+        WorkflowSignal.consume!(step.signal_id, now: now)
+      end
+
+      def signal_name!(name)
+        text = name.to_s.strip
+        raise ArgumentError, "signal! needs a signal name, got #{name.inspect}" if text.empty?
+
+        -text
+      end
+
+      def duplicate(record, key)
+        WorkflowSignal.find_by!(workflow_id: record.workflow_id, idempotency_key: key).tap do |signal|
+          signal.duplicate_delivery = true
+        end
+      end
+
+      def received!(record, signal, actor:, notes:, reason: nil)
+        duplicate = signal.duplicate_delivery?
+        Runner.event!(record, "signal_received", actor: actor, reason: reason,
+                                                 details: { name: signal.name, idempotency_key: signal.idempotency_key,
+                                                            signal_id: signal.id, duplicate: duplicate }.compact)
+        woke = !duplicate && wake_waiting(record, signal, actor: actor)
+        notes.instrument("pgbus.workflow.signal",
+                         Runner.payload_for(record, name: signal.name, duplicate: duplicate, woke: woke))
+      end
+
+      def wake_waiting(record, signal, actor:) # rubocop:disable Naming/PredicateMethod -- true when it woke the step
+        step = WorkflowStep.latest_for(record.workflow_id)
+        return false unless step&.status == "waiting" && step.batch_id.nil?
+
+        definition = record.workflow_klass&.workflow_steps&.fetch(step.step_name)
+        return false unless definition&.waits_for_signal? && definition.wait_for.matches?(signal)
+
+        claim!(record, step, signal, actor: actor)
+        Waiting.wake!(record, step, now: Time.current, signal_id: signal.id)
+        true
+      end
+
+      def claim!(record, step, signal, actor:)
+        now = Time.current
+        WorkflowSignal.claim!(signal.id, step_id: step.id, now: now)
+        signal.assign_attributes(status: "claimed", claimed_by_step_id: step.id, claimed_at: now)
+        Runner.event!(record, "signal_claimed", actor: actor, step: step, details: { name: signal.name, signal_id: signal.id })
+      end
+
+      # The oldest pending signal +matcher+ takes. A SignalMatcher narrows the
+      # query to its name; any other matcher sees every pending signal.
+      def match(record, matcher)
+        name = matcher.respond_to?(:signal_name) ? matcher.signal_name : nil
+        WorkflowSignal.pending_for(record.workflow_id, name: name).find_each(batch_size: 100) do |signal|
+          return signal if matcher.matches?(signal)
+        end
+        nil
+      end
+
+      def park(record, step, definition, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
+        timeout_at = definition.wait_timeout && (now + definition.wait_timeout)
+        Waiting.park!(record, step, now: now, wait_for: definition.wait_for_name, timeout_at: timeout_at)
+        false
+      end
+
+      # This attempt waited, holds no signal, and its wait_timeout passed: the
+      # sweep woke it with on_timeout: :run.
+      def timed_out?(step, now)
+        !step.waiting_since.nil? && step.signal_id.nil? && !step.timeout_at.nil? && step.timeout_at <= now + 1
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/states.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The one transition table (issue #540). Every verb, the workflow states
+    # it is legal from, the state it moves the workflow to, and what it does
+    # to the step rows. The runner's guarded UPDATEs take their WHERE status
+    # IN (...) from here, available_actions (dashboard buttons, MCP tools)
+    # reads it, and the docs page lists it. Nothing else decides whether a
+    # transition is legal.
+    #
+    # Outside verbs are the ones a person or a program calls on a run
+    # (console, dashboard, MCP); runner verbs are the StepJob's and the
+    # sweep's own moves, never offered as actions.
+    module States
+      WORKFLOW = %w[ready performing waiting paused finished cancelled].freeze
+      ONGOING = %w[ready performing waiting paused].freeze
+      TERMINAL = %w[finished cancelled].freeze
+      STEP = %w[scheduled waiting in_progress completed failed cancelled skipped].freeze
+      OPEN_STEP = %w[scheduled waiting in_progress].freeze
+
+      # Why an ongoing run needs a person (the sweep's gauge, and the
+      # dashboard's needs-attention view later).
+      STUCK_REASONS = %w[paused_error stalled paused_manual overdue waiting_overdue].freeze
+
+      Transition = Data.define(:verb, :from, :to, :outside, :error, :effect)
+
+      TRANSITIONS = Ractor.make_shareable(
+        [
+          # Outside verbs
+          Transition.new(verb: :pause, from: %w[ready performing waiting], to: "paused", outside: true,
+                         error: :InvalidTransition,
+                         effect: "a running step finishes and records its outcome; nothing new is claimed"),
+          Transition.new(verb: :resume, from: %w[paused], to: "ready", outside: true, error: :NotPaused,
+                         effect: "a failed step runs again as a new attempt; a completed or skipped one is " \
+                                 "followed by the next step; a scheduled one is sent again; a waiting one waits again"),
+          Transition.new(verb: :resume_at, from: %w[paused], to: "ready", outside: true, error: :NotPaused,
+                         effect: "the named step runs as a new attempt"),
+          Transition.new(verb: :cancel, from: ONGOING, to: "cancelled", outside: true, error: :InvalidTransition,
+                         effect: "scheduled and in_progress steps are cancelled; a running step's outcome is ignored"),
+          Transition.new(verb: :run_now, from: %w[ready], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the scheduled step's wait is cut short and it is sent now"),
+          Transition.new(verb: :reschedule, from: %w[ready], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the scheduled step moves to the given time"),
+          Transition.new(verb: :rerun, from: TERMINAL, to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "a new run starts with the same subject and arguments"),
+          Transition.new(verb: :skip, from: %w[waiting], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the waiting step is skipped (a signal it holds is consumed) and the next step is " \
+                                 "scheduled, or the run finishes after the last"),
+          # signal leaves the state alone unless it wakes a waiting step (wake).
+          Transition.new(verb: :signal, from: ONGOING, to: nil, outside: true, error: :NotOngoing,
+                         effect: "the signal is stored; a waiting step it matches is scheduled again, otherwise it " \
+                                 "stays pending until a step claims it"),
+          # Runner verbs
+          Transition.new(verb: :claim, from: %w[ready], to: "performing", outside: false, error: :InvalidTransition,
+                         effect: "the scheduled step moves to in_progress"),
+          Transition.new(verb: :advance, from: %w[performing], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "the step is completed or skipped and the next step is scheduled"),
+          Transition.new(verb: :finish, from: %w[performing paused], to: "finished", outside: false,
+                         error: :InvalidTransition, effect: "the last step (or one that called finished!) completed"),
+          Transition.new(verb: :reattempt, from: %w[performing], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "the step failed and its next attempt is scheduled"),
+          Transition.new(verb: :step_pause, from: %w[performing], to: "paused", outside: false,
+                         error: :InvalidTransition,
+                         effect: "the step completed after pause!, or failed (an exception or a stall)"),
+          Transition.new(verb: :step_cancel, from: %w[performing paused], to: "cancelled", outside: false,
+                         error: :InvalidTransition, effect: "the step called cancel!, or cancel_if or a policy cancelled it"),
+          Transition.new(verb: :unpause, from: %w[paused], to: "performing", outside: false, error: :NotPaused,
+                         effect: "resume! while the step that was running at the outside pause! is still running: " \
+                                 "the run goes on performing it"),
+          Transition.new(verb: :hold, from: %w[paused], to: "paused", outside: false, error: :InvalidTransition,
+                         effect: "an outcome that arrived after an outside pause!: recorded on the step; a " \
+                                 "completed, skipped or reattempted step has its next row scheduled; the workflow " \
+                                 "stays paused"),
+          Transition.new(verb: :park, from: %w[performing], to: "waiting", outside: false, error: :InvalidTransition,
+                         effect: "the step waits for a matching signal or for its fan-out batch; nothing is sent " \
+                                 "until it is woken"),
+          Transition.new(verb: :wake, from: %w[waiting], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "a matching signal arrived, or the wait timed out with on_timeout: :run: the " \
+                                 "waiting step is scheduled again"),
+          Transition.new(verb: :resolve, from: %w[waiting], to: "performing", outside: false,
+                         error: :InvalidTransition,
+                         effect: "the fan-out batch finished, the wait timed out, or an operator skipped the step: " \
+                                 "its outcome is applied as for a finished attempt"),
+          Transition.new(verb: :rewait, from: %w[paused], to: "waiting", outside: false, error: :NotPaused,
+                         effect: "resume! on a run paused while its step was waiting: it waits again")
+        ].to_h { |transition| [transition.verb, transition] }
+      )
+
+      module_function
+
+      def fetch(verb)
+        TRANSITIONS.fetch(verb.to_sym) { raise ArgumentError, "unknown workflow verb #{verb.inspect}" }
+      end
+
+      def from(verb) = fetch(verb).from
+
+      def to(verb) = fetch(verb).to
+
+      def legal?(verb, status) = from(verb).include?(status.to_s)
+
+      # Returns the target state, or raises the verb's documented error.
+      def check!(verb, status)
+        transition = fetch(verb)
+        return transition.to if transition.from.include?(status.to_s)
+
+        raise Workflow.const_get(transition.error),
+              "cannot #{verb.to_s.tr("_", " ")} a #{status} workflow (allowed from: #{transition.from.join(", ")})"
+      end
+
+      # The outside verbs legal in +status+: the dashboard's buttons and the
+      # MCP write tools.
+      def available_actions(status)
+        state = status.to_s
+        TRANSITIONS.each_value.select { |transition| transition.outside && transition.from.include?(state) }.map(&:verb)
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/step_context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The workflow step running in this fiber, while its body runs:
+    #
+    #   Pgbus::Workflow::StepContext.workflow_id   # => "6f1c…" (nil outside a step)
+    #   Rails.logger.tagged("wf=#{Pgbus::Workflow::StepContext.workflow_id}") { ... }
+    #
+    # Not named Current: every constant under Pgbus::Workflow is visible from
+    # a workflow subclass's step bodies, and a bare `Current` there must stay
+    # the app's ActiveSupport::CurrentAttributes.
+    #
+    # Fiber-local (Thread.current[] is per fiber), saved and restored around
+    # each step so a nested or concurrent step never sees another's context.
+    # Pgbus's own log lines inside a step carry workflow=… step=… attempt=…
+    # through Pgbus::LogFormatter's context.
+    module StepContext
+      KEY = :pgbus_workflow_step_context
+
+      # The running step, as the fiber-local value.
+      Frame = Data.define(:workflow_id, :workflow_class, :step_name, :attempt)
+
+      # Which attempt a workflow instance is running its body for. Set by the
+      # StepJob on the fresh instance it runs the body on, never by app code.
+      Attempt = Data.define(:step_id, :step_name, :attempt)
+
+      module_function
+
+      def with(workflow_id:, workflow_class:, step_name:, attempt:, &)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = Frame.new(workflow_id: workflow_id, workflow_class: workflow_class,
+                                        step_name: step_name, attempt: attempt)
+        LogFormatter.with_context(workflow: workflow_id, step: step_name, attempt: attempt, &)
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      def context = Thread.current[KEY]
+
+      def workflow_id = context&.workflow_id
+
+      def workflow_class = context&.workflow_class
+
+      def step_name = context&.step_name
+
+      def attempt = context&.attempt
+
+      # "workflow=… step=… attempt=…" for a log line, or "" outside a step.
+      def log_tag
+        current = context
+        return "" unless current
+
+        "workflow=#{current.workflow_id} step=#{current.step_name} attempt=#{current.attempt}"
+      end
+    end
+  end
+end