pgbus 0.19.3 → 0.20.0

data/lib/pgbus/web/workflow_insights_queries.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # The SQL behind the workflow insights (issue #549): one query per block
+    # of the page, each bounded by the window and served by an index #540
+    # created. The step stats read idx_pgbus_workflow_steps_insights
+    # (workflow_class, step_name, finished_at); the run counts read
+    # idx_pgbus_workflows_class_status (workflow_class, status, created_at),
+    # with every status listed so the created_at range applies under each;
+    # the ended runs read idx_pgbus_workflows_status (status, updated_at): a
+    # run ends in the UPDATE that sets its finished_at/cancelled_at, so
+    # updated_at >= the ended-at bound keeps every row the window wants.
+    #
+    # Status lists are the States constants, inlined; every value that comes
+    # from outside (a class name, a time, a bucket length) is a bind.
+    module WorkflowInsightsQueries
+      ALL = Workflow::States::WORKFLOW
+      ONGOING = Workflow::States::ONGOING
+      # Upper bounds (ms) of the end-to-end duration histogram: < 1 s, 10 s,
+      # 1 min, 10 min, 1 h, 6 h, 1 d, 7 d, and the open last bin.
+      DURATION_BOUNDS_MS = [1_000, 10_000, 60_000, 600_000, 3_600_000, 21_600_000, 86_400_000, 604_800_000].freeze
+      REVISIONS = 5
+
+      module_function
+
+      # Every workflow_class with a row, by a loose index scan (one probe per
+      # class) instead of a DISTINCT over every run.
+      def class_names
+        sql = <<~SQL
+          WITH RECURSIVE classes AS (
+            (SELECT workflow_class FROM #{runs} ORDER BY workflow_class LIMIT 1)
+            UNION ALL
+            SELECT (SELECT w.workflow_class FROM #{runs} w WHERE w.workflow_class > c.workflow_class
+                    ORDER BY w.workflow_class LIMIT 1)
+            FROM classes c WHERE c.workflow_class IS NOT NULL
+          )
+          SELECT workflow_class FROM classes WHERE workflow_class IS NOT NULL
+        SQL
+        select(sql, "Classes").rows.map(&:first)
+      end
+
+      def class_known?(workflow_class)
+        select("SELECT 1 FROM #{runs} WHERE workflow_class = $1 LIMIT 1", "Class Known", [workflow_class]).rows.any?
+      end
+
+      # The ongoing runs by (class, status, current step).
+      def ongoing(workflow_class: nil)
+        sql = <<~SQL
+          SELECT workflow_class, status, current_step, COUNT(*)
+          FROM #{runs}
+          WHERE status IN (#{list(ONGOING)})#{" AND workflow_class = $1" if workflow_class}
+          GROUP BY workflow_class, status, current_step
+        SQL
+        select(sql, "Ongoing", [workflow_class].compact).cast_values.map do |klass, status, step, runs|
+          { workflow_class: klass, status: status, step: step, runs: runs.to_i }
+        end
+      end
+
+      # Per class: the runs that finished or were cancelled between +since+
+      # and +until_time+, and the end-to-end percentiles (created → finished)
+      # of the finished.
+      def ended(since:, until_time:, workflow_class: nil)
+        sql = <<~SQL
+          SELECT workflow_class, COUNT(*) FILTER (WHERE status = 'finished'), COUNT(*) FILTER (WHERE status = 'cancelled'),
+                 COUNT(e2e_ms), #{percentiles("e2e_ms", 0.5, 0.95, 0.99)}
+          FROM (#{ended_runs(until_bind: "$2", class_bind: ("$3" if workflow_class))}) ended
+          GROUP BY workflow_class
+        SQL
+        select(sql, "Ended", [since, until_time, workflow_class].compact).cast_values.map do |klass, finished, cancelled, samples, *pcts|
+          { workflow_class: klass, finished: finished.to_i, cancelled: cancelled.to_i,
+            e2e_ms: percentile_hash(%i[p50 p95 p99], pcts, samples) }
+        end
+      end
+
+      # { bin => runs } of one class's finished runs over DURATION_BOUNDS_MS
+      # (bin 0 is under the first bound, the last bin is past the last one).
+      def duration_histogram(workflow_class, since:, until_time:)
+        sql = <<~SQL
+          SELECT width_bucket(e2e_ms::float8, ARRAY[#{DURATION_BOUNDS_MS.join(", ")}]::float8[]), COUNT(*)
+          FROM (#{ended_runs(until_bind: "$2", class_bind: "$3")}) ended
+          WHERE status = 'finished'
+          GROUP BY 1
+        SQL
+        select(sql, "Durations", [since, until_time, workflow_class]).rows.to_h { |bin, runs| [bin.to_i, runs.to_i] }
+      end
+
+      # { bucket start => [started, finished, cancelled] }. Buckets are
+      # multiples of +bucket+ seconds on the wall clock of +zone+ (an IANA
+      # name), so a day bucket starts at that zone's midnight on both sides
+      # of a DST change; a bucket start is that wall clock's epoch seconds
+      # (WorkflowInsightsReport.wall_epoch).
+      def throughput(workflow_class, since:, until_time:, bucket:, zone: "UTC")
+        sql = <<~SQL
+          SELECT bucket, SUM(started), SUM(finished), SUM(cancelled) FROM (
+            SELECT #{wall_bucket("created_at")} AS bucket, 1 AS started, 0 AS finished, 0 AS cancelled
+            FROM #{runs}
+            WHERE workflow_class = $2 AND status IN (#{list(ALL)}) AND created_at BETWEEN $1 AND $5
+            UNION ALL
+            SELECT #{wall_bucket("ended_at")}, 0, (status = 'finished')::int, (status = 'cancelled')::int
+            FROM (#{ended_runs(until_bind: "$5", class_bind: "$2")}) ended
+          ) buckets
+          GROUP BY bucket
+        SQL
+        select(sql, "Throughput", [since, workflow_class, bucket, zone, until_time]).rows.to_h do |start, started, finished, cancelled|
+          [start.to_i * bucket, [started.to_i, finished.to_i, cancelled.to_i]]
+        end
+      end
+
+      # The bucket number of a UTC timestamp column on the wall clock of the
+      # zone bound as $4, in buckets of $3 seconds.
+      def wall_bucket(column)
+        "FLOOR(EXTRACT(EPOCH FROM (#{column} AT TIME ZONE 'UTC' AT TIME ZONE $4)) / $3)::bigint"
+      end
+
+      # Per step: the attempts that finished between +since+ and +until_time+.
+      def step_stats(workflow_class, since:, until_time:)
+        sql = <<~SQL
+          SELECT step_name, #{stat_columns}, MIN(created_at)
+          FROM (#{attempt_rows}) attempts
+          GROUP BY step_name
+        SQL
+        select(sql, "Steps", [workflow_class, since, until_time]).cast_values.to_h do |name, *stats, first_seen_at|
+          [name, attempt_stats(stats).merge(first_seen_at: first_seen_at)]
+        end
+      end
+
+      # Per step, over the runs started between +since+ and +until_time+: how many have a row
+      # for it (reached) and its mean position in their runs (the step order
+      # of a class that no longer loads). Partitioned by the run's bigint id:
+      # sorting 50k workflow_id strings under a locale collation costs ~4x.
+      def funnel_reached(workflow_class, since:, until_time:)
+        sql = <<~SQL
+          SELECT step_name, COUNT(*), AVG(position) FROM (
+            SELECT s.step_name, RANK() OVER (PARTITION BY w.id ORDER BY MIN(s.id)) AS position
+            FROM #{runs} w JOIN #{steps} s ON s.workflow_id = w.workflow_id
+            WHERE w.workflow_class = $1 AND w.status IN (#{list(ALL)}) AND w.created_at BETWEEN $2 AND $3
+            GROUP BY w.id, s.step_name
+          ) reached
+          GROUP BY step_name
+        SQL
+        select(sql, "Funnel", [workflow_class, since, until_time]).rows.to_h do |name, reached, position|
+          [name, { reached: reached.to_i, position: position.to_f }]
+        end
+      end
+
+      # Where each run started between +since+ and +until_time+ is now:
+      # { [step, status] => runs }.
+      def funnel_stopped(workflow_class, since:, until_time:)
+        sql = <<~SQL
+          SELECT current_step, status, COUNT(*)
+          FROM #{runs}
+          WHERE workflow_class = $1 AND status IN (#{list(ALL)}) AND created_at BETWEEN $2 AND $3
+          GROUP BY current_step, status
+        SQL
+        select(sql, "Stopped", [workflow_class, since, until_time]).rows.to_h { |step, status, runs| [[step, status], runs.to_i] }
+      end
+
+      # The step stats of the REVISIONS app revisions that finished an
+      # attempt last, per (revision, step) and per revision (step nil).
+      def by_revision(workflow_class, since:, until_time:)
+        sql = <<~SQL
+          WITH revisions AS (
+            SELECT app_revision, MIN(finished_at) AS first_seen_at, MAX(finished_at) AS last_seen_at
+            FROM #{steps}
+            WHERE workflow_class = $1 AND finished_at BETWEEN $2 AND $3 AND app_revision IS NOT NULL
+            GROUP BY app_revision
+            ORDER BY last_seen_at DESC
+            LIMIT #{REVISIONS}
+          )
+          SELECT attempts.app_revision, revisions.first_seen_at, revisions.last_seen_at, attempts.step_name, #{stat_columns}
+          FROM (#{attempt_rows}) attempts
+          JOIN revisions ON revisions.app_revision = attempts.app_revision
+          GROUP BY GROUPING SETS ((attempts.app_revision, revisions.first_seen_at, revisions.last_seen_at, attempts.step_name),
+                                  (attempts.app_revision, revisions.first_seen_at, revisions.last_seen_at))
+          ORDER BY revisions.last_seen_at DESC, attempts.step_name NULLS FIRST
+        SQL
+        select(sql, "Revisions", [workflow_class, since, until_time]).cast_values.map do |revision, first_seen, last_seen, name, *stats|
+          { revision: revision, first_seen_at: first_seen, last_seen_at: last_seen, step: name, stats: attempt_stats(stats) }
+        end
+      end
+
+      # The finished and cancelled runs that ended between $1 and +until_bind+
+      # (of the class at +class_bind+): never one dated after now (a skewed
+      # clock), which the charts would not show either.
+      def ended_runs(until_bind:, class_bind: nil)
+        <<~SQL
+          SELECT workflow_class, status, COALESCE(finished_at, cancelled_at) AS ended_at,
+                 CASE WHEN status = 'finished' THEN GREATEST(EXTRACT(EPOCH FROM (finished_at - created_at)) * 1000, 0) END AS e2e_ms
+          FROM #{runs}
+          WHERE status IN ('finished', 'cancelled') AND updated_at >= $1
+            AND COALESCE(finished_at, cancelled_at) BETWEEN $1 AND #{until_bind}#{" AND workflow_class = #{class_bind}" if class_bind}
+        SQL
+      end
+
+      # The attempts of class $1 that finished between $2 and $3 (never one
+      # dated after now). run_ms: completed or
+      # failed attempts that started; pickup_ms (scheduled → started, never
+      # negative): every attempt that started.
+      def attempt_rows
+        <<~SQL
+          SELECT step_name, status, outcome, error_class, app_revision, created_at,
+                 CASE WHEN status IN ('completed', 'failed') AND started_at IS NOT NULL
+                      THEN GREATEST(EXTRACT(EPOCH FROM (finished_at - started_at)) * 1000, 0) END AS run_ms,
+                 CASE WHEN started_at IS NOT NULL
+                      THEN GREATEST(EXTRACT(EPOCH FROM (started_at - scheduled_at)) * 1000, 0) END AS pickup_ms
+          FROM #{steps}
+          WHERE workflow_class = $1 AND finished_at BETWEEN $2 AND $3
+        SQL
+      end
+
+      STAT_KEYS = %i[attempts completed failed reattempted skipped cancelled].freeze
+
+      def stat_columns
+        <<~SQL.squish
+          COUNT(*), COUNT(*) FILTER (WHERE status = 'completed'), COUNT(*) FILTER (WHERE error_class IS NOT NULL),
+          COUNT(*) FILTER (WHERE outcome = 'reattempted'), COUNT(*) FILTER (WHERE status = 'skipped'),
+          COUNT(*) FILTER (WHERE status = 'cancelled'),
+          COUNT(run_ms), #{percentiles("run_ms", 0.5, 0.95, 0.99)},
+          COUNT(pickup_ms), #{percentiles("pickup_ms", 0.5, 0.95)}
+        SQL
+      end
+
+      def attempt_stats(values)
+        counts = STAT_KEYS.zip(values.first(STAT_KEYS.size).map(&:to_i)).to_h
+        run_samples, run50, run95, run99, pickup_samples, pickup50, pickup95 = values.drop(STAT_KEYS.size)
+        counts.merge(run_ms: percentile_hash(%i[p50 p95 p99], [run50, run95, run99], run_samples),
+                     pickup_ms: percentile_hash(%i[p50 p95], [pickup50, pickup95], pickup_samples))
+      end
+
+      def percentiles(column, *fractions)
+        fractions.map { |f| "percentile_cont(#{f}) WITHIN GROUP (ORDER BY #{column})" }.join(", ")
+      end
+
+      def percentile_hash(keys, values, samples)
+        keys.zip(values.map { |v| v&.to_f&.round(1) }).to_h.merge(samples: samples.to_i)
+      end
+
+      def list(statuses) = statuses.map { |status| connection.quote(status) }.join(", ")
+
+      def runs = WorkflowEntry.quoted_table_name
+
+      def steps = WorkflowStep.quoted_table_name
+
+      def connection = WorkflowEntry.connection
+
+      def select(sql, name, binds = []) = connection.exec_query(sql, "WorkflowInsights #{name}", binds)
+    end
+  end
+end

data/lib/pgbus/web/workflow_insights_report.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # Shapes WorkflowInsightsQueries' rows into the hashes the insights pages
+    # and MCP tools read (issue #549). Pure: no I/O.
+    #
+    # Steps come in the class's declaration order (gravestones included, as
+    # kind "removed"), then any step name the rows hold that the class does
+    # not declare (declared: false). For a class that no longer loads, the
+    # names in the rows, ordered by their mean position in the runs started
+    # in the window. Live counts are keyed by the run's status (ready,
+    # performing, waiting, paused), so each links to the filtered list.
+    module WorkflowInsightsReport
+      LIVE = Workflow::States::ONGOING.map(&:to_sym).freeze
+      STOPPED = Workflow::States::WORKFLOW.map(&:to_sym).freeze
+      OUTCOMES = %i[completed failed reattempted skipped cancelled].freeze
+      # Percentiles over fewer samples than this get a "few samples" note.
+      FEW_SAMPLES = 20
+      # The real-time step that walks a window's buckets: 15 min, the finest
+      # granularity of a UTC offset change.
+      WALK = 900
+      DAY = 86_400
+
+      module_function
+
+      def summary(name, klass, ongoing_rows, ended_row, attention)
+        live = ongoing_rows.sum { |row| row[:runs] }
+        e2e = ended_row ? ended_row[:e2e_ms].slice(:p50, :p95, :samples) : { p50: nil, p95: nil, samples: 0 }
+        { workflow_class: name, loaded: !klass.nil?, ongoing: live,
+          paused: ongoing_rows.select { |row| row[:status] == "paused" }.sum { |row| row[:runs] },
+          attention: attention, finished: ended_row&.fetch(:finished) || 0, cancelled: ended_row&.fetch(:cancelled) || 0,
+          e2e_ms: e2e, removed_in_flight: removed_in_flight(klass, ongoing_rows) }
+      end
+
+      def detail(name, klass, window:, since:, now:, ongoing:, ended:, attention:, stats:, histogram:, throughput:, reached:,
+                 stopped:, revisions:, zone: nil)
+        names = step_list(klass, stats, ongoing, reached, stopped)
+        summary(name, klass, ongoing, ended, attention).merge(
+          window: window.to_h.merge(since: since), bucket_seconds: window.bucket_seconds,
+          started: stopped.values.sum, e2e_ms: ended ? ended[:e2e_ms] : empty_percentiles(%i[p50 p95 p99]),
+          steps: names.map { |entry| step(entry, stats[entry[:name]], ongoing) },
+          duration_histogram: duration_histogram(histogram),
+          throughput: throughput_buckets(throughput, since: since, now: now, bucket: window.bucket_seconds, zone: zone),
+          funnel: names.map { |entry| funnel_step(entry[:name], reached, stopped) },
+          by_revision: by_revision(revisions, names.map { |entry| entry[:name] })
+        )
+      end
+
+      # [{ name:, kind:, removed:, declared: }] in pipeline order.
+      def step_list(klass, stats, ongoing, reached, stopped)
+        seen = (stats.keys + ongoing.map { |row| row[:step] } + reached.keys + stopped.keys.map(&:first)).compact.uniq
+        declared = klass ? klass.workflow_steps.entries.map { |entry| declared_step(entry) } : []
+        extra = (seen - declared.map { |entry| entry[:name] }).sort_by do |name|
+          [reached.dig(name, :position) || Float::INFINITY, stats.dig(name, :first_seen_at)&.to_f || Float::INFINITY, name]
+        end
+        declared + extra.map { |name| { name: name, kind: nil, removed: false, declared: false } }
+      end
+
+      def declared_step(entry)
+        kind = if entry.removed? then "removed"
+               elsif entry.kind == "fan_out" then "fan_out"
+               elsif entry.waits_for_signal? then "signal"
+               else "step"
+               end
+        { name: entry.name, kind: kind, removed: entry.removed?, declared: true }
+      end
+
+      def step(entry, stats, ongoing)
+        counts = LIVE.to_h { |status| [status, 0] }
+        ongoing.each { |row| counts[row[:status].to_sym] += row[:runs] if row[:step] == entry[:name] }
+        stats ||= { attempts: 0, run_ms: empty_percentiles(%i[p50 p95 p99]), pickup_ms: empty_percentiles(%i[p50 p95]) }
+        entry.merge(counts: counts, sample_size: stats[:attempts], outcomes: OUTCOMES.to_h { |key| [key, stats[key].to_i] },
+                    rates: rates(stats), run_ms: stats[:run_ms], pickup_ms: stats[:pickup_ms])
+      end
+
+      # Shares of the attempts: failed (an error was recorded), reattempted,
+      # skipped. nil without attempts.
+      def rates(stats)
+        attempts = stats[:attempts].to_i
+        %i[failed reattempted skipped].to_h do |key|
+          [key, attempts.zero? ? nil : (stats[key].to_f / attempts).round(4)]
+        end
+      end
+
+      def empty_percentiles(keys) = keys.to_h { |key| [key, nil] }.merge(samples: 0)
+
+      # Gravestones some ongoing run still sits on: { "reminder" => 3 }.
+      def removed_in_flight(klass, ongoing_rows)
+        return {} unless klass
+
+        names = klass.workflow_steps.removed_names
+        ongoing_rows.select { |row| names.include?(row[:step]) }
+                    .each_with_object(Hash.new(0)) { |row, counts| counts[row[:step]] += row[:runs] }.to_h
+      end
+
+      def duration_histogram(histogram)
+        bounds = WorkflowInsightsQueries::DURATION_BOUNDS_MS
+        (0..bounds.size).map do |bin|
+          { from_ms: bin.zero? ? 0 : bounds[bin - 1], to_ms: bounds[bin], count: histogram.fetch(bin, 0) }
+        end
+      end
+
+      # Every bucket of the window, oldest first, empty ones as zeros. +from+
+      # and +to+ are the real times its wall-clock start and the next
+      # bucket's fall on in +zone+ (a day bucket across a DST change is 23 or
+      # 25 hours long; a fall-back hour spans two real hours).
+      def throughput_buckets(counts, since:, now:, bucket:, zone: nil)
+        zone ||= utc_zone
+        bucket_starts(since: since, now: now, bucket: bucket, zone: zone).map do |start|
+          started, finished, cancelled = counts.fetch(start, [0, 0, 0])
+          { from: from_wall(start, zone), to: from_wall(start + bucket, zone), started: started, finished: finished,
+            cancelled: cancelled }
+        end
+      end
+
+      # The wall-clock epoch seconds (in +zone+) each bucket from +since+ to
+      # +now+ starts at: what WorkflowInsightsQueries.throughput keys by.
+      # Walked in real time (steps of at most WALK seconds, finer than any DST
+      # change), so a spring-forward night has no bucket for the hour it
+      # skips and a fall-back night's repeated hour is one bucket.
+      def bucket_starts(since:, now:, bucket:, zone: nil)
+        zone ||= utc_zone
+        moments = (since.to_i..now.to_i).step([bucket, WALK].min).map { |seconds| Time.at(seconds) } << now
+        moments.map { |moment| wall_epoch(moment, zone) / bucket * bucket }.uniq.sort
+      end
+
+      # +time+'s wall clock in +zone+, as epoch seconds.
+      def wall_epoch(time, zone)
+        local = time.in_time_zone(zone)
+        local.to_i + local.utc_offset
+      end
+
+      # The real (UTC) time a bucket's wall-clock start falls on in +zone+:
+      # the first of the two in a repeated hour, or, when a DST change skips
+      # the start itself (a midnight that jumps to 01:00), the first moment
+      # of the bucket that exists.
+      def from_wall(wall, zone)
+        (0...DAY).step(WALK) do |later|
+          return zone.tzinfo.local_to_utc(Time.at(wall + later).utc, true).utc
+        rescue TZInfo::PeriodNotFound
+          next
+        end
+        Time.at(wall).utc
+      end
+
+      def utc_zone = ActiveSupport::TimeZone["UTC"]
+
+      def funnel_step(name, reached, stopped)
+        { name: name, reached: reached.dig(name, :reached) || 0,
+          stopped: STOPPED.to_h { |status| [status, stopped.fetch([name, status.to_s], 0)] } }
+      end
+
+      # One entry per revision (newest first): its totals and its steps in
+      # pipeline order.
+      def by_revision(rows, order)
+        rows.group_by { |row| row[:revision] }.map do |revision, group|
+          total = group.find { |row| row[:step].nil? }
+          steps = group.select { |row| row[:step] }.sort_by { |row| order.index(row[:step]) || order.size }
+          { revision: revision, first_seen_at: total[:first_seen_at], last_seen_at: total[:last_seen_at],
+            **revision_numbers(total[:stats]),
+            steps: steps.map { |row| { name: row[:step], **revision_numbers(row[:stats]) } } }
+        end
+      end
+
+      def revision_numbers(stats)
+        { attempts: stats[:attempts], rates: rates(stats), run_ms: stats[:run_ms].slice(:p50, :p95, :samples) }
+      end
+    end
+  end
+end

data/lib/pgbus/web/workflow_payload.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # Workflow arguments, step outputs and signal payloads as the Workflows
+    # dashboard and its MCP tools show them (issue #542). They are stored
+    # through ActiveJob::Arguments; this reads that stored form without
+    # deserializing it, so showing a run never loads its records (a GlobalID
+    # shows as its URI) and never runs a custom serializer.
+    module WorkflowPayload
+      BOOKKEEPING = %w[_aj_symbol_keys _aj_ruby2_keywords _aj_hash_with_indifferent_access].freeze
+
+      module_function
+
+      def display(value)
+        case value
+        when nil then {}
+        when Hash then display_hash(value)
+        when Array then value.map { |element| element.nil? ? nil : display(element) }
+        else value
+        end
+      end
+
+      def display_hash(hash)
+        return hash["_aj_globalid"] if hash.size == 1 && hash.key?("_aj_globalid")
+        if hash.key?("_aj_serialized")
+          # A serializer that stores one "value" shows it; one that stores
+          # several fields (a Range: begin, end, exclude_end) shows those.
+          return hash.key?("value") ? display(hash["value"]) : display_hash(hash.except("_aj_serialized"))
+        end
+
+        hash.except(*BOOKKEEPING).transform_values { |nested| nested.nil? ? nil : display(nested) }
+      end
+    end
+  end
+end

data/lib/pgbus/web/workflow_query.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/time"
+
+module Pgbus
+  module Web
+    # The Workflows list's query string (issue #542), checked: a status from
+    # DataSource::WorkflowList::STATUSES, the text filters stripped (blank
+    # ones dropped, each at most MAX_LENGTH characters) and the created-at
+    # and ended-at (issue #549: finished_at or cancelled_at) ranges parsed in
+    # Time.zone (a bare date as the start or the end of that day). Anything
+    # else raises Invalid, which the controller answers with 400. #to_param
+    # is the same query back, for links that keep it.
+    class WorkflowQuery
+      class Invalid < StandardError; end
+
+      TEXT_FILTERS = %i[workflow_class step error_class subject_type subject_id workflow_id].freeze
+      DATE_FILTERS = %i[created_from created_to ended_from ended_to].freeze
+      MAX_LENGTH = 255
+      DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
+      # A date (what <input type="date"> sends) or an ISO 8601 date and time.
+      DATE_OR_TIME = /\A\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?\z/
+
+      attr_reader :status, :filters, :raw
+
+      def initialize(params)
+        @status = (params[:status].presence || "ongoing").to_s
+        raise Invalid, "unknown status #{@status.inspect}" unless DataSource::WorkflowList::STATUSES.include?(@status)
+
+        @raw = {}
+        @filters = {}
+        TEXT_FILTERS.each { |key| text(key, params[key]) }
+        DATE_FILTERS.each { |key| date(key, params[key]) }
+      end
+
+      def filtered? = @raw.any?
+
+      # The query as URL params (status and the filters as given), merged with +extra+.
+      def to_param(**extra) = { status: status, **@raw }.merge(extra).compact
+
+      private
+
+      def text(key, value)
+        value = scalar(key, value)
+        return if value.empty?
+        raise Invalid, "#{key} is longer than #{MAX_LENGTH} characters" if value.length > MAX_LENGTH
+
+        @raw[key] = value
+        @filters[key] = value
+      end
+
+      def date(key, value)
+        value = scalar(key, value)
+        return if value.empty?
+
+        time = parse_time(value) || raise(Invalid, "#{key} #{value.inspect} is not a date")
+        time = time.end_of_day if key.end_with?("_to") && value.match?(DATE_ONLY)
+        @raw[key] = value
+        @filters[key] = time
+      end
+
+      def scalar(key, value)
+        return "" if value.nil?
+        raise Invalid, "#{key} must be a single value" unless value.is_a?(String)
+
+        value.strip
+      end
+
+      # Date.valid_date? because Time.zone.parse rolls 2026-02-30 over to March.
+      def parse_time(value)
+        return nil unless value.match?(DATE_OR_TIME) && Date.valid_date?(*value[0, 10].split("-").map(&:to_i))
+
+        Time.zone ? Time.zone.parse(value) : Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/pgbus/web/workflow_state.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # The Workflows dashboard's words for one run (issue #542): the badge
+    # (its status, or "scheduled" for a ready run whose step waits for a
+    # time still ahead) and what it is doing and what happens next, as a
+    # pgbus.workflows.next.<key>_html key and its arguments. Arguments named
+    # :step, :signal and :batch are names, :ago a past moment and :time a
+    # future one; the helper renders each. Pure.
+    module WorkflowState
+      BADGE_TONES = { "ready" => :gray, "scheduled" => :gray, "performing" => :blue, "waiting" => :yellow,
+                      "paused" => :yellow, "finished" => :green, "cancelled" => :red }.freeze
+
+      Result = Data.define(:badge, :badge_tone, :next_key, :next_args)
+
+      module_function
+
+      # row – a DataSource#workflows row. threshold – how long a due step may
+      # wait for a worker before it counts as overdue (workflow_stall_threshold).
+      def present(row, threshold:, now: Time.current)
+        badge, key, args = derive(row, threshold, now)
+        Result.new(badge: badge, badge_tone: BADGE_TONES.fetch(badge, :gray), next_key: key, next_args: args)
+      end
+
+      def derive(row, threshold, now)
+        step = row[:current_step]
+        case row[:status]
+        when "performing" then performing(row, step)
+        when "waiting" then waiting(row, step)
+        when "paused" then paused(row, step)
+        when "ready" then ready(row, step, threshold, now)
+        when "finished" then ["finished", "finished", { ago: row[:finished_at] || row[:updated_at] }]
+        when "cancelled" then ["cancelled", "cancelled", { ago: row[:cancelled_at] || row[:updated_at] }]
+        else [row[:status].to_s, "unknown", { status: row[:status].to_s }]
+        end
+      end
+
+      def performing(row, step)
+        attempt = row[:current_attempt].to_i
+        return ["performing", "performing", { step: step }] if attempt <= 1
+
+        ["performing", "performing_attempt", { step: step, attempt: attempt }]
+      end
+
+      def waiting(row, step)
+        if row[:batch_id]
+          progress = row[:batch_progress] || {}
+          return ["waiting", "waiting_batch", { batch: batch_name(row), done: progress[:done].to_i, total: progress[:total].to_i }]
+        end
+        return ["waiting", "waiting_step", { step: step }] unless row[:waiting_for]
+
+        args = { signal: row[:waiting_for], ago: row[:waiting_since] }
+        row[:timeout_at] ? ["waiting", "waiting_signal_timeout", args.merge(time: row[:timeout_at])] : ["waiting", "waiting_signal", args]
+      end
+
+      def paused(row, step)
+        return ["paused", "paused_error", { step: step, error: row[:error_class] }] if row[:error_class]
+
+        ["paused", "paused_manual", { step: step }]
+      end
+
+      def ready(row, step, threshold, now)
+        due = JobState.time(row[:scheduled_at])
+        return ["ready", "ready", { step: step }] unless due
+        return ["scheduled", "scheduled", { step: step, time: due }] if due > now
+        return ["ready", "overdue", { step: step, ago: due }] if threshold && due < now - threshold
+
+        ["ready", "due", { step: step, ago: due }]
+      end
+
+      # The fan-out batch as its description names it: "Class#step".
+      def batch_name(row) = "#{row[:workflow_class]}##{row[:current_step]}"
+    end
+  end
+end