pgbus 0.19.4 → 0.20.0

data/app/helpers/pgbus/workflows_helper.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Pgbus
+  # The Workflows pages' words (issue #542): status badges, the "what happens
+  # next" sentence, the subject link, the Resume label, the audit-trail
+  # sentence and the attention reasons. Moments go through pgbus_time; the
+  # _html keys let the <time>, <code> and links through, translate escapes
+  # every other argument.
+  module WorkflowsHelper
+    BADGE_CSS = {
+      blue: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
+      gray: "bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300",
+      yellow: "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400",
+      green: "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400",
+      red: "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400"
+    }.freeze
+
+    # The outside verbs the show page has a button for (Send signal is its
+    # own form; pause and reschedule stay in the console for now).
+    DASHBOARD_ACTIONS = %i[resume resume_at run_now skip rerun cancel].freeze
+
+    # A link inside a sentence: inline (the button helper's inline-flex would
+    # break the sentence) and underlined; WCAG 2.5.8 exempts inline targets.
+    INLINE_LINK_CSS = "font-medium underline text-indigo-700 hover:text-indigo-900 dark:text-indigo-300 dark:hover:text-indigo-200"
+
+    # Text inputs, selects and textareas on the Workflows pages.
+    INPUT_CSS = "mt-1 block w-full rounded-md border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-900 " \
+                "px-2 py-1.5 text-sm text-gray-900 dark:text-white focus:border-indigo-500 focus:ring-indigo-500"
+
+    STEP_TONES = { "scheduled" => :gray, "waiting" => :yellow, "in_progress" => :blue, "completed" => :green,
+                   "failed" => :red, "cancelled" => :gray, "skipped" => :gray }.freeze
+
+    SIGNAL_TONES = { "pending" => :yellow, "claimed" => :blue, "consumed" => :green }.freeze
+
+    # The verbs that need the run's class (its step list): resume!, resume_at!
+    # and rerun! raise StepNotDefined without it, and skip! would find no next
+    # step and finish the run.
+    CLASS_ACTIONS = %i[resume resume_at rerun skip].freeze
+
+    # The show page's buttons: available_actions it has a button for, without
+    # CLASS_ACTIONS when the run's class is not loaded here.
+    def pgbus_workflow_dashboard_actions(workflow)
+      actions = Array(workflow[:available_actions]) & DASHBOARD_ACTIONS
+      workflow[:class_loaded] == false ? actions - CLASS_ACTIONS : actions
+    end
+
+    def pgbus_workflow_state(row)
+      Web::WorkflowState.present(row, threshold: Pgbus.configuration.workflow_stall_threshold)
+    end
+
+    def pgbus_workflow_badge(result)
+      pgbus_workflow_tone_badge(t("pgbus.workflows.statuses.#{result.badge}"), result.badge_tone)
+    end
+
+    def pgbus_workflow_step_badge(status)
+      pgbus_workflow_tone_badge(t("pgbus.workflows.step_statuses.#{status}"), STEP_TONES.fetch(status.to_s, :gray))
+    end
+
+    def pgbus_workflow_signal_badge(status)
+      pgbus_workflow_tone_badge(t("pgbus.workflows.signal_statuses.#{status}"), SIGNAL_TONES.fetch(status.to_s, :gray))
+    end
+
+    def pgbus_workflow_tone_badge(label, tone)
+      tag.span(label, class: "#{ApplicationHelper::BATCH_BADGE_BASE} #{BADGE_CSS.fetch(tone)}")
+    end
+
+    # "Waiting for batch OrderWorkflow#notify_vendors (7 of 12 jobs done)."
+    def pgbus_workflow_next(row, result = pgbus_workflow_state(row))
+      args = result.next_args.to_h do |key, value|
+        case key
+        when :step, :signal then [key, tag.code(value, class: "font-mono")]
+        when :batch then [key, pgbus_workflow_batch_link(value, row[:batch_id])]
+        when :ago then [key, pgbus_time(value)]
+        when :time then [key, pgbus_time(value, clock: true)]
+        else [key, value]
+        end
+      end
+      translate("pgbus.workflows.next.#{result.next_key}_html", **args)
+    end
+
+    def pgbus_workflow_batch_link(name, batch_id)
+      label = tag.code(name, class: "font-mono")
+      batch_id ? link_to(label, pgbus.batch_path(batch_id), class: INLINE_LINK_CSS, data: { turbo_frame: "_top" }) : label
+    end
+
+    # "Order 1042", linked through config.workflow_subject_url when it gives
+    # an http(s) URL or a same-site path; plain text otherwise, and "—"
+    # for a subject-less run.
+    def pgbus_workflow_subject(row)
+      return Web::TimeFormat::NONE unless row[:subject_type]
+
+      label = "#{row[:subject_type]} #{row[:subject_id]}"
+      url = pgbus_workflow_subject_url(row[:subject_type], row[:subject_id])
+      url ? pgbus_link_to(label, url, data: { turbo_frame: "_top" }) : label
+    end
+
+    def pgbus_workflow_subject_url(type, id)
+      builder = Pgbus.configuration.workflow_subject_url
+      return nil unless builder
+
+      pgbus_workflow_safe_url(builder.call(type, id))
+    rescue StandardError => e
+      Pgbus.logger.error { "[Pgbus::Web] workflow_subject_url raised #{e.class}: #{e.message}" }
+      nil
+    end
+
+    # An absolute http(s) URL with a host, or a path on this site ("/…",
+    # never "//host" or "/\host"). Anything else (javascript:, data:, a
+    # relative path) is not linked.
+    def pgbus_workflow_safe_url(value)
+      url = value.to_s.strip
+      return nil if url.empty?
+      return url if url.start_with?("/") && !url.start_with?("//", "/\\")
+
+      uri = URI.parse(url)
+      %w[http https].include?(uri.scheme&.downcase) && uri.host.present? ? url : nil
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # The Resume button's label: what resume! will do (WorkflowActionPlan).
+    def pgbus_workflow_resume_label(workflow)
+      action = workflow[:resume_action]
+      return t("pgbus.workflows.actions.resume") unless action
+
+      t("pgbus.workflows.resume.#{action}", step: workflow[:resume_step])
+    end
+
+    # "Resumed by dashboard:alice: SMTP fixed", "Step failed by system (capture #2)".
+    def pgbus_workflow_event_sentence(event)
+      what = t("pgbus.workflows.events.#{event[:event]}", default: event[:event].to_s.humanize)
+      sentence = t("pgbus.workflows.audit.by", event: what, actor: event[:actor])
+      if event[:step_name]
+        sentence = t("pgbus.workflows.audit.with_step", sentence: sentence, step: event[:step_name], attempt: event[:attempt])
+      end
+      event[:reason].present? ? t("pgbus.workflows.audit.with_reason", sentence: sentence, reason: event[:reason]) : sentence
+    end
+
+    def pgbus_workflow_value(value)
+      value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s
+    end
+
+    # The bulk confirm: "Resume all 3 runs paused at capture on Timeout::Error?"
+    def pgbus_workflow_bulk_confirm(action, group)
+      key = group[:error_class] ? "#{action}_error" : action.to_s
+      t("pgbus.workflows.attention.confirm.#{key}", count: group[:count], step: group[:step_name], error: group[:error_class])
+    end
+
+    # The index URL with the current query, merged with +extra+ (nil drops a key).
+    def pgbus_workflows_path_with(query, **extra)
+      pgbus.workflows_path(query.to_param(**extra))
+    end
+
+    # Series names and words the timeline chart prints (charts.js renderTimeline).
+    def pgbus_workflow_chart_i18n
+      series = %w[waited queued waiting paused ran_ok ran_failed ran_open ran_cancelled]
+      { series: series.index_with { |name| t("pgbus.workflows.timeline.series.#{name}") },
+        paused_row: t("pgbus.workflows.timeline.paused_row"),
+        statuses: Workflow::States::STEP.index_with { |status| t("pgbus.workflows.step_statuses.#{status}") } }
+    end
+  end
+end

data/app/models/pgbus/workflow_entry.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  # One workflow run (pgbus_workflows). Pgbus::Workflow is the DSL and the
+  # handle; this is its row. Every status change goes through
+  # Pgbus::Workflow::Runner, as a guarded UPDATE under the row lock.
+  class WorkflowEntry < BusRecord
+    self.table_name = "pgbus_workflows"
+
+    scope :ongoing, -> { where(status: Workflow::States::ONGOING) }
+    scope :terminal, -> { where(status: Workflow::States::TERMINAL) }
+    scope :stale, ->(before:) { terminal.where(updated_at: ...before) }
+
+    # The run's row, locked FOR UPDATE for the rest of the transaction.
+    def self.lock_for(workflow_id)
+      lock.find_by(workflow_id: workflow_id)
+    end
+
+    # Single-winner status change: 1 when this call moved the row, 0 when
+    # its status was not in +from+.
+    def self.transition!(workflow_id, from:, to:, **attrs) # rubocop:disable Naming/MethodParameterName
+      where(workflow_id: workflow_id, status: from).update_all(attrs.merge(status: to, updated_at: Time.current))
+    end
+
+    # Inserts a run. With an idempotency_key a conflict on
+    # (workflow_class, idempotency_key) inserts nothing and returns false; a
+    # conflict on the one-ongoing-per-subject index raises
+    # ActiveRecord::RecordNotUnique. Raw SQL rather than
+    # insert_all(unique_by:), which resolves the index through the schema
+    # cache (issue #401).
+    def self.insert_run!(attrs) # rubocop:disable Naming/PredicateMethod
+      columns = attrs.keys
+      values = attrs.values.map { |value| value.is_a?(Hash) ? JSON.generate(value) : value }
+      placeholders = (1..columns.size).map { |i| "$#{i}" }.join(", ")
+      conflict = (" ON CONFLICT (workflow_class, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING" if attrs[:idempotency_key])
+      result = connection.exec_query(
+        "INSERT INTO #{table_name} (#{columns.join(", ")}) VALUES (#{placeholders})#{conflict} RETURNING id",
+        "WorkflowEntry Insert", values
+      )
+      result.rows.any?
+    end
+
+    # { [workflow_class, status] => count } over every run.
+    def self.status_counts
+      group(:workflow_class, :status).count
+    end
+
+    # Why ongoing runs need a person, as { [workflow_class, reason] => count }
+    # (Workflow::States::STUCK_REASONS). One query: each paused or ready run
+    # (and, with +waiting_threshold+, each waiting run) with its latest step row.
+    #   stalled       paused on a step that failed with StepStalled
+    #   paused_error  paused on a step that failed with any other error
+    #   paused_manual paused otherwise (the step called pause!, or an outside pause!)
+    #   overdue       ready, its scheduled step due more than +threshold+ ago
+    #   waiting_overdue waiting longer than +waiting_threshold+ on a step
+    #                 without a wait_timeout: (only with +waiting_threshold+,
+    #                 which needs the waiting-step columns)
+    # With +workflow_class+, that class's runs only (the workflow insights,
+    # issue #549).
+    def self.stuck_reason_counts(threshold:, now: Time.current, waiting_threshold: nil, workflow_class: nil)
+      binds = stuck_binds(threshold, now, waiting_threshold)
+      class_bind = "$#{binds.size + 1}" if workflow_class
+      sql = <<~SQL
+        SELECT stuck.workflow_class, stuck.reason, COUNT(*) AS runs
+        FROM (#{stuck_runs_sql(waiting: !waiting_threshold.nil?, class_bind: class_bind)}) stuck
+        WHERE stuck.reason IS NOT NULL
+        GROUP BY stuck.workflow_class, stuck.reason
+      SQL
+      connection.exec_query(sql, "WorkflowEntry Stuck", binds + [workflow_class].compact).rows.to_h do |klass, reason, count|
+        [[klass, reason], count.to_i]
+      end
+    end
+
+    # The dashboard's needs-attention view (issue #542): the stuck runs of
+    # stuck_reason_counts grouped by (class, step, reason, error class), the
+    # biggest group first, at most +limit+ groups. first_seen_at/last_seen_at
+    # bound when the group's runs got stuck (paused_at, the overdue step's
+    # scheduled_at, or the waiting step's waiting_since); error_message is
+    # the newest one's. With +workflow_class+, that class's groups only.
+    def self.attention_groups(threshold:, now: Time.current, waiting_threshold: nil, limit: 200, workflow_class: nil)
+      binds = stuck_binds(threshold, now, waiting_threshold)
+      class_bind = "$#{binds.size + 1}" if workflow_class
+      sql = <<~SQL
+        SELECT stuck.workflow_class, stuck.step_name, stuck.reason, stuck.error_class, COUNT(*) AS runs,
+               MIN(stuck.since) AS first_seen_at, MAX(stuck.since) AS last_seen_at,
+               (ARRAY_AGG(stuck.error_message ORDER BY stuck.since DESC NULLS LAST, stuck.id DESC))[1] AS error_message
+        FROM (#{stuck_runs_sql(waiting: !waiting_threshold.nil?, class_bind: class_bind)}) stuck
+        WHERE stuck.reason IS NOT NULL
+        GROUP BY stuck.workflow_class, stuck.step_name, stuck.reason, stuck.error_class
+        ORDER BY runs DESC, last_seen_at DESC NULLS LAST, stuck.workflow_class
+        LIMIT #{Integer(limit)}
+      SQL
+      result = connection.exec_query(sql, "WorkflowEntry Attention", binds + [workflow_class].compact)
+      result.cast_values.map do |klass, step_name, reason, error_class, count, first_seen, last_seen, message|
+        { workflow_class: klass, step_name: step_name, reason: reason, error_class: error_class, count: count.to_i,
+          first_seen_at: first_seen, last_seen_at: last_seen, error_message: message }
+      end
+    end
+
+    # The workflow_ids of one attention group (+group+: workflow_class,
+    # step_name, reason, error_class; a nil error_class matches runs without
+    # one), oldest stuck first, at most +limit+: what a bulk action walks.
+    def self.attention_ids(group, threshold:, now: Time.current, waiting_threshold: nil, limit: 500)
+      binds = stuck_binds(threshold, now, waiting_threshold)
+      first = binds.size + 1
+      sql = <<~SQL
+        SELECT stuck.workflow_id
+        FROM (#{stuck_runs_sql(waiting: !waiting_threshold.nil?)}) stuck
+        WHERE stuck.workflow_class = $#{first} AND stuck.step_name = $#{first + 1} AND stuck.reason = $#{first + 2}
+          AND stuck.error_class IS NOT DISTINCT FROM $#{first + 3}
+        ORDER BY stuck.since NULLS LAST, stuck.id
+        LIMIT #{Integer(limit)}
+      SQL
+      values = binds + group.values_at(:workflow_class, :step_name, :reason, :error_class)
+      connection.exec_query(sql, "WorkflowEntry Attention Ids", values).rows.map(&:first)
+    end
+
+    # Each paused or ready run (and, when +waiting+, each waiting run) with
+    # its latest step row and why it is stuck (NULL when it is not). Binds
+    # $1 (the overdue cutoff) and, when +waiting+, $2 (the waiting cutoff);
+    # +class_bind+ names the placeholder that narrows it to one class.
+    def self.stuck_runs_sql(waiting:, class_bind: nil)
+      <<~SQL
+        SELECT w.id, w.workflow_id, w.workflow_class, COALESCE(s.step_name, w.current_step) AS step_name,
+               s.error_class, s.error_message, stuck_reason.reason,
+               CASE
+                 WHEN stuck_reason.reason IN ('stalled', 'paused_error', 'paused_manual') THEN w.paused_at
+                 WHEN stuck_reason.reason = 'overdue' THEN s.scheduled_at
+                 #{"WHEN stuck_reason.reason = 'waiting_overdue' THEN s.waiting_since" if waiting}
+               END AS since
+        FROM #{table_name} w
+        LEFT JOIN LATERAL (
+          SELECT step_name, status, error_class, error_message, scheduled_at#{", timeout_at, waiting_since" if waiting}
+          FROM #{WorkflowStep.table_name}
+          WHERE workflow_id = w.workflow_id ORDER BY id DESC LIMIT 1
+        ) s ON TRUE
+        CROSS JOIN LATERAL (
+          SELECT CASE
+                   WHEN w.status = 'paused' AND s.status = 'failed' AND s.error_class = 'Pgbus::Workflow::StepStalled' THEN 'stalled'
+                   WHEN w.status = 'paused' AND s.status = 'failed' THEN 'paused_error'
+                   WHEN w.status = 'paused' THEN 'paused_manual'
+                   WHEN w.status = 'ready' AND s.status = 'scheduled' AND s.scheduled_at < $1 THEN 'overdue'
+                   #{"WHEN w.status = 'waiting' AND s.status = 'waiting' AND s.timeout_at IS NULL AND s.waiting_since < $2 THEN 'waiting_overdue'" if waiting}
+                 END AS reason
+        ) stuck_reason
+        WHERE w.status IN ('paused', 'ready'#{", 'waiting'" if waiting})#{" AND w.workflow_class = #{class_bind}" if class_bind}
+      SQL
+    end
+    private_class_method :stuck_runs_sql
+
+    def self.stuck_binds(threshold, now, waiting_threshold)
+      waiting_threshold.nil? ? [now - threshold] : [now - threshold, now - waiting_threshold]
+    end
+    private_class_method :stuck_binds
+
+    # The Pgbus::Workflow subclass that started this run, or nil when it no
+    # longer exists.
+    def workflow_klass
+      klass = workflow_class.safe_constantize
+      klass if klass.is_a?(Class) && klass < Workflow
+    end
+
+    # True when the run started on a different step list than its class
+    # declares now (a step added, removed or reordered since).
+    def definition_outdated?
+      klass = workflow_klass
+      klass ? klass.definition_digest != definition_digest : false
+    end
+  end
+end

data/app/models/pgbus/workflow_event.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # The audit trail (pgbus_workflow_events): one row per transition and per
+  # operator action, with who did it (actor) and why (reason). Append-only:
+  # written by Pgbus::Workflow::Runner inside the transaction of the
+  # transition it records, read-only once inserted, removed with its run.
+  #
+  # Actors: "app" (an outside verb called without actor:), "system" (the
+  # StepJob, the sweep, crash detection), or what the caller passes
+  # ("dashboard:<name>", "mcp", "alice", ...).
+  class WorkflowEvent < BusRecord
+    self.table_name = "pgbus_workflow_events"
+
+    REASON_LIMIT = 1_000
+    DETAIL_LIMIT = 1_000
+
+    EVENTS = %w[
+      started step_scheduled step_started step_completed step_failed step_skipped step_reattempted
+      paused resumed cancelled finished run_now rescheduled rerun stall_detected late_completion_ignored
+      signal_received signal_claimed step_waiting wait_timed_out fan_out_opened fan_out_finished
+    ].freeze
+
+    def self.record!(workflow_id:, event:, actor:, reason: nil, step: nil, details: {})
+      create!(
+        workflow_id: workflow_id, event: event.to_s, actor: actor.to_s,
+        reason: reason && Workflow::ErrorCapture.truncate(reason.to_s, REASON_LIMIT),
+        step_id: step&.id, step_name: step&.step_name, attempt: step&.attempt,
+        details: cap(details), created_at: Time.current
+      )
+    end
+
+    # String values in details are capped, so one large error message cannot
+    # bloat the trail.
+    def self.cap(details)
+      details.to_h do |key, value|
+        [key.to_s, value.is_a?(String) ? Workflow::ErrorCapture.truncate(value, DETAIL_LIMIT) : value]
+      end
+    end
+
+    def readonly? = persisted? || super
+  end
+end

data/app/models/pgbus/workflow_signal.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  # One signal delivered to a workflow run (pgbus_workflow_signals, issue
+  # #541): pending (buffered, no step has taken it), claimed (a wait_for:
+  # step took it and runs with it as received_signal) and consumed (that
+  # step ended). Written only by Pgbus::Workflow::Signals under the run's row
+  # lock.
+  #
+  # +payload+ reads back the signal! payload with indifferent access
+  # (through ActiveJob::Arguments, as workflow arguments do).
+  class WorkflowSignal < BusRecord
+    self.table_name = "pgbus_workflow_signals"
+
+    STATUSES = %w[pending claimed consumed].freeze
+
+    # Inserts a signal. A second signal with the same (workflow_id,
+    # idempotency_key) inserts nothing and returns nil. Raw SQL rather than
+    # insert_all(unique_by:), which resolves the index through the schema
+    # cache (issue #401), as WorkflowEntry.insert_run! does.
+    def self.insert_signal!(workflow_id:, name:, payload:, idempotency_key:, now: Time.current)
+      sql = <<~SQL
+        INSERT INTO #{table_name} (workflow_id, name, payload, idempotency_key, status, created_at)
+        VALUES ($1, $2, $3, $4, 'pending', $5)
+        ON CONFLICT (workflow_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
+        RETURNING id
+      SQL
+      result = connection.exec_query(sql, "WorkflowSignal Insert",
+                                     [workflow_id, name, JSON.generate(payload), idempotency_key, now])
+      id = result.rows.first&.first
+      id && find(id)
+    end
+
+    # The pending signals of a run (only +name+'s when given); iterate them
+    # oldest first with find_each, which batches by id.
+    def self.pending_for(workflow_id, name: nil)
+      scope = where(workflow_id: workflow_id, status: "pending")
+      name ? scope.where(name: name.to_s) : scope
+    end
+
+    # The signal an earlier attempt of +step_name+ claimed and did not
+    # consume (a reattempt, or a resume! after a failure, runs with it).
+    def self.held_by_step(workflow_id, step_name)
+      attempts = WorkflowStep.where(workflow_id: workflow_id, step_name: step_name.to_s).select(:id)
+      where(workflow_id: workflow_id, status: "claimed", claimed_by_step_id: attempts).order(:id).first
+    end
+
+    # pending → claimed, by +step_id+. Returns the number of rows moved.
+    def self.claim!(id, step_id:, now: Time.current)
+      where(id: id, status: "pending").update_all(status: "claimed", claimed_by_step_id: step_id, claimed_at: now)
+    end
+
+    # claimed → consumed. Returns the number of rows moved.
+    def self.consume!(id, now: Time.current)
+      where(id: id, status: "claimed").update_all(status: "consumed", consumed_at: now)
+    end
+
+    attr_writer :duplicate_delivery
+
+    # True on what signal! returned for a redelivery: a signal with the same
+    # idempotency key was already stored, and nothing else happened.
+    def duplicate_delivery? = @duplicate_delivery == true
+
+    def payload
+      return @payload if defined?(@payload)
+
+      @payload = Workflow::Payload.load(super) || {}.with_indifferent_access
+    end
+
+    def reload(...)
+      remove_instance_variable(:@payload) if defined?(@payload)
+      super
+    end
+  end
+end

data/app/models/pgbus/workflow_step.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Pgbus
+  # One step attempt (pgbus_workflow_steps). The unique (workflow_id,
+  # step_name, attempt) index makes a duplicate attempt impossible, and the
+  # guarded claim (scheduled → in_progress) makes a duplicate StepJob a no-op.
+  #
+  # The after-commit callback below is the ONLY place a
+  # Pgbus::Workflow::StepJob is enqueued: start!, an advance, a reattempt,
+  # resume!, run_now!, and the sweep all write a row (a new scheduled row, or
+  # a bumped enqueued_at) and let it fire once the write is visible, even
+  # inside an application transaction.
+  class WorkflowStep < BusRecord
+    self.table_name = "pgbus_workflow_steps"
+
+    after_save_commit :enqueue_step_job, if: :needs_enqueue?
+
+    # Inserts the next attempt of +step_name+: one more than the highest
+    # attempt so far (1 for a step that never ran).
+    def self.insert_next!(workflow_id:, workflow_class:, step_name:, scheduled_at:)
+      attempt = where(workflow_id: workflow_id, step_name: step_name).maximum(:attempt).to_i + 1
+      create!(workflow_id: workflow_id, workflow_class: workflow_class, step_name: step_name, attempt: attempt,
+              status: "scheduled", scheduled_at: scheduled_at, created_at: Time.current)
+    end
+
+    # scheduled → in_progress, only once the row is due (a second of slack
+    # for clock skew between the sender and this worker). A message that
+    # arrives early (left behind by reschedule! to a later time) claims
+    # nothing; the later send does. Returns the number of rows claimed.
+    def self.claim!(id, now:, stall_at:, msg_id:, worker:, app_revision:)
+      where(id: id, status: "scheduled").where(scheduled_at: ..(now + 1))
+                                        .update_all(status: "in_progress", started_at: now, stall_at: stall_at,
+                                                    msg_id: msg_id, worker: worker, app_revision: app_revision)
+    end
+
+    # Records an attempt's outcome, only while the row is still in_progress.
+    # 0 means the attempt was declared stalled (or the run cancelled) while
+    # it was still running: its outcome is not applied.
+    def self.finish!(id, **attrs)
+      where(id: id, status: "in_progress").update_all(attrs)
+    end
+
+    # in_progress → waiting: the step parks on a signal or its fan-out batch
+    # (Workflow::Waiting). Returns the number of rows moved.
+    def self.park!(id, **attrs)
+      where(id: id, status: "in_progress").update_all(attrs.merge(status: "waiting"))
+    end
+
+    # waiting → in_progress, so the outcome of a finished wait (the batch
+    # finished, the wait timed out, an operator skipped it) is applied like
+    # any attempt's. Returns the number of rows moved.
+    def self.unpark!(id)
+      where(id: id, status: "waiting").update_all(status: "in_progress")
+    end
+
+    # waiting rows of waiting runs past their timeout_at (the sweep applies
+    # their on_timeout).
+    def self.wait_expired(now: Time.current)
+      where(status: "waiting").where(timeout_at: ...now)
+                              .where(workflow_id: WorkflowEntry.where(status: "waiting").select(:workflow_id))
+    end
+
+    # The scheduled, waiting and in_progress rows of a run, cancelled (an
+    # outside cancel!, a resume_at!).
+    def self.cancel_open!(workflow_id, now: Time.current)
+      where(workflow_id: workflow_id, status: Workflow::States::OPEN_STEP)
+        .update_all(status: "cancelled", outcome: "cancelled", finished_at: now)
+    end
+
+    # The newest row of a run: the step it is on.
+    def self.latest_for(workflow_id)
+      where(workflow_id: workflow_id).order(id: :desc).first
+    end
+
+    # How many of +step_name+'s latest finished attempts in a row were
+    # reattempted (what max_reattempts counts). Any other outcome, such as a
+    # pause an operator resumed, ends the run of reattempts.
+    def self.consecutive_reattempts(workflow_id, step_name)
+      outcomes = where(workflow_id: workflow_id, step_name: step_name).where.not(outcome: nil)
+                                                                      .order(attempt: :desc).pluck(:outcome)
+      outcomes.take_while { |outcome| outcome == "reattempted" }.size
+    end
+
+    def self.completed_output(workflow_id, step_name)
+      where(workflow_id: workflow_id, step_name: step_name.to_s, status: "completed").order(attempt: :desc).pick(:output)
+    end
+
+    # { step_name => output } of each step's latest completed attempt.
+    def self.completed_outputs(workflow_id)
+      where(workflow_id: workflow_id, status: "completed").order(:attempt).pluck(:step_name, :output).to_h
+    end
+
+    # in_progress rows past their stall_at.
+    def self.stalled(now: Time.current)
+      where(status: "in_progress").where(stall_at: ...now)
+    end
+
+    # scheduled rows of ready runs, due more than +threshold+ ago and not
+    # sent within it: the sweep sends them again.
+    def self.overdue(threshold:, now: Time.current)
+      cutoff = now - threshold
+      where(status: "scheduled").where(scheduled_at: ...cutoff)
+                                .where("enqueued_at IS NULL OR enqueued_at < ?", cutoff)
+                                .where(workflow_id: WorkflowEntry.where(status: "ready").select(:workflow_id))
+    end
+
+    # Fires on a new scheduled row, on a change to scheduled, and on a
+    # bumped enqueued_at; never on any other save.
+    def needs_enqueue?
+      status == "scheduled" && (previously_new_record? || saved_change_to_status? || saved_change_to_enqueued_at?)
+    end
+
+    private
+
+    # Runs after commit, so a failure cannot roll back the row: it is
+    # reported, and the sweep sends the step again once it is
+    # workflow_stall_threshold overdue.
+    def enqueue_step_job
+      job = Workflow::StepJob.set(**step_job_set_options).perform_later(id)
+      update_columns(enqueued_at: Time.current, job_id: job.job_id) if job
+    rescue StandardError => e
+      Pgbus.logger.error do
+        "[Pgbus] Workflow StepJob for step #{id} (#{step_name}) could not be enqueued: #{e.class}: #{e.message}"
+      end
+      ErrorReporter.report(e, { action: "workflow_step_enqueue", workflow_class: workflow_class,
+                                workflow_id: workflow_id, step_name: step_name, attempt: attempt })
+    end
+
+    # queue/priority from the class and the step (step wins), sent at
+    # scheduled_at (which already holds any job_options wait/wait_until, see
+    # Workflow::Runner.schedule!).
+    def step_job_set_options
+      klass = workflow_class.safe_constantize
+      options = klass.is_a?(Class) && klass < Workflow ? klass.step_job_options_for(step_name) : {}
+      set = { queue: options[:queue] || Pgbus.configuration.workflow_queue, priority: options[:priority] }
+      set[:wait_until] = scheduled_at if scheduled_at > Time.current
+      set.compact
+    end
+  end
+end

data/app/views/layouts/pgbus/application.html.erb

@@ -130,6 +130,7 @@
               <%= pgbus_nav_link t("pgbus.layout.nav.processes"), pgbus.processes_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.events"), pgbus.events_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.batches"), pgbus.batches_path %>
+              <%= pgbus_nav_link t("pgbus.layout.nav.workflows"), pgbus.workflows_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.dlq"), pgbus.dead_letter_index_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.outbox"), pgbus.outbox_index_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.locks"), pgbus.locks_path %>
@@ -191,6 +192,7 @@
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.processes"), pgbus.processes_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.events"), pgbus.events_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.batches"), pgbus.batches_path %>
+          <%= pgbus_mobile_nav_link t("pgbus.layout.nav.workflows"), pgbus.workflows_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.dlq"), pgbus.dead_letter_index_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.outbox"), pgbus.outbox_index_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.locks"), pgbus.locks_path %>

data/app/views/pgbus/dashboard/_stats_cards.html.erb

@@ -77,6 +77,23 @@
       <p class="text-xs text-gray-600 dark:text-gray-300"><%= throughput[:available] ? t("pgbus.dashboard.stats_cards.throughput_detail", minutes: throughput[:window_minutes]) : t("pgbus.dashboard.stats_cards.throughput_unavailable") %></p>
     <% end %>
 
+    <%# Two links in one card (the list and the attention view), so the card
+        is a div; its title and number link to the list. %>
+    <% workflows = @workflow_counts %>
+    <div data-testid="workflows-card" class="<%= card %>">
+      <%= link_to pgbus.workflows_path, data: { turbo_frame: "_top" }, class: "block" do %>
+        <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.dashboard.stats_cards.workflows") %></p>
+        <p class="<%= number %>"><%= number_with_delimiter(workflows[:ongoing]) %></p>
+      <% end %>
+      <p class="text-xs text-gray-600 dark:text-gray-300">
+        <%= t("pgbus.dashboard.stats_cards.workflows_detail", paused: workflows[:paused]) %>
+        <% if workflows[:attention].positive? %>
+          · <%= pgbus_link_to t("pgbus.dashboard.stats_cards.workflows_attention", count: workflows[:attention]),
+                  pgbus.attention_workflows_path, size: :sm, tone: :yellow, data: { turbo_frame: "_top" } %>
+        <% end %>
+      </p>
+    </div>
+
     <%= link_to pgbus.locks_path, data: { turbo_frame: "_top" }, class: card do %>
       <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.dashboard.stats_cards.parked_jobs") %></p>
       <p class="mt-1 text-3xl font-semibold <%= @stats[:parked_total].to_i > 0 ? 'text-amber-600 dark:text-amber-400' : 'text-gray-900 dark:text-white' %>">