pgbus 0.19.3 → 0.20.0

data/lib/pgbus/web/data_source/workflow_actions.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The Workflows dashboard's actions (issue #542). Each goes through the
+      # run's own outside verb (Pgbus::Workflow#resume! and friends), so the
+      # States table and the row lock decide, and returns the real outcome:
+      #
+      #   { ok: true }                                      it happened
+      #   { ok: false, code:, reason:, status: }            it did not, and why
+      #
+      # code is :not_allowed (the run is no longer in a state that allows it,
+      # usually a lost race: status says where it is now), :not_found,
+      # :invalid (an unknown step, a payload over the size cap) or :failed
+      # (anything else: logged). actor is who it is recorded as on the run's
+      # audit trail; reason is the operator's note.
+      module WorkflowActions
+        # At most this many runs per bulk call; a bigger group takes another press.
+        BULK_CAP = 500
+        # The outcomes a bulk call counts as "had already moved on".
+        MOVED_ON = %i[not_allowed not_found].freeze
+
+        def resume_workflow(workflow_id, actor:, reason: nil)
+          workflow_action(workflow_id) { |wf| wf.resume!(actor: actor, reason: reason) }
+        end
+
+        def cancel_workflow(workflow_id, actor:, reason: nil)
+          workflow_action(workflow_id) { |wf| wf.cancel!(actor: actor, reason: reason) }
+        end
+
+        def skip_workflow_step(workflow_id, actor:, reason: nil)
+          workflow_action(workflow_id) { |wf| wf.skip!(actor: actor, reason: reason) }
+        end
+
+        def resume_workflow_at(workflow_id, step:, actor:, reason: nil)
+          workflow_action(workflow_id) { |wf| wf.resume_at!(step, actor: actor, reason: reason) }
+        end
+
+        def run_workflow_step_now(workflow_id, actor:, reason: nil)
+          workflow_action(workflow_id) { |wf| wf.run_now!(actor: actor, reason: reason) }
+        end
+
+        # A redelivery with the same idempotency_key stores nothing: ok, with
+        # duplicate: true. The actor and reason are on the signal_received event.
+        def signal_workflow(workflow_id, name:, payload:, idempotency_key:, actor:, reason: nil)
+          duplicate = false
+          result = workflow_action(workflow_id) do |wf|
+            signal = wf.signal!(name, payload: payload, idempotency_key: idempotency_key, actor: actor, reason: reason)
+            duplicate = signal.duplicate_delivery?
+          end
+          result[:ok] ? result.merge(duplicate: duplicate) : result
+        end
+
+        # The new run's workflow_id on success.
+        def rerun_workflow(workflow_id, actor:, reason: nil)
+          rerun = nil
+          result = workflow_action(workflow_id) { |wf| rerun = wf.rerun!(actor: actor, reason: reason) }
+          result[:ok] ? result.merge(workflow_id: rerun.workflow_id) : result
+        end
+
+        # +group+ is a needs-attention group (workflow_class, step_name,
+        # reason, error_class). Each of its runs, at most BULK_CAP, through its
+        # own guarded transition: one that moved on in the meantime is
+        # skipped. { ok:, done:, skipped:, failed:, failure: }, or ok: false
+        # with a reason when the group could not be read.
+        def bulk_resume_workflows(group:, actor:, reason: nil)
+          bulk_workflow_action(group) { |id| resume_workflow(id, actor: actor, reason: reason) }
+        end
+
+        def bulk_cancel_workflows(group:, actor:, reason: nil)
+          bulk_workflow_action(group) { |id| cancel_workflow(id, actor: actor, reason: reason) }
+        end
+
+        private
+
+        def workflow_action(workflow_id)
+          workflow = Workflow.find(workflow_id)
+          return { ok: false, code: :not_found, reason: "workflow #{workflow_id} not found" } unless workflow
+
+          yield workflow
+          { ok: true }
+        rescue Workflow::InvalidTransition => e
+          { ok: false, code: :not_allowed, reason: e.message, status: WorkflowEntry.where(workflow_id: workflow_id).pick(:status) }
+        rescue ActiveRecord::RecordNotFound => e
+          { ok: false, code: :not_found, reason: e.message }
+        rescue Workflow::StepNotDefined, Workflow::PayloadTooLarge, ArgumentError => e
+          { ok: false, code: :invalid, reason: e.message }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Workflow action on #{workflow_id} failed: #{e.class}: #{e.message}" }
+          { ok: false, code: :failed, reason: "#{e.class}: #{e.message}" }
+        end
+
+        # done: changed. skipped: had moved on (no longer in a state that
+        # allows it, or gone). failed: anything else, with the first reason.
+        def bulk_workflow_action(group, &)
+          ids = WorkflowEntry.attention_ids(group, **attention_thresholds, limit: BULK_CAP)
+          outcomes = ids.map(&)
+          moved_on, failed = outcomes.reject { |outcome| outcome[:ok] }.partition { |outcome| MOVED_ON.include?(outcome[:code]) }
+          result = { ok: true, done: outcomes.size - moved_on.size - failed.size, skipped: moved_on.size, failed: failed.size }
+          failed.empty? ? result : result.merge(failure: failed.first[:reason])
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Bulk workflow action on #{group.inspect} failed: #{e.class}: #{e.message}" }
+          { ok: false, code: :failed, reason: "#{e.class}: #{e.message}", done: 0, skipped: 0, failed: 0 }
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source/workflow_insights.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The workflow insights' reads (issue #549): one row per workflow class
+      # for /pgbus/workflows/definitions, and one class's pipeline, step
+      # performance, throughput, durations, funnel and per-revision numbers
+      # for /pgbus/workflows/definitions/:workflow_class and the MCP tools.
+      # Read from the step and run rows inside a WorkflowWindow
+      # (WorkflowInsightsQueries); WorkflowInsightsReport shapes the answer.
+      #
+      # A class is the registered Pgbus::Workflow subclass of that name, or,
+      # for a name present in pgbus_workflows, its safe_constantize when that
+      # is a Pgbus::Workflow subclass. A name from a URL that is neither is
+      # never constantized: the class is unknown.
+      module WorkflowInsights
+        # A workflow class name: a constant path (OrderWorkflow,
+        # Billing::OrderWorkflow). The route constrains to the same shape.
+        CLASS_NAME = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+        def workflow_definitions(window:)
+          return [] unless Workflow::Sweep.tables_ready?
+
+          ongoing = WorkflowInsightsQueries.ongoing.group_by { |row| row[:workflow_class] }
+          ended = WorkflowInsightsQueries.ended(since: window.since, until_time: window.now).index_by { |row| row[:workflow_class] }
+          stuck = attention_by_class
+          names = (registered_workflows.keys + WorkflowInsightsQueries.class_names + ongoing.keys + ended.keys + stuck.keys)
+          names.uniq.sort.map do |name|
+            WorkflowInsightsReport.summary(name, insights_class(name), ongoing.fetch(name, []), ended[name], stuck.fetch(name, 0))
+          end
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading workflow definitions: #{e.class}: #{e.message}" }
+          []
+        end
+
+        # nil for a name that is not a constant path, that no class or run
+        # has, or when the read failed.
+        def workflow_definition(workflow_class, window:)
+          return nil unless Workflow::Sweep.tables_ready?
+
+          name = workflow_class.to_s
+          return nil unless CLASS_NAME.match?(name)
+
+          registered = registered_workflows[name]
+          return nil unless registered || WorkflowInsightsQueries.class_known?(name)
+
+          read_definition(name, registered || insights_class(name), window)
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading workflow definition #{workflow_class}: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        private
+
+        def read_definition(name, klass, window)
+          now = window.now
+          zone = Time.zone || ActiveSupport::TimeZone["UTC"]
+          since = window.since
+          queries = WorkflowInsightsQueries
+          WorkflowInsightsReport.detail(
+            name, klass,
+            window: window, since: since, now: now, ongoing: queries.ongoing(workflow_class: name),
+            ended: queries.ended(since: since, until_time: now, workflow_class: name).first,
+            attention: attention_by_class(workflow_class: name).fetch(name, 0),
+            stats: queries.step_stats(name, since: since, until_time: now),
+            histogram: queries.duration_histogram(name, since: since, until_time: now),
+            throughput: queries.throughput(name, since: since, until_time: now, bucket: window.bucket_seconds,
+                                                 zone: zone.tzinfo.identifier),
+            zone: zone,
+            reached: queries.funnel_reached(name, since: since, until_time: now),
+            stopped: queries.funnel_stopped(name, since: since, until_time: now),
+            revisions: queries.by_revision(name, since: since, until_time: now)
+          )
+        end
+
+        # { name => class } of every registered Pgbus::Workflow subclass.
+        def registered_workflows = Workflow.registered_classes.to_h { |klass| [klass.name, klass] }
+
+        # The class a run's workflow_class names, or nil when it does not
+        # load or is not a Pgbus::Workflow subclass. Only for names from the
+        # registry or the rows.
+        def insights_class(name)
+          registered_workflows.fetch(name) do
+            klass = name.safe_constantize
+            klass if klass.is_a?(Class) && klass < Workflow
+          end
+        end
+
+        # { workflow_class => runs needing a person } (stuck_reason_counts),
+        # of every class or of +workflow_class+ only.
+        def attention_by_class(workflow_class: nil)
+          counts = WorkflowEntry.stuck_reason_counts(**attention_thresholds, workflow_class: workflow_class)
+          counts.each_with_object(Hash.new(0)) { |((klass, _), runs), sums| sums[klass] += runs }
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source/workflow_list.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The Workflows pages' reads (issue #542): the list with its filters,
+      # one run's detail (attempts, signals, audit trail, what can be done to
+      # it), the needs-attention groups and the home-page counts. An install
+      # without the workflow tables (pgbus:add_workflows not run) gets empty
+      # lists and zero counts, not an error per refresh.
+      module WorkflowList
+        STATUSES = (%w[ongoing] + Workflow::States::WORKFLOW + %w[all]).freeze
+        FILTERS = %i[workflow_class step error_class subject_type subject_id workflow_id created_from created_to
+                     ended_from ended_to].freeze
+        STEP_HISTORY = 100
+        EVENT_HISTORY = 200
+        # The pause events the timeline pairs, read on their own so a long
+        # audit trail never drops a run's earliest pauses from the chart.
+        PAUSE_HISTORY = 1_000
+        SIGNAL_HISTORY = 100
+        RERUN_LINKS = 10
+        ATTENTION_GROUPS = 200
+
+        # status – one of STATUSES ("ongoing": ready, performing, waiting or
+        # paused). Filters (FILTERS) combine with AND. An unknown status or
+        # filter raises ArgumentError (the controller answers 400).
+        def workflows(status: "ongoing", page: 1, per_page: 25, **filters)
+          check_workflow_query!(status, filters)
+          return [] unless Workflow::Sweep.tables_ready?
+
+          fetch_workflows(status, filters, page, per_page)
+        end
+
+        def workflows_count(status: "ongoing", **filters)
+          check_workflow_query!(status, filters)
+          return ListCounts::EMPTY_COUNT unless Workflow::Sweep.tables_ready?
+
+          count_workflows(status, filters)
+        end
+
+        def workflow_detail(workflow_id)
+          return nil unless Workflow::Sweep.tables_ready?
+
+          record = WorkflowEntry.find_by(workflow_id: workflow_id)
+          return nil unless record
+
+          steps = WorkflowStep.where(workflow_id: workflow_id).order(id: :desc).limit(STEP_HISTORY).to_a
+          progress = batch_progress([step_attribute(steps.first, :batch_id)].compact)
+          workflow_row(record, steps.first, progress).merge(workflow_extras(record, steps))
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error fetching workflow #{workflow_id}: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        def ongoing_workflows_count = workflow_status_count(Workflow::States::ONGOING)
+
+        def paused_workflows_count = workflow_status_count("paused")
+
+        def workflow_attention_count
+          return 0 unless Workflow::Sweep.tables_ready?
+
+          WorkflowEntry.stuck_reason_counts(**attention_thresholds).values.sum
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error counting stuck workflows: #{e.class}: #{e.message}" }
+          0
+        end
+
+        # The stuck runs grouped by (class, step, reason, error class), each
+        # with the status its runs are in and the actions that status allows;
+        # with +workflow_class+, that class's groups only (issue #549).
+        def workflow_attention_groups(workflow_class: nil)
+          return [] unless Workflow::Sweep.tables_ready?
+
+          groups = WorkflowEntry.attention_groups(**attention_thresholds, limit: ATTENTION_GROUPS, workflow_class: workflow_class)
+          groups.map do |group|
+            status = WorkflowActionPlan.group_status(group[:reason])
+            group.merge(status: status, available_actions: Workflow::States.available_actions(status))
+          end
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error fetching stuck workflows: #{e.class}: #{e.message}" }
+          []
+        end
+
+        private
+
+        def check_workflow_query!(status, filters)
+          raise ArgumentError, "unknown workflow status: #{status.inspect}" unless STATUSES.include?(status.to_s)
+
+          unknown = filters.keys - FILTERS
+          raise ArgumentError, "unknown workflow filter(s): #{unknown.join(", ")}" if unknown.any?
+        end
+
+        def fetch_workflows(status, filters, page, per_page)
+          records = workflow_scope(status, filters).order(created_at: :desc, id: :desc)
+                                                   .limit(per_page).offset((page - 1) * per_page).to_a
+          latest = latest_steps(records.map(&:workflow_id))
+          waiting = latest.values.select { |step| step.status == "waiting" }
+          progress = batch_progress(waiting.filter_map { |step| step_attribute(step, :batch_id) })
+          records.map { |record| workflow_row(record, latest[record.workflow_id], progress) }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error fetching workflows: #{e.class}: #{e.message}" }
+          []
+        end
+
+        def count_workflows(status, filters)
+          rows = workflow_scope(status, filters).limit(ListCounts::COUNT_CAP + 1).count
+          ListCounts::Count.new(total: [rows, ListCounts::COUNT_CAP].min, capped: rows > ListCounts::COUNT_CAP)
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error counting workflows: #{e.class}: #{e.message}" }
+          ListCounts::EMPTY_COUNT
+        end
+
+        def workflow_scope(status, filters)
+          scope = WorkflowEntry.all
+          status = status.to_s
+          scope = scope.where(status: status == "ongoing" ? Workflow::States::ONGOING : status) unless status == "all"
+          filters = filters.compact
+          { workflow_class: :workflow_class, step: :current_step, error_class: :error_class, subject_type: :subject_type,
+            subject_id: :subject_id, workflow_id: :workflow_id }.each do |filter, column|
+            scope = scope.where(column => filters[filter]) if filters.key?(filter)
+          end
+          scope = scope.where(created_at: filters[:created_from]..) if filters[:created_from]
+          scope = scope.where(created_at: ..filters[:created_to]) if filters[:created_to]
+          ended_scope(scope, filters)
+        end
+
+        # When a finished or cancelled run ended (issue #549): what the
+        # insights' "finished / cancelled in the window" counts link to. A run
+        # ends in the UPDATE that sets its updated_at, so the updated_at bound
+        # keeps every match and lets idx_pgbus_workflows_status serve it.
+        def ended_scope(scope, filters)
+          table = WorkflowEntry.arel_table
+          ended_at = Arel::Nodes::NamedFunction.new("COALESCE", [table[:finished_at], table[:cancelled_at]])
+          if filters[:ended_from]
+            scope = scope.where(table[:updated_at].gteq(filters[:ended_from])).where(ended_at.gteq(filters[:ended_from]))
+          end
+          scope = scope.where(ended_at.lteq(filters[:ended_to])) if filters[:ended_to]
+          scope
+        end
+
+        # { workflow_id => its newest step row }, one query for the page.
+        def latest_steps(workflow_ids)
+          return {} if workflow_ids.empty?
+
+          WorkflowStep.where(workflow_id: workflow_ids).select("DISTINCT ON (workflow_id) #{WorkflowStep.table_name}.*")
+                      .order(Arel.sql("workflow_id, id DESC")).index_by(&:workflow_id)
+        end
+
+        # { batch_id => { done:, total: } } for waiting fan-out steps, one query.
+        def batch_progress(batch_ids)
+          return {} if batch_ids.empty?
+
+          BatchEntry.where(batch_id: batch_ids).to_a.to_h do |batch|
+            [batch.batch_id, { done: batch.completed_jobs.to_i + failure_job_count(batch), total: batch.total_jobs.to_i }]
+          end
+        end
+
+        def workflow_row(record, step, progress)
+          waiting = step&.status == "waiting"
+          { workflow_id: record.workflow_id, workflow_class: record.workflow_class, subject_type: record.subject_type,
+            subject_id: record.subject_id, status: record.status, current_step: record.current_step,
+            current_attempt: step&.attempt, step_status: step&.status,
+            waiting_for: (step_attribute(step, :wait_for) if waiting),
+            waiting_since: (step_attribute(step, :waiting_since) if waiting),
+            timeout_at: (step_attribute(step, :timeout_at) if waiting),
+            batch_id: step_attribute(step, :batch_id),
+            batch_progress: (progress[step_attribute(step, :batch_id)] if waiting),
+            scheduled_at: (step.scheduled_at if step&.status == "scheduled"),
+            error_class: record.error_class, error_message: record.error_message,
+            paused_at: record.paused_at, finished_at: record.finished_at, cancelled_at: record.cancelled_at,
+            rerun_of_workflow_id: record.rerun_of_workflow_id, created_at: record.created_at, updated_at: record.updated_at }
+        end
+
+        # The waiting-step columns exist only once pgbus:add_workflow_signals ran.
+        def step_attribute(step, name)
+          step.public_send(name) if step&.has_attribute?(name)
+        end
+
+        def workflow_extras(record, steps)
+          step_hashes = steps.map { |step| workflow_step_hash(step) }
+          events = WorkflowEvent.where(workflow_id: record.workflow_id).order(id: :desc).limit(EVENT_HISTORY).map do |event|
+            { id: event.id, event: event.event, actor: event.actor, reason: event.reason, step_name: event.step_name,
+              attempt: event.attempt, details: event.details, created_at: event.created_at }
+          end
+          klass = record.workflow_klass
+          resume_action, resume_step = WorkflowActionPlan.resume_plan(record, steps.first, klass)
+          now = Time.current
+          { arguments: WorkflowPayload.display(record.arguments),
+            steps: step_hashes.map { |step| step.merge(durations: WorkflowTimeline.durations(step, now: now)) },
+            signals: workflow_signals(record.workflow_id), events: events,
+            available_actions: Workflow::States.available_actions(record.status),
+            definition_outdated: record.definition_outdated?, class_loaded: !klass.nil?,
+            step_names: klass ? klass.workflow_steps.names : [], resume_action: resume_action, resume_step: resume_step,
+            signal_names: WorkflowActionPlan.signal_names(steps.first, klass), reruns: workflow_reruns(record.workflow_id),
+            timeline: WorkflowTimeline.chart(step_hashes, pause_events(record.workflow_id), status: record.status, now: now) }
+        end
+
+        def workflow_step_hash(step)
+          { id: step.id, step_name: step.step_name, attempt: step.attempt, status: step.status, outcome: step.outcome,
+            created_at: step.created_at, scheduled_at: step.scheduled_at, enqueued_at: step.enqueued_at,
+            started_at: step.started_at, finished_at: step.finished_at, job_id: step.job_id, msg_id: step.msg_id,
+            worker: step.worker, app_revision: step.app_revision, error_class: step.error_class,
+            error_message: step.error_message, error_backtrace: step.error_backtrace, error_causes: step.error_causes || [],
+            output: step.output && WorkflowPayload.display(step.output),
+            waiting_since: step_attribute(step, :waiting_since), wait_for: step_attribute(step, :wait_for),
+            timeout_at: step_attribute(step, :timeout_at), batch_id: step_attribute(step, :batch_id),
+            signal_id: step_attribute(step, :signal_id) }
+        end
+
+        def pause_events(workflow_id)
+          WorkflowEvent.where(workflow_id: workflow_id, event: WorkflowTimeline::PAUSE_EVENTS).order(:id).limit(PAUSE_HISTORY)
+                       .map { |event| { event: event.event, created_at: event.created_at } }
+        end
+
+        def workflow_signals(workflow_id)
+          return [] unless Workflow::Sweep.waiting_ready?
+
+          WorkflowSignal.where(workflow_id: workflow_id).order(id: :desc).limit(SIGNAL_HISTORY).map do |signal|
+            { id: signal.id, name: signal.name, status: signal.status, idempotency_key: signal.idempotency_key,
+              payload: WorkflowPayload.display(signal.read_attribute(:payload)), created_at: signal.created_at,
+              claimed_at: signal.claimed_at, consumed_at: signal.consumed_at }
+          end
+        end
+
+        def workflow_reruns(workflow_id)
+          WorkflowEntry.where(rerun_of_workflow_id: workflow_id).order(created_at: :desc).limit(RERUN_LINKS)
+                       .pluck(:workflow_id, :status, :created_at).map do |id, status, created_at|
+            { workflow_id: id, status: status, created_at: created_at }
+          end
+        end
+
+        def workflow_status_count(status)
+          return 0 unless Workflow::Sweep.tables_ready?
+
+          WorkflowEntry.where(status: status).count
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error counting workflows: #{e.class}: #{e.message}" }
+          0
+        end
+
+        def attention_thresholds(config: Pgbus.configuration)
+          waiting = Workflow::Sweep.waiting_ready? ? config.workflow_waiting_visibility_threshold : nil
+          { threshold: config.workflow_stall_threshold, waiting_threshold: waiting }
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/data_source.rb

@@ -13,6 +13,9 @@ module Pgbus
       include ProcessList
       include DashboardSignals
       include DeployTaskList
+      include WorkflowList
+      include WorkflowActions
+      include WorkflowInsights
 
       # pgbus_failed_events rows outside the EventBus handler queues; binds
       # handler_queue_names_literal as $1.

data/lib/pgbus/web/workflow_action_plan.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # What a Workflows dashboard action will do (issue #542), so its button
+    # can say so before anyone presses it. Which actions exist at all is
+    # Workflow::States.available_actions; this only names their effect.
+    module WorkflowActionPlan
+      # The status the runs of a needs-attention group are in.
+      GROUP_STATUS = { "stalled" => "paused", "paused_error" => "paused", "paused_manual" => "paused",
+                       "overdue" => "ready", "waiting_overdue" => "waiting" }.freeze
+
+      module_function
+
+      def group_status(reason) = GROUP_STATUS.fetch(reason.to_s)
+
+      # [action, step_name] for resume! of a paused run, as OutsideVerbs.resume
+      # decides it from the run's latest step row:
+      #   :retry    the step failed: it runs again as a new attempt
+      #   :continue the step completed or was skipped: the next step runs
+      #   :finish   …and it was the last: the run finishes
+      #   :resend   the step was scheduled when the run paused: it is sent again
+      #   :rewait   the step was waiting: it waits again
+      #   :carry_on the step was still running: the run goes on performing it
+      # [nil, nil] when the run is not paused, or its class is gone.
+      def resume_plan(record, latest, klass)
+        return [nil, nil] unless record.status == "paused" && latest
+
+        case latest.status
+        when "failed" then [:retry, latest.step_name]
+        when "scheduled" then [:resend, latest.step_name]
+        when "waiting" then [:rewait, latest.step_name]
+        when "in_progress" then [:carry_on, latest.step_name]
+        when "completed", "skipped" then following_plan(latest, klass)
+        else [nil, nil]
+        end
+      end
+
+      def following_plan(latest, klass)
+        return [nil, nil] unless klass
+        # resume! raises StepNotDefined for a step the class no longer
+        # declares (and no removed_step covers): no plan to promise.
+        return [nil, nil] unless klass.workflow_steps.entries.any? { |entry| entry.name == latest.step_name }
+
+        following = klass.workflow_steps.next_after(latest.step_name)
+        following ? [:continue, following.name] : [:finish, nil]
+      end
+
+      # The signal names a waiting step takes, for the Send signal select:
+      # [name] for a wait_for: name or SignalMatcher, [] for a custom matcher
+      # (the form then takes free text) or a step that is not waiting on one.
+      def signal_names(latest, klass)
+        return [] unless latest&.status == "waiting" && klass
+        return [] if latest.has_attribute?(:batch_id) && latest.batch_id
+
+        matcher = klass.workflow_steps.fetch(latest.step_name)&.wait_for
+        name = matcher.respond_to?(:signal_name) ? matcher.signal_name : nil
+        name ? [name.to_s] : []
+      end
+    end
+  end
+end