pgbus 0.19.4 → 0.20.1

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,89 @@
+# 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 and :late past moments 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] }
+        return ["waiting", "waiting_signal", args] unless row[:timeout_at]
+
+        signal_deadline(row, args.merge(time: row[:timeout_at]))
+      end
+
+      # An on_timeout: :notify deadline sends a late notice and the wait goes
+      # on (issue #565); late_since is the first deadline the wait missed.
+      def signal_deadline(row, args)
+        # A deploy that changed on_timeout since the last notice: the next
+        # deadline does something else (nil: the class is not loaded here).
+        late = row[:late_since] && [nil, "notify"].include?(row[:on_timeout]&.to_s)
+        return ["waiting", "waiting_signal_late", args.merge(late: row[:late_since])] if late
+
+        ["waiting", row[:on_timeout].to_s == "notify" ? "waiting_signal_notify" : "waiting_signal_timeout", 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

data/lib/pgbus/web/workflow_timeline.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # Where a workflow run's time went (issue #542), from its step rows and
+    # audit trail. Each attempt splits into
+    #
+    #   waited   created_at → scheduled_at   the step's wait: (or a reattempt's)
+    #   queued   scheduled_at → started_at   due, not yet claimed by a worker
+    #   ran      started_at → finished_at    the body (up to now while in progress)
+    #   waiting  waiting_since → …           parked on a signal or its fan-out batch
+    #
+    # and a paused run's pauses (paused → resumed, from the events) are their
+    # own segments, so a long gap explains itself; each wait_timed_out event
+    # is a marker. The show page's step table prints durations; the
+    # range-bar chart (charts.js renderTimeline) draws chart. Pure: rows in,
+    # hashes out.
+    module WorkflowTimeline
+      OPEN = %w[scheduled waiting in_progress].freeze
+      PAUSE_ENDS = %w[resumed cancelled finished].freeze
+      PAUSE_EVENTS = (%w[paused] + PAUSE_ENDS).freeze
+      WAIT_TIMED_OUT = "wait_timed_out"
+      RAN_SERIES = { "completed" => "ran_ok", "skipped" => "ran_ok", "failed" => "ran_failed",
+                     "in_progress" => "ran_open", "waiting" => "ran_open" }.freeze
+
+      module_function
+
+      # [{ kind:, from:, to: }] in time order. +step+ is a step hash (the
+      # data source's) with Time values.
+      def segments(step, now:)
+        created, scheduled, started, since = step.values_at(:created_at, :scheduled_at, :started_at, :waiting_since)
+        ending = step[:finished_at] || (OPEN.include?(step[:status].to_s) ? now : nil)
+        pieces = if since && scheduled && since < scheduled
+                   # A signal step woken by its signal: the row was scheduled
+                   # again at the wake and claimed a second time.
+                   [[:waited, created, since], [:waiting, since, scheduled], [:queued, scheduled, started],
+                    [:ran, started, ending]]
+                 elsif since
+                   [[:waited, created, scheduled], [:queued, scheduled, started], [:ran, started, since],
+                    [:waiting, since, ending]]
+                 else
+                   [[:waited, created, scheduled], [:queued, scheduled, started || ending], [:ran, started, ending]]
+                 end
+        clip(pieces, step[:finished_at])
+      end
+
+      # { waited:, queued:, ran:, waiting: } in seconds; nil for a kind the
+      # attempt never reached.
+      def durations(step, now:)
+        totals = segments(step, now: now).group_by { |segment| segment[:kind] }
+        %i[waited queued ran waiting].to_h do |kind|
+          pieces = totals[kind]
+          [kind, pieces&.sum { |segment| (segment[:to] - segment[:from]).to_f }]
+        end
+      end
+
+      # [{ from:, to: }]: each "paused" event up to the event that ended it,
+      # oldest first; a pause still open runs to now. +events+ in any order.
+      def paused_periods(events, status:, now:)
+        periods = []
+        opened = nil
+        events.sort_by { |event| event[:created_at] }.each do |event|
+          if event[:event] == "paused"
+            opened ||= event[:created_at]
+          elsif opened && PAUSE_ENDS.include?(event[:event])
+            periods << { from: opened, to: event[:created_at] }
+            opened = nil
+          end
+        end
+        periods << { from: opened, to: now } if opened && status.to_s == "paused"
+        periods
+      end
+
+      # The chart payload: one row per attempt (oldest first), the paused
+      # periods and the wait_timed_out marks (wait_timeouts). Times are epoch milliseconds; each segment carries its
+      # series (its colour: ran is coloured by how the attempt ended) and its
+      # duration in words for the tooltip.
+      def chart(steps, events, status:, now:)
+        rows = steps.sort_by { |step| [step[:created_at], step[:attempt].to_i] }.map do |step|
+          { label: "#{step[:step_name]} ##{step[:attempt]}", status: step[:status], outcome: step[:outcome],
+            error_class: step[:error_class],
+            segments: segments(step, now: now).map { |segment| chart_segment(segment, series_for(segment[:kind], step)) } }
+        end
+        paused = paused_periods(events, status: status, now: now).map do |period|
+          chart_segment(period.merge(kind: :paused), "paused")
+        end
+        { rows: rows, paused: paused, wait_timeouts: wait_timeouts(events) }
+      end
+
+      # [{ at:, step:, action: }] per wait_timed_out event, oldest first, at
+      # the deadline it reports (when it went out, without one): the chart
+      # draws each as a line across the rows, the page lists them. An
+      # on_timeout: :notify wait has one per late notice (issue #565).
+      def wait_timeouts(events)
+        timed_out = events.select { |event| event[:event] == WAIT_TIMED_OUT }.sort_by { |event| event[:created_at] }
+        timed_out.map do |event|
+          details = event[:details].to_h
+          { at: millis(deadline(details["timeout_at"]) || event[:created_at]),
+            step: "#{event[:step_name]} ##{event[:attempt]}", action: details["action"] }
+        end
+      end
+
+      def series_for(kind, step)
+        return kind.to_s unless kind == :ran
+
+        RAN_SERIES.fetch(step[:status].to_s, "ran_cancelled")
+      end
+
+      def chart_segment(segment, series)
+        { kind: segment[:kind].to_s, series: series, from: millis(segment[:from]), to: millis(segment[:to]),
+          duration: TimeFormat.duration(segment[:to] - segment[:from]) }
+      end
+
+      def millis(time) = (time.to_f * 1000).round
+
+      def deadline(iso) = iso && Time.iso8601(iso)
+
+      # Drops a piece without both ends or of no length, and ends every piece
+      # at the attempt's finished_at (a step cancelled before its scheduled_at).
+      def clip(pieces, finished)
+        pieces.filter_map do |kind, from, to|
+          next unless from && to
+
+          to = [to, finished].min if finished
+          { kind: kind, from: from, to: to } if to > from
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/workflow_window.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "time"
+require "active_support/core_ext/time"
+
+module Pgbus
+  module Web
+    # The window the workflow insights read (issue #549): 1 h, 24 h (the
+    # default), 7 d or 30 d, never longer than config.workflow_retention
+    # (finished and cancelled runs older than that are gone, so a longer
+    # window would undercount). Each length has its chart bucket, at most 30
+    # per window: 5 min, 1 h, 6 h, 1 d; a capped window takes the bucket of
+    # the shortest choice that covers it. Anything else raises Invalid (400
+    # on the page, an error on the MCP tool).
+    class WorkflowWindow
+      class Invalid < StandardError; end
+
+      # name => [seconds, bucket seconds]
+      CHOICES = Ractor.make_shareable({ "1h" => [3_600, 300], "24h" => [86_400, 3_600], "7d" => [604_800, 21_600],
+                                        "30d" => [2_592_000, 86_400] })
+      DEFAULT = "24h"
+
+      attr_reader :name, :seconds, :bucket_seconds, :now
+
+      # +now+ is fixed here, so every read and every link of one page share
+      # one window end.
+      def self.parse(value, retention: Pgbus.configuration.workflow_retention, now: Time.current)
+        name = value.nil? || value == "" ? DEFAULT : value
+        raise Invalid, "unknown window #{value.inspect} (one of #{CHOICES.keys.join(", ")})" unless name.is_a?(String) && CHOICES.key?(name)
+
+        new(name, retention: retention, now: now)
+      end
+
+      def initialize(name, retention:, now: Time.current)
+        @name = name
+        @now = now
+        requested = CHOICES.fetch(name).first
+        @seconds = retention ? [requested, retention.to_i].min : requested
+        @capped = @seconds < requested
+        @bucket_seconds = CHOICES.values.find { |length, _| length >= @seconds }.last
+        freeze
+      end
+
+      def capped? = @capped
+
+      def since(reference = now) = reference - seconds
+
+      def to_h = { name: name, seconds: seconds, bucket_seconds: bucket_seconds, capped: capped? }
+    end
+  end
+end

data/lib/pgbus/workflow/batch_finished_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Pgbus
+  class Workflow
+    # The on_complete callback of a fan_out step's batch (issue #541):
+    # perform(step_id) resumes the run once every member finished (FanOut).
+    # Sent on the step's StepJob queue (config.workflow_queue unless the
+    # class or step says otherwise). A callback is never a member of the
+    # batch it reports on, and the StepJob it leads to is sent outside any
+    # Pgbus.batch block, so neither joins a batch.
+    class BatchFinishedJob < ::ActiveJob::Base
+      queue_as { Pgbus.configuration.workflow_queue }
+
+      def perform(step_id)
+        FanOut.finished(step_id)
+      end
+    end
+  end
+end