pgbus 0.14.1 → 0.15.0

data/lib/pgbus/client/fair_read.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Client
+    # Fair share reads (issue #426): a weighted, work-conserving interleave
+    # across fair-share keys within one queue. Replaces `read_batch` on the
+    # worker when `config.fair_share` is set.
+    #
+    # Scheduling rule per read of `qty`: for every key that has visible
+    # messages, rank that key's visible messages 1..qty oldest-visible first
+    # (`vt, msg_id`); a message's virtual time is `rank / weight`; take the
+    # `qty` messages with the lowest `(virtual_time, msg_id)`. Weight 3 vs 1
+    # yields a 3:1 split under contention; a lone key fills the whole batch.
+    # This is batch-level weighted fair queuing — proportional within each
+    # batch, memoryless across batches (no deficit carry-over).
+    #
+    # Cost model: key enumeration is a loose index scan over
+    # (key, vt, msg_id) — one probe per key with visible work; keys whose
+    # messages are all invisible (in flight / delayed / in retry backoff) are
+    # skipped at the index level because `vt` is in the index. Per-key
+    # candidates are a bounded `LIMIT qty` index range. Roughly
+    # O(K · log n + K · qty), K = keys with visible work, independent of
+    # backlog depth. Within a key the order is `(vt, msg_id)` — FIFO for
+    # immediate enqueues; retried/delayed messages sort by when they became
+    # visible — a deliberate deviation from pgmq.read's pure msg_id order so
+    # the per-key lookup never sorts a tenant's whole visible backlog.
+    #
+    # Candidates are selected before locking (same shape as
+    # pgmq.read_grouped_rr), so under concurrent readers a batch can come back
+    # short; the worker loop re-reads immediately while it has capacity.
+    module FairRead
+      # The read expressions are written against the alias `m`; the index
+      # expression is the same shape minus the alias so the planner matches it.
+      FAIR_INDEX_KEY_EXPR = "COALESCE(message->>'#{FairShare::METADATA_KEY}', '')".freeze
+      FAIR_KEY_EXPR = "COALESCE(m.message->>'#{FairShare::METADATA_KEY}', '')".freeze
+      FAIR_WEIGHT_EXPR = "COALESCE((m.message->>'#{FairShare::WEIGHT_KEY}')::numeric, 1)".freeze
+      FAIR_INDEX_SUFFIX = "_fair_idx"
+
+      def read_batch_fair(queue_name, qty:, vt: nil)
+        full_name = fair_queue_name(queue_name)
+        guarded_read { fair_read_step(full_name, qty, vt || config.visibility_timeout) }
+      end
+
+      # Idempotent, memoized per process. Uses CREATE INDEX CONCURRENTLY so
+      # enabling fair share on an existing, populated queue never blocks
+      # enqueues. A queue table that does not exist yet is left alone (its
+      # creation path builds the index non-concurrently); any other failure is
+      # logged with the remediation and NOT memoized so the next ensure retries.
+      def ensure_fair_index(queue_name)
+        full_name = fair_queue_name(queue_name)
+        return if fair_indexes_ensured[full_name]
+
+        with_stale_connection_retry do
+          synchronized { exec_ddl(fair_index_sql(full_name, concurrently: true)) }
+        end
+        fair_indexes_ensured[full_name] = true
+      rescue StandardError => e
+        if duplicate_relation_error?(e)
+          fair_indexes_ensured[full_name] = true
+        elsif undefined_table_error?(e)
+          Pgbus.logger.debug { "[Pgbus] Fair index deferred — queue table #{full_name} not created yet" }
+        else
+          Pgbus.logger.error do
+            "[Pgbus] Could not create fair index #{fair_index_name(full_name)} on pgmq.q_#{full_name}: " \
+              "#{e.class}: #{e.message}. A failed CONCURRENTLY build leaves an INVALID index behind — " \
+              "run `DROP INDEX IF EXISTS pgmq.#{fair_index_name(full_name)}` and restart the worker to retry."
+          end
+        end
+      end
+
+      private
+
+      # One instrumented, retried, serialized, timeout-bounded fair read of a
+      # physical (already prefixed + sanitized) queue table. Not breaker-guarded
+      # itself so callers that loop over sub-queues can wrap the loop once.
+      def fair_read_step(full_name, qty, vt_seconds)
+        Instrumentation.instrument("pgbus.client.read_batch_fair", queue: full_name, qty: qty) do
+          with_stale_connection_retry do
+            synchronized { with_read_timeout { exec_fair_read(full_name, qty, vt_seconds) } }
+          end
+        end
+      end
+
+      def fair_queue_name(queue_name)
+        QueueNameValidator.sanitize!(config.queue_name(queue_name))
+      end
+
+      def fair_indexes_ensured
+        @fair_indexes_ensured ||= Concurrent::Map.new
+      end
+
+      # Runs inside create_queue_physically (caller owns the mutex) on a
+      # freshly created, empty table — plain CREATE INDEX is instant there.
+      def create_fair_index_if_needed(full_name)
+        return unless FairShare.enabled?(config)
+
+        exec_ddl(fair_index_sql(full_name, concurrently: false))
+        fair_indexes_ensured[full_name] = true
+      rescue StandardError => e
+        raise unless duplicate_relation_error?(e)
+
+        fair_indexes_ensured[full_name] = true
+      end
+
+      def exec_ddl(sql)
+        @pgmq.with_connection { |conn| conn.exec(sql) }
+      end
+
+      def exec_fair_read(full_name, qty, vt_seconds)
+        rows = @pgmq.with_connection do |conn|
+          conn.exec_params(fair_read_sql(full_name), [qty.to_i, vt_seconds.to_i]).to_a
+        end
+        rows.map { |row| PGMQ::Message.new(row) }
+      end
+
+      def fair_index_name(full_name)
+        "q_#{full_name}#{FAIR_INDEX_SUFFIX}"
+      end
+
+      def fair_index_sql(full_name, concurrently:)
+        "CREATE INDEX #{"CONCURRENTLY " if concurrently}IF NOT EXISTS #{fair_index_name(full_name)} " \
+          "ON pgmq.q_#{full_name} ((#{FAIR_INDEX_KEY_EXPR}), vt, msg_id)"
+      end
+
+      def fair_read_sql(full_name)
+        table = "pgmq.q_#{full_name}"
+        <<~SQL
+          WITH RECURSIVE fair_keys AS (
+            (SELECT #{FAIR_KEY_EXPR} AS k
+               FROM #{table} m
+              WHERE m.vt <= now()
+              ORDER BY 1 LIMIT 1)
+            UNION ALL
+            SELECT (SELECT #{FAIR_KEY_EXPR}
+                      FROM #{table} m
+                     WHERE #{FAIR_KEY_EXPR} > fk.k
+                       AND m.vt <= now()
+                     ORDER BY 1 LIMIT 1)
+              FROM fair_keys fk
+             WHERE fk.k IS NOT NULL
+          ),
+          candidates AS (
+            SELECT c.msg_id, c.rn, c.w
+              FROM fair_keys fk
+              CROSS JOIN LATERAL (
+                SELECT m.msg_id,
+                       ROW_NUMBER() OVER (ORDER BY m.vt, m.msg_id) AS rn,
+                       #{FAIR_WEIGHT_EXPR} AS w
+                  FROM #{table} m
+                 WHERE #{FAIR_KEY_EXPR} = fk.k
+                   AND m.vt <= now()
+                 ORDER BY m.vt, m.msg_id
+                 LIMIT $1
+              ) c
+             WHERE fk.k IS NOT NULL
+          ),
+          picked AS (
+            SELECT msg_id, ROW_NUMBER() OVER (ORDER BY rn / w, msg_id) AS selection_order
+              FROM candidates
+             ORDER BY rn / w, msg_id
+             LIMIT $1
+          ),
+          locked AS (
+            SELECT m.msg_id, p.selection_order
+              FROM #{table} m
+              JOIN picked p ON p.msg_id = m.msg_id
+             WHERE m.vt <= now()
+             FOR UPDATE OF m SKIP LOCKED
+          ),
+          updated AS (
+            UPDATE #{table} m
+               SET vt = clock_timestamp() + make_interval(secs => $2),
+                   read_ct = read_ct + 1,
+                   last_read_at = clock_timestamp()
+              FROM locked l
+             WHERE m.msg_id = l.msg_id
+            RETURNING m.msg_id, m.read_ct, m.enqueued_at, m.last_read_at, m.vt, m.message, m.headers,
+                      l.selection_order
+          )
+          SELECT msg_id, read_ct, enqueued_at, last_read_at, vt, message, headers
+            FROM updated
+           ORDER BY selection_order
+        SQL
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -12,6 +12,7 @@ require_relative "client/resizable_pool"
 module Pgbus
   class Client
     include ReadAfter
+    include FairRead
     include EnsureStreamQueue
     include NotifyStream
 
@@ -339,6 +340,10 @@ module Pgbus
       end
     end
 
+    def target_queue(queue_name, priority = nil)
+      @queue_strategy.target_queue(queue_name, priority)
+    end
+
     def send_message(queue_name, payload, headers: nil, delay: 0, priority: nil)
       target = @queue_strategy.target_queue(queue_name, priority)
       Instrumentation.instrument("pgbus.client.send_message", queue: target) do
@@ -381,13 +386,17 @@ module Pgbus
       msg_id
     end
 
-    def send_batch(queue_name, payloads, headers: nil, delay: 0)
-      full_name = config.queue_name(queue_name)
+    # Bulk enqueue. Routes through the queue strategy exactly like
+    # #send_message: under priority routing the bare `pgbus_<queue>` table is
+    # never created (only `_p0.._pN` are), so targeting it raised
+    # PG::UndefinedTable and no worker would have read it either.
+    def send_batch(queue_name, payloads, headers: nil, delay: 0, priority: nil)
+      target = @queue_strategy.target_queue(queue_name, priority)
       serialized, serialized_headers = serialize_batch(payloads, headers)
-      Instrumentation.instrument("pgbus.client.send_batch", queue: full_name, size: payloads.size) do
+      Instrumentation.instrument("pgbus.client.send_batch", queue: target, size: payloads.size) do
         with_stale_connection_retry do
           ensure_queue(queue_name)
-          synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
+          synchronized { @pgmq.produce_batch(target, serialized, headers: serialized_headers, delay: delay) }
         end
       end
     end
@@ -420,11 +429,17 @@ module Pgbus
       # Non-priority fast path delegates to read_batch, which is already gated
       # by the connection-health breaker — no extra guard needed here.
       unless @queue_strategy.priority?
-        return (read_batch(queue_name, qty: qty, vt: vt) || []).map do |m|
-          [config.queue_name(queue_name), m]
-        end
+        msgs = if FairShare.enabled?(config)
+                 read_batch_fair(queue_name, qty: qty, vt: vt)
+               else
+                 read_batch(queue_name, qty: qty, vt: vt)
+               end
+        return (msgs || []).map { |m| [config.queue_name(queue_name), m] }
       end
 
+      # Fair share (issue #426): strict between levels, fair within a level.
+      return read_batch_prioritized_fair(queue_name, qty: qty, vt: vt) if FairShare.enabled?(config)
+
       # The priority loop issues its own reads, so gate the whole loop: an open
       # breaker fails fast before any sub-queue is touched, and the loop as a
       # unit records one success/failure with the latch.
@@ -449,6 +464,25 @@ module Pgbus
       end
     end
 
+    # Priority sub-queues drained p0 → pN, each level read with the fair
+    # interleave. guarded_read wraps the loop as one unit (see above).
+    def read_batch_prioritized_fair(queue_name, qty:, vt: nil)
+      guarded_read do
+        remaining = qty
+        results = []
+
+        config.priority_queue_names(queue_name).each do |pq_name|
+          break if remaining <= 0
+
+          msgs = fair_read_step(QueueNameValidator.sanitize!(pq_name), remaining, vt || config.visibility_timeout)
+          msgs.each { |m| results << [pq_name, m] }
+          remaining -= msgs.size
+        end
+
+        results
+      end
+    end
+
     def read_with_poll(queue_name, qty:, vt: nil, max_poll_seconds: 5, poll_interval_ms: 100)
       full_name = config.queue_name(queue_name)
       guarded_read do
@@ -682,21 +716,55 @@ module Pgbus
     #   false — the message definitely does not exist
     #   nil   — could not determine (e.g. queue table missing or unknown error).
     #           Callers MUST treat nil as "exists" for safety.
-    def message_exists?(queue_name, msg_id: nil, uniqueness_key: nil)
-      has_msg_id = !msg_id.nil?
-      has_uniqueness_key = !uniqueness_key.nil?
-      raise ArgumentError, "pass exactly one of msg_id or uniqueness_key" unless has_msg_id ^ has_uniqueness_key
+    def message_in_queue?(queue_name, msg_id:)
+      message_exists?(queue_name, msg_id: msg_id)
+    end
+
+    # Look up a queue row by ActiveJob job_id in the JSON payload. Used by the
+    # batch sweep: move_to_dead_letter produces a new DLQ msg_id, so the
+    # source msg_id is not a DLQ identity.
+    #
+    # Same tri-state as message_exists?: true / false / nil (unknown). A
+    # logical name expands to every physical table the strategy owns (the
+    # `_pN` sub-queues under priority routing); an already-prefixed physical
+    # name probes itself only.
+    def message_with_job_id?(queue_name, job_id:)
+      tables = lookup_physical_queue_names(queue_name).map { |name| QueueNameValidator.sanitize!(name) }
+      determined = false
+
+      synchronized do
+        with_raw_connection do |conn|
+          tables.each do |sanitized|
+            present = probe_job_id_presence(conn, sanitized, job_id)
+            return true if present == true
 
+            determined = true unless present == :missing
+          end
+        end
+      end
+
+      determined ? false : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition -- tri-state: nil means unknown
+    end
+
+    # DLQ companion of a logical or already-physical queue name. Does not
+    # re-prefix a name that resolve_full_queue_name already expanded.
+    def dead_letter_physical_name(queue_name)
+      full = resolve_full_queue_name(queue_name)
+      # Priority sub-queues share the logical queue's DLQ (`pgbus_default_dlq`),
+      # not a per-priority `…_pN_dlq`. Only strip when the strategy actually
+      # creates `_pN` tables — a logical queue named `orders_p0` must keep it.
+      base = @queue_strategy.priority? ? full.sub(/_p\d+\z/, "") : full
+      "#{base}#{Pgbus::DEAD_LETTER_SUFFIX}"
+    end
+
+    # Same tri-state as message_exists?: true / false / nil (unknown).
+    def message_archived?(queue_name, msg_id:)
       full_name = resolve_full_queue_name(queue_name)
       sanitized = QueueNameValidator.sanitize!(full_name)
 
       synchronized do
         with_raw_connection do |conn|
-          if has_msg_id
-            msg_id_present?(conn, sanitized, msg_id.to_i)
-          else
-            uniqueness_key_present?(conn, sanitized, uniqueness_key)
-          end
+          msg_id_archived?(conn, sanitized, msg_id.to_i)
         end
       end
     rescue ActiveRecord::StatementInvalid => e
@@ -709,6 +777,64 @@ module Pgbus
       nil
     end
 
+    def message_exists?(queue_name, msg_id: nil, uniqueness_key: nil)
+      has_msg_id = !msg_id.nil?
+      has_uniqueness_key = !uniqueness_key.nil?
+      raise ArgumentError, "pass msg_id, uniqueness_key, or both" unless has_msg_id || has_uniqueness_key
+
+      tables = lookup_physical_queue_names(queue_name).map { |name| QueueNameValidator.sanitize!(name) }
+      determined = false
+
+      synchronized do
+        with_raw_connection do |conn|
+          tables.each do |sanitized|
+            present = probe_queue_presence(
+              conn, sanitized,
+              msg_id: has_msg_id ? msg_id.to_i : nil,
+              uniqueness_key: has_uniqueness_key ? uniqueness_key : nil
+            )
+            return true if present == true
+
+            determined = true unless present == :missing
+          end
+        end
+      end
+
+      determined ? false : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition -- tri-state: nil means unknown
+    end
+
+    # Which uniqueness keys currently appear in any live PGMQ queue payload.
+    # Used by the dispatcher reaper for unbound locks (pending / msg_id=0)
+    # so it never probes the synthetic `pending` queue (issue #418).
+    #
+    # Per-queue UndefinedTable is skipped (table dropped between listing and
+    # select). Failure to list pgmq.meta — or any non-undefined error — raises;
+    # callers must treat that as "unknown" and keep the lock.
+    def uniqueness_keys_present(lock_keys)
+      keys = Array(lock_keys).compact.map(&:to_s).uniq
+      return Set.new if keys.empty?
+
+      found = Set.new
+      synchronized do
+        with_raw_connection do |conn|
+          names = conn.exec("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+                      .map { |row| row["queue_name"] }
+          names.each do |name|
+            break if found.size == keys.size
+
+            sanitized = begin
+              QueueNameValidator.sanitize!(name)
+            rescue ArgumentError
+              next
+            end
+
+            scan_uniqueness_keys(conn, sanitized, keys, found)
+          end
+        end
+      end
+      found
+    end
+
     def purge_archive(queue_name, older_than:, batch_size: 1000)
       full_name = config.queue_name(queue_name)
       sanitized = QueueNameValidator.sanitize!(full_name)
@@ -933,9 +1059,76 @@ module Pgbus
       name.start_with?(prefix) ? name : config.queue_name(name)
     end
 
-    def msg_id_present?(conn, sanitized, msg_id)
+    # Logical names expand through QueueFactory so a priority queue's _pN
+    # tables are included; already-prefixed physical names stay as-is.
+    def lookup_physical_queue_names(queue_name)
+      name = queue_name.to_s
+      prefix = "#{config.queue_prefix}_"
+      name.start_with?(prefix) ? [name] : @queue_strategy.physical_queue_names(name)
+    end
+
+    def probe_queue_presence(conn, sanitized, msg_id:, uniqueness_key:)
+      if msg_id
+        msg_id_present?(conn, sanitized, msg_id, uniqueness_key: uniqueness_key)
+      else
+        uniqueness_key_present?(conn, sanitized, uniqueness_key)
+      end
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless undefined_table_error?(e)
+
+      :missing
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+
+      :missing
+    end
+
+    def probe_job_id_presence(conn, sanitized, job_id)
+      job_id_present?(conn, sanitized, job_id)
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless undefined_table_error?(e)
+
+      :missing
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+
+      :missing
+    end
+
+    def scan_uniqueness_keys(conn, sanitized, keys, found)
+      placeholders = keys.each_index.map { |i| "$#{i + 1}" }.join(", ")
+      result = conn.exec_params(
+        "SELECT DISTINCT message::jsonb ->> 'pgbus_uniqueness_key' AS k " \
+        "FROM pgmq.q_#{sanitized} " \
+        "WHERE message::jsonb ->> 'pgbus_uniqueness_key' IN (#{placeholders})",
+        keys
+      )
+      result.each { |row| found.add(row["k"]) if row["k"] }
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless undefined_table_error?(e)
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+    end
+
+    def msg_id_present?(conn, sanitized, msg_id, uniqueness_key: nil)
+      result = if uniqueness_key
+                 conn.exec_params(
+                   "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 " \
+                   "AND message::jsonb ->> 'pgbus_uniqueness_key' = $2 LIMIT 1",
+                   [msg_id, uniqueness_key]
+                 )
+               else
+                 conn.exec_params(
+                   "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 LIMIT 1",
+                   [msg_id]
+                 )
+               end
+      result.ntuples.positive?
+    end
+
+    def msg_id_archived?(conn, sanitized, msg_id)
       result = conn.exec_params(
-        "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 LIMIT 1",
+        "SELECT 1 FROM pgmq.a_#{sanitized} WHERE msg_id = $1 LIMIT 1",
         [msg_id]
       )
       result.ntuples.positive?
@@ -950,6 +1143,15 @@ module Pgbus
       result.ntuples.positive?
     end
 
+    def job_id_present?(conn, sanitized, job_id)
+      result = conn.exec_params(
+        "SELECT 1 FROM pgmq.q_#{sanitized} " \
+        "WHERE message::jsonb ->> 'job_id' = $1 LIMIT 1",
+        [job_id]
+      )
+      result.ntuples.positive?
+    end
+
     # Detect "relation does not exist" via the underlying PG error type.
     # Falls back to message matching only if PG::UndefinedTable is undefined
     # (very old pg gem) — never relies on locale-sensitive text.
@@ -1175,6 +1377,7 @@ module Pgbus
         create_queue_table(full_name)
         enable_notify_if_needed(full_name, NOTIFY_THROTTLE_MS)
         create_fifo_index_if_needed(full_name)
+        create_fair_index_if_needed(full_name)
       end
     end
 

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -28,12 +28,25 @@ module Pgbus
         # otherwise. This avoids losing a blocked row if enqueue fails.
         def promote_next(concurrency_key, client:, delay: 0)
           released = nil
+          msg_id = nil
           Pgbus::BlockedExecution.transaction do
             released = release_next(concurrency_key)
             raise ActiveRecord::Rollback unless released
 
             actual_delay = resolve_delay(released[:payload], delay)
-            client.send_message(released[:queue_name], released[:payload], delay: actual_delay)
+            # Carry the enqueuer's priority through: under priority routing it
+            # picks the _pN sub-queue, not just the release order (issue #423).
+            msg_id = client.send_message(released[:queue_name], released[:payload],
+                                         delay: actual_delay, priority: released[:priority])
+          end
+
+          if released && msg_id
+            begin
+              Batch.backfill_execution(released[:payload], msg_id,
+                                       client.target_queue(released[:queue_name], released[:priority]))
+            rescue StandardError => e
+              Pgbus.logger.warn { "[Pgbus] Batch execution backfill failed after promote: #{e.message}" }
+            end
           end
 
           !!released

data/lib/pgbus/configuration.rb

@@ -70,11 +70,40 @@ module Pgbus
     # :round_robin = use read_grouped_rr (fair round-robin across groups).
     attr_reader :group_mode
 
+    # Fair share scheduling across tenants (issue #426). nil = disabled.
+    # Any #call-able receiving the ActiveJob instance at enqueue time and
+    # returning nil (unkeyed), a key (String/Symbol/Integer), or [key, weight]
+    # (weight: positive Numeric, default 1). Keyed jobs are read with
+    # Client#read_batch_fair — a weighted, work-conserving interleave across
+    # keys within each queue. Mutually exclusive with group_mode.
+    attr_reader :fair_share
+
+    # Fair share for event-bus consumers (issue #427). nil = disabled. Any
+    # #call-able receiving the Pgbus::Event at publish time (routing_key,
+    # payload as passed to publish, headers) and returning nil, a key, or
+    # [key, weight] exactly like fair_share. The key rides in the event
+    # envelope and consumers read subscriber queues with
+    # Client#read_batch_fair. Independent of fair_share (jobs).
+    attr_reader :event_fair_share
+
+    # Persist ActiveSupport::CurrentAttributes across enqueue → perform
+    # (issue #430). nil = off (default). :auto = every CurrentAttributes
+    # subclass; an Array of classes/names; or a Hash of class/name =>
+    # { only: [...] } / { except: [...] }. Normalized to :auto or an Array of
+    # { name:, only:, except: } specs (classes are resolved lazily by name).
+    attr_reader :current_attributes
+
     # Archive compaction. Only the user-facing retention window is configurable;
     # the loop interval and batch size are tuned via constants on
     # Pgbus::Process::Dispatcher.
     attr_reader :archive_retention
 
+    # Batch execution-row sweep + finished-batch cleanup. Retention nil disables
+    # cleanup (same sentinel as archive_retention). Sweep interval is required.
+    # Stall threshold: how long a pending batch may go without a new execution
+    # row (or an orphan row without a msg_id) before the sweep repairs it.
+    attr_reader :batch_retention, :batch_sweep_interval, :batch_stall_threshold
+
     # Transactional outbox
     attr_accessor :outbox_enabled, :outbox_poll_interval, :outbox_batch_size
     attr_reader :outbox_retention # rubocop:disable Style/AccessorGrouping
@@ -262,8 +291,14 @@ module Pgbus
       @priority_levels = nil
       @default_priority = 1
       @group_mode = nil
+      @fair_share = nil
+      @event_fair_share = nil
+      @current_attributes = nil
 
       @archive_retention = 7 * 24 * 3600 # 7 days
+      @batch_retention = 7 * 24 * 3600 # 7 days
+      @batch_sweep_interval = 300 # 5 minutes
+      @batch_stall_threshold = 300 # 5 minutes, solid_queue's stalled_for default
 
       @outbox_enabled = false
       @outbox_poll_interval = 1.0
@@ -599,6 +634,28 @@ module Pgbus
       @group_mode = coerced
     end
 
+    def current_attributes=(value)
+      @current_attributes = Pgbus::CurrentAttributes.normalize(value)
+    end
+
+    def fair_share=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise Pgbus::ConfigurationError,
+              "fair_share must be nil or respond to #call (got #{callable.class})"
+      end
+
+      @fair_share = callable
+    end
+
+    def event_fair_share=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise Pgbus::ConfigurationError,
+              "event_fair_share must be nil or respond to #call (got #{callable.class})"
+      end
+
+      @event_fair_share = callable
+    end
+
     VALID_CONNECTION_GUC_MODES = %i[options session].freeze
 
     def connection_guc_mode=(mode)
@@ -774,6 +831,7 @@ module Pgbus
       validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
+      validate_fair_share!
 
       self
     end
@@ -818,7 +876,9 @@ module Pgbus
 
       # Interval knobs: positive Numeric, never nil (mirror polling_interval).
       { dispatch_interval: dispatch_interval, outbox_poll_interval: outbox_poll_interval,
-        recurring_schedule_interval: recurring_schedule_interval }.each do |name, value|
+        recurring_schedule_interval: recurring_schedule_interval,
+        batch_sweep_interval: batch_sweep_interval,
+        batch_stall_threshold: batch_stall_threshold }.each do |name, value|
         raise Pgbus::ConfigurationError, "#{name} must be > 0" unless value.is_a?(Numeric) && value.positive?
       end
 
@@ -852,6 +912,14 @@ module Pgbus
       raise Pgbus::ConfigurationError, "connects_to must be a Hash or nil"
     end
 
+    def validate_fair_share!
+      return unless fair_share && group_mode
+
+      raise Pgbus::ConfigurationError,
+            "fair_share and group_mode are mutually exclusive — fair_share interleaves across keys " \
+            "within a queue, group_mode serializes PGMQ FIFO groups; pick one"
+    end
+
     def validate_streams!
       unless streams_default_retention.is_a?(Numeric) && streams_default_retention >= 0
         raise Pgbus::ConfigurationError, "streams_default_retention must be a non-negative number"
@@ -1170,6 +1238,18 @@ module Pgbus
       @archive_retention = coerce_duration!(value, :archive_retention)
     end
 
+    def batch_retention=(value)
+      @batch_retention = coerce_duration!(value, :batch_retention)
+    end
+
+    def batch_sweep_interval=(value)
+      @batch_sweep_interval = coerce_duration!(value, :batch_sweep_interval)
+    end
+
+    def batch_stall_threshold=(value)
+      @batch_stall_threshold = coerce_duration!(value, :batch_stall_threshold)
+    end
+
     def outbox_retention=(value)
       @outbox_retention = coerce_duration!(value, :outbox_retention)
     end