pgbus 0.16.3 → 0.16.5

data/config/locales/nl.yml

@@ -86,6 +86,8 @@ nl:
         enqueued: In de wachtrij geplaatst
         failed_dlq: Mislukt / DLQ
         failed_dlq_labels: Mislukt / Dead Lettered
+        parked_jobs: Geparkeerde jobs
+        parked_jobs_oldest: oudste %{age}
         processes: Processen
         queues: Wachtrijen
         recurring: Terugkerend
@@ -404,6 +406,43 @@ nl:
       toggle_dark_mode: Donkere modus schakelen
       toggle_menu: Menu wisselen
     locks:
+      concurrency:
+        cards:
+          keys_at_limit: Sleutels op de limiet
+          keys_at_limit_hint: geen plek vrij
+          oldest_wait: Langste wachttijd
+          oldest_wait_hint: job die het langst wacht
+          parked_jobs: Geparkeerde jobs
+          parked_jobs_hint: wachten op een plek
+          slots_held: Bezette plekken
+          slots_held_hint: over alle sleutels
+        description: Sleutels gedeclareerd met limits_concurrency, de plekken die ze bezetten en de jobs die erachter geparkeerd staan
+        discard_parked: Geparkeerde verwijderen
+        discard_parked_confirm:
+          one: De 1 job die achter deze sleutel geparkeerd staat verwijderen? Hij draait nooit meer.
+          other: De %{count} jobs die achter deze sleutel geparkeerd staan verwijderen? Ze draaien nooit meer.
+        empty: Geen gelijktijdigheidssleutels in gebruik
+        headers:
+          in_use: In gebruik
+          key: Sleutel
+          lease: Lease
+          oldest_wait: Langste wachttijd
+          parked: Geparkeerd
+        key_released:
+          one: "%{key} vrijgegeven en 1 job gepromoveerd."
+          other: "%{key} vrijgegeven en %{count} jobs gepromoveerd."
+        lease:
+          expired: Verlopen
+          live: Actief
+          none: Geen houder
+        no_key: Geen gelijktijdigheidssleutel opgegeven.
+        parked_discarded:
+          one: 1 geparkeerde job verwijderd.
+          other: "%{count} geparkeerde jobs verwijderd."
+        release: Vrijgeven
+        release_confirm: "%{key} vrijgeven en de geparkeerde jobs promoveren?"
+        release_confirm_live: De lease op %{key} is nog vers, dus er draait waarschijnlijk nog een job. Vrijgeven laat er een naast starten. Doorgaan?
+        title: Gelijktijdigheid
       index:
         all_locks_discarded:
           one: 1 slot verwijderd.
@@ -427,7 +466,9 @@ nl:
           one: 1 slot verwijderd.
           other: "%{count} sloten verwijderd."
         none_selected: Geen sloten geselecteerd.
-        title: Uniciteitsleutels
+        page_description: Uniciteitssleutels en gelijktijdigheidsplekken die jobs tegenhouden
+        title: Vergrendelingen
+        uniqueness_title: Uniciteitsleutels
     outbox:
       index:
         description: Transactionele uitgaande berichten wachten op publicatie naar PGMQ

data/config/locales/pt.yml

@@ -86,6 +86,8 @@ pt:
         enqueued: Enfileirado
         failed_dlq: Falhou / DLQ
         failed_dlq_labels: Falhados / Dead Lettered
+        parked_jobs: Trabalhos estacionados
+        parked_jobs_oldest: mais antigo %{age}
         processes: Processos
         queues: Filas
         recurring: Recorrente
@@ -404,6 +406,43 @@ pt:
       toggle_dark_mode: Alternar modo escuro
       toggle_menu: Alternar menu
     locks:
+      concurrency:
+        cards:
+          keys_at_limit: Chaves no limite
+          keys_at_limit_hint: sem vaga livre
+          oldest_wait: Espera mais longa
+          oldest_wait_hint: o trabalho que espera há mais tempo
+          parked_jobs: Trabalhos estacionados
+          parked_jobs_hint: à espera de uma vaga
+          slots_held: Vagas ocupadas
+          slots_held_hint: em todas as chaves
+        description: Chaves declaradas com limits_concurrency, as vagas que ocupam e os trabalhos estacionados atrás delas
+        discard_parked: Descartar estacionados
+        discard_parked_confirm:
+          one: Descartar o trabalho estacionado atrás desta chave? Nunca será executado.
+          other: Descartar os %{count} trabalhos estacionados atrás desta chave? Nunca serão executados.
+        empty: Nenhuma chave de concorrência em uso
+        headers:
+          in_use: Em uso
+          key: Chave
+          lease: Concessão
+          oldest_wait: Espera mais longa
+          parked: Estacionados
+        key_released:
+          one: "%{key} libertada e 1 trabalho promovido."
+          other: "%{key} libertada e %{count} trabalhos promovidos."
+        lease:
+          expired: Expirada
+          live: Ativa
+          none: Sem detentor
+        no_key: Nenhuma chave de concorrência indicada.
+        parked_discarded:
+          one: 1 trabalho estacionado descartado.
+          other: "%{count} trabalhos estacionados descartados."
+        release: Libertar
+        release_confirm: Libertar %{key} e promover os seus trabalhos estacionados?
+        release_confirm_live: A concessão de %{key} ainda está válida, por isso é provável que um trabalho continue a correr. Libertar permite que outro arranque ao lado. Continuar?
+        title: Concorrência
       index:
         all_locks_discarded:
           one: 1 bloqueio descartado.
@@ -427,7 +466,9 @@ pt:
           one: 1 bloqueio descartado.
           other: "%{count} bloqueios descartados."
         none_selected: Nenhum bloqueio selecionado.
-        title: Chaves de unicidade
+        page_description: Chaves de unicidade e vagas de concorrência que estão a reter trabalhos
+        title: Bloqueios
+        uniqueness_title: Chaves de unicidade
     outbox:
       index:
         description: Entradas da caixa de saída transacional pendentes de publicação para PGMQ

data/config/locales/sv.yml

@@ -86,6 +86,8 @@ sv:
         enqueued: Inlagda
         failed_dlq: Misslyckade / DLQ
         failed_dlq_labels: Misslyckade / Dead Lettered
+        parked_jobs: Parkerade jobb
+        parked_jobs_oldest: äldst %{age}
         processes: Processer
         queues: Köer
         recurring: Återkommande
@@ -404,6 +406,43 @@ sv:
       toggle_dark_mode: Växla mörkt läge
       toggle_menu: Växla meny
     locks:
+      concurrency:
+        cards:
+          keys_at_limit: Nycklar vid gränsen
+          keys_at_limit_hint: ingen ledig plats
+          oldest_wait: Längsta väntan
+          oldest_wait_hint: längst ett jobb har väntat
+          parked_jobs: Parkerade jobb
+          parked_jobs_hint: väntar på en plats
+          slots_held: Hållna platser
+          slots_held_hint: över alla nycklar
+        description: Nycklar deklarerade med limits_concurrency, platserna de håller och jobben som parkerats bakom dem
+        discard_parked: Kasta parkerade
+        discard_parked_confirm:
+          one: Kasta det 1 jobb som parkerats bakom denna nyckel? Det kommer aldrig att köras.
+          other: Kasta de %{count} jobb som parkerats bakom denna nyckel? De kommer aldrig att köras.
+        empty: Inga samtidighetsnycklar används
+        headers:
+          in_use: Används
+          key: Nyckel
+          lease: Lås
+          oldest_wait: Längsta väntan
+          parked: Parkerade
+        key_released:
+          one: Frigjorde %{key} och befordrade 1 jobb.
+          other: Frigjorde %{key} och befordrade %{count} jobb.
+        lease:
+          expired: Utgånget
+          live: Aktivt
+          none: Ingen innehavare
+        no_key: Ingen samtidighetsnyckel angiven.
+        parked_discarded:
+          one: Kastade 1 parkerat jobb.
+          other: Kastade %{count} parkerade jobb.
+        release: Frigör
+        release_confirm: Frigör %{key} och befordra dess parkerade jobb?
+        release_confirm_live: Låset på %{key} är fortfarande färskt, så ett jobb körs troligen än. Att frigöra låter ett annat starta bredvid det. Fortsätta?
+        title: Samtidighet
       index:
         all_locks_discarded:
           one: Kasserade 1 lås.
@@ -427,7 +466,9 @@ sv:
           one: Kasserade 1 lås.
           other: Kasserade %{count} lås.
         none_selected: Inga lås valda.
-        title: Unikhetsnycklar
+        page_description: Unikhetsnycklar och samtidighetsplatser som håller tillbaka jobb
+        title: Lås
+        uniqueness_title: Unikhetsnycklar
     outbox:
       index:
         description: Transaktionella utboxposter som väntar på publicering till PGMQ

data/config/routes.rb

@@ -81,6 +81,11 @@ Pgbus::Engine.routes.draw do
     collection do
       post :discard_selected
       post :discard_all
+      # Collection routes, not member: a concurrency key is a free-form
+      # string that may contain ".", "/" or ":" and does not belong in a
+      # path segment. Both take the key as a form param.
+      post :release_key
+      post :discard_parked
     end
   end
   resource :insights, only: [:show], controller: "insights"

data/lib/pgbus/active_job/adapter.rb

@@ -70,17 +70,40 @@ module Pgbus
         priority = active_job.try(:priority)
         msg_id = nil
         blocked = false
+        # Only a failure raised from inside the produce can be ambiguous.
+        # Everything before it — taking the slot, parking the job — proves no
+        # message exists, however database-shaped the error looks. Never
+        # reset: once the send returns, msg_id is set and the rescue routes
+        # on that instead.
+        sending = false
 
         if key && concurrency
-          result = Concurrency::Semaphore.acquire(key, concurrency[:limit], concurrency[:duration])
+          # The check and the park commit together, under the semaphore row
+          # lock the upsert holds even when it reports :blocked — so a holder
+          # signalling right now waits and then sees the parked row instead
+          # of stranding it (rails/solid_queue#712).
+          acquired = false
+          Pgbus::Semaphore.transaction(requires_new: true) do
+            acquired = Concurrency::Semaphore.acquire(key, concurrency[:limit], slot_lease(concurrency, delay)) ==
+                       :acquired
+            blocked = handle_conflict(concurrency, active_job, key, queue, payload_hash, priority: priority) unless
+              acquired
+          end
 
-          if result == :acquired
-            msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay, priority: priority)
+          if acquired
+            # Deliberately AFTER the commit. PGMQ has its own connection, so
+            # the send can never join this transaction; sending first would
+            # mean a failed commit leaves the message live with the slot
+            # rolled back, and the next enqueue runs beside it. This way the
+            # only crash window leaves a slot held with no message — the
+            # sweep reclaims it, and until then the key is under-admitted,
+            # never over-admitted.
+            sending = true
+            msg_id = send_holding_slot(key, queue, payload_hash, delay: delay, priority: priority)
             active_job.provider_job_id = msg_id
-          else
-            blocked = handle_conflict(concurrency, active_job, key, queue, payload_hash, priority: priority)
           end
         else
+          sending = true
           msg_id = Pgbus.client.send_message(queue, payload_hash, delay: delay, priority: priority)
           active_job.provider_job_id = msg_id
         end
@@ -97,18 +120,69 @@ module Pgbus
         Thread.current[:pgbus_acquired_uniqueness_key] = nil
         active_job
       rescue StandardError => e
-        if msg_id.nil?
+        # An ambiguous send is treated exactly like a live message: the
+        # produce may have committed with only its reply lost, and undoing
+        # the bookkeeping for a message that is in fact live is the worse
+        # error — it would leave that job running with no uniqueness lock and
+        # uncounted by its batch. A batch left waiting for a job that never
+        # existed is recovered by the stalled-batch sweep; a batch that
+        # finishes early and fires its callback is not recoverable. The
+        # `sending` guard keeps that reprieve to the produce itself: a
+        # database error from the slot upsert or the park is not ambiguous.
+        if msg_id.nil? && !(sending && ambiguous_delivery?(e))
           rollback_acquired_uniqueness_lock
           uncount_batch_job(payload_hash)
         else
-          # Message is live: drop the thread-local so a later discard on this
-          # thread cannot release that job's uniqueness lock, but do not
-          # DELETE the pgbus_uniqueness_keys row.
+          # Drop the thread-local so a later discard on this thread cannot
+          # release that job's uniqueness lock, but do not DELETE the
+          # pgbus_uniqueness_keys row.
           Thread.current[:pgbus_acquired_uniqueness_key] = nil
         end
         raise e
       end
 
+      # True when a failure raised from inside the produce reached the
+      # database, so the message may have been written even though the reply
+      # did not come back. Deliberately an over-approximation: the client's
+      # pre-produce queue setup is inside the same call, so its connection
+      # errors are counted as ambiguous too. That errs toward keeping a lock
+      # and a batch count the reapers can reclaim, rather than dropping
+      # bookkeeping for a message that turns out to be live.
+      def ambiguous_delivery?(error)
+        (defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)) ||
+          (defined?(PG::Error) && error.is_a?(PG::Error))
+      end
+
+      # A slot is leased for `duration` of silence, but the visibility
+      # heartbeat that renews it only starts once a worker picks the message
+      # up. A scheduled job waits in PGMQ until then, so its lease has to
+      # cover the delay as well or the sweep expires it mid-wait and promotes
+      # a second job for the same key.
+      def slot_lease(concurrency, delay)
+        Concurrency.effective_duration(concurrency[:duration]) + delay.to_i
+      end
+
+      # Hand the slot back only when the failure proves nothing was
+      # produced. On an ambiguous outcome the message may well be live, and
+      # releasing would admit a second job beside it — so the hold stands
+      # and the lease expiry plus the dispatcher's sweep reclaim it.
+      def send_holding_slot(key, queue, payload_hash, delay:, priority:)
+        Pgbus.client.send_message(queue, payload_hash, delay: delay, priority: priority)
+      rescue StandardError => e
+        if ambiguous_delivery?(e)
+          Pgbus.logger.warn do
+            "[Pgbus] Send outcome unknown for #{key}; holding its concurrency slot until the lease expires: #{e.message}"
+          end
+        else
+          begin
+            Concurrency::Semaphore.release(key)
+          rescue StandardError => release_error
+            Pgbus.logger.warn { "[Pgbus] Could not release concurrency slot after failed send: #{release_error.message}" }
+          end
+        end
+        raise
+      end
+
       def physical_queue(queue, priority)
         Pgbus.client.target_queue(queue, priority)
       end

data/lib/pgbus/active_job/executor.rb

@@ -96,13 +96,24 @@ module Pgbus
           # `batch` (and `batch.enqueue` for open batches) work inside a job.
           assign_batch_id(job, payload)
           Pgbus.logger.debug { "[Pgbus::Executor] running #{tag} job_class=#{job_class}" }
-          with_visibility_heartbeat(job, queue_name, msg_id, source_queue) { execute_job(job) }
+          with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) { execute_job(job) }
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
           # message carries the batch tag and signals on its own outcome.
           retried = Batch.retry_reenqueued?(payload["job_id"])
           Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{tag} job_class=#{job_class}" }
-          archive_from(queue_name, msg_id, source_queue: source_queue)
+          # Archiving is the exact-once claim on this execution.
+          # :already_archived means another worker archived the message (our
+          # heartbeat lapsed and it was redelivered): that worker owns the
+          # completion signals, and signalling again here would release the
+          # concurrency slot a second time (rails/solid_queue#761).
+          if archive_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
+            Pgbus.logger.warn do
+              "[Pgbus::Executor] already archived elsewhere, skipping signals #{tag} job_class=#{job_class}"
+            end
+            release_duplicate_execution_lock(uniqueness_key, uniqueness_strategy, queue_name, msg_id)
+            return :duplicate
+          end
           Pgbus.logger.debug { "[Pgbus::Executor] archived #{tag} job_class=#{job_class}" }
           job_succeeded = true
           release_uniqueness_lock(uniqueness_key)
@@ -177,14 +188,18 @@ module Pgbus
       # Keep the message invisible while perform runs (see VisibilityHeartbeat).
       # Wraps only the perform: the heartbeat must be gone before archive or
       # the retry backoff touches the same message's VT.
-      def with_visibility_heartbeat(job, queue_name, msg_id, source_queue, &)
+      def with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload, &)
         klass = job.class
         per_job = klass.respond_to?(:pgbus_visibility_heartbeat_enabled) ? klass.pgbus_visibility_heartbeat_enabled : nil
         return yield if per_job == false
 
+        # The heartbeat also keeps the job's semaphore alive, so `duration`
+        # bounds silence, not run time.
+        concurrency_key = Concurrency.extract_key(payload)
         VisibilityHeartbeat.track(
           client: client, queue_name: source_queue || queue_name, prefixed: source_queue.nil?,
-          msg_id: msg_id, job_class: klass.name, config: config, &
+          msg_id: msg_id, job_class: klass.name, config: config,
+          concurrency: concurrency_key && [concurrency_key, Concurrency.config_for(klass)[:duration]], &
         )
       end
 
@@ -322,12 +337,10 @@ module Pgbus
         key = Concurrency.extract_key(payload)
         return unless key
 
-        # Atomic permit handoff: try to promote a blocked job first.
-        # promote_next wraps delete + enqueue in a transaction so neither is lost.
-        # If promoted, the slot stays occupied (no release needed).
-        # Only release the semaphore if there's nothing to promote.
-        promoted = Concurrency::BlockedExecution.promote_next(key, client: client)
-        Concurrency::Semaphore.release(key) unless promoted
+        # Release the slot and hand it to the next parked job in one
+        # transaction; the semaphore row lock orders this against a
+        # concurrent enqueue that is parking a job.
+        Concurrency::Semaphore.signal(key, client: client)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Concurrency signal failed: #{e.message}" }
       end
@@ -356,14 +369,26 @@ module Pgbus
       # that succeeded but failed to archive redelivers after VT expiry and
       # runs twice. If the retry also fails, fall through to the normal
       # failure path (recorded failure + VT-based redelivery).
+      # Returns :archived, :already_archived, or :ambiguous.
+      #
+      # A `false` reported after our OWN retry is ambiguous, not a duplicate:
+      # the first archive may well have committed with only its reply lost to
+      # the connection error that triggered the retry. Claiming it is the
+      # safe reading — the alternative strands this job's concurrency slot,
+      # batch and uniqueness state on every such blip, whereas a genuine
+      # duplicate would additionally require another worker to have taken and
+      # finished the same message inside the retry window.
       def archive_from(queue_name, msg_id, source_queue: nil)
         attempts = 0
         begin
-          if source_queue
-            client.archive_message(source_queue, msg_id, prefixed: false)
-          else
-            client.archive_message(queue_name, msg_id)
-          end
+          archived = if source_queue
+                       client.archive_message(source_queue, msg_id, prefixed: false)
+                     else
+                       client.archive_message(queue_name, msg_id)
+                     end
+          return :archived unless archived == false
+
+          attempts.positive? ? :ambiguous : :already_archived
         rescue StandardError => e
           attempts += 1
           raise unless attempts == 1 && connection_error?(e)
@@ -375,6 +400,21 @@ module Pgbus
         end
       end
 
+      # A :while_executing lock is bound to THIS message, so an execution
+      # that loses the archive race still has to hand its own lock back —
+      # conditionally, so it can never delete a successor's row. An
+      # :until_executed lock belongs to the job as a whole and is released by
+      # the worker that actually archived it.
+      def release_duplicate_execution_lock(uniqueness_key, uniqueness_strategy, queue_name, msg_id)
+        return unless uniqueness_key && uniqueness_strategy == :while_executing
+
+        # Same queue the execution lock was acquired under, so the match
+        # cannot land on another queue's message of the same id.
+        UniquenessKey.release_if_bound!(uniqueness_key, queue_name: queue_name, msg_id: msg_id)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Duplicate-execution lock release failed: #{e.message}" }
+      end
+
       def connection_error?(error)
         defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)
       end

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -7,11 +7,20 @@ module Pgbus
     module BlockedExecution
       class << self
         # Insert a blocked execution for a job that hit the concurrency limit.
+        #
+        # `expires_at` is a re-check hint for the sweep's ordering only — a
+        # parked job is never deleted for being old. The only way out of the
+        # table is promotion.
+        #
+        # The payload goes in as a Hash: the jsonb attribute serializes it
+        # once. Handing it a pre-serialized String stored a JSON *string*
+        # (double-encoded), which every document reader of the column —
+        # `payload->>'job_id'`, the job-class lookup, `scheduled_at` — misread.
         def insert(concurrency_key:, queue_name:, payload:, duration:, priority: 0)
           Pgbus::BlockedExecution.create!(
             concurrency_key: concurrency_key,
             queue_name: queue_name,
-            payload: JSON.generate(payload),
+            payload: payload,
             priority: priority,
             expires_at: Time.current + duration
           )
@@ -23,42 +32,53 @@ module Pgbus
           Pgbus::BlockedExecution.release_next!(concurrency_key)
         end
 
-        # Atomically promote the next blocked execution: delete the row and enqueue
-        # the job in a single transaction. Returns true if a job was promoted, false
-        # otherwise. This avoids losing a blocked row if enqueue fails.
+        # Atomically promote the next blocked execution: delete the row, take a
+        # semaphore slot for it and enqueue the job in a single transaction.
+        # Returns true if a job was promoted, false otherwise.
+        #
+        # The slot is taken through the same guarded upsert an enqueue uses,
+        # so a promotion can never push the key past its limit; when no slot
+        # is free the savepoint rolls back and the row stays parked. Runs as a
+        # savepoint so `Semaphore.signal` can wrap it with the release.
         def promote_next(concurrency_key, client:, delay: 0)
           released = nil
           msg_id = nil
-          Pgbus::BlockedExecution.transaction do
+          Pgbus::BlockedExecution.transaction(requires_new: true) do
             released = release_next(concurrency_key)
             raise ActiveRecord::Rollback unless released
 
+            # Resolve the delay first: a parked scheduled job goes back into
+            # PGMQ invisible, and nothing renews its lease until a worker
+            # picks it up, so the wait has to be part of the lease.
             actual_delay = resolve_delay(released[:payload], delay)
+            raise ActiveRecord::Rollback unless slot_taken?(concurrency_key, released[:payload], 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
+          return false unless released && msg_id
 
-          !!released
+          backfill(released, msg_id, client)
+          true
         rescue StandardError => e
           Pgbus.logger.warn { "[Pgbus] Promote blocked execution failed for #{concurrency_key}: #{e.message}" }
           false
         end
 
-        # Delete blocked executions that have expired.
-        # Returns the count of deleted rows.
-        def expire_stale
-          Pgbus::BlockedExecution.expired(Time.current).delete_all
+        # Sweep: promote every parked job that can take a slot right now.
+        # Covers what the completion-time signal cannot — a holder that died
+        # (its semaphore expired and was swept) or a promote that failed.
+        # Returns the number of jobs promoted.
+        def promote_pending(client:, per_key: 100)
+          Pgbus::BlockedExecution.repair_double_encoded!
+          Pgbus::BlockedExecution.promotable_keys.sum do |key|
+            promoted = 0
+            promoted += 1 while promoted < per_key && promote_next(key, client: client)
+            promoted
+          end
         end
 
         # Count blocked executions for a given key. Useful for testing/monitoring.
@@ -68,6 +88,27 @@ module Pgbus
 
         private
 
+        # The batch execution row is bookkeeping, not the promotion. Give it
+        # its own savepoint: `Semaphore.signal` calls promote_next inside a
+        # transaction, and a database error out here would poison that
+        # transaction — the commit then fails, un-deleting the parked row and
+        # un-taking the slot while the message is already live, so the job
+        # runs a second time.
+        def backfill(released, msg_id, client)
+          Pgbus::BlockedExecution.transaction(requires_new: true) do
+            Batch.backfill_execution(released[:payload], msg_id,
+                                     client.target_queue(released[:queue_name], released[:priority]))
+          end
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus] Batch execution backfill failed after promote: #{e.message}" }
+        end
+
+        def slot_taken?(concurrency_key, payload, delay = 0)
+          config = Concurrency.config_for_payload(payload)
+          expires_at = Time.current + Concurrency.effective_duration(config[:duration]) + delay.to_i
+          Pgbus::Semaphore.acquire!(concurrency_key, config[:limit], expires_at) == :acquired
+        end
+
         def resolve_delay(payload, default_delay)
           scheduled_at = payload["scheduled_at"]
           return default_delay unless scheduled_at

data/lib/pgbus/concurrency/semaphore.rb

@@ -6,6 +6,12 @@ module Pgbus
       class << self
         # Attempt to acquire a slot in the semaphore for the given key.
         # Returns :acquired if a slot was available, :blocked if the limit is reached.
+        #
+        # The upsert takes the semaphore row lock until the surrounding
+        # transaction commits — even when it returns :blocked. The adapter
+        # relies on that: parking the job inside the same transaction means a
+        # holder that signals concurrently waits on `release` below and then
+        # sees the parked row (rails/solid_queue#712).
         def acquire(key, max_value, duration)
           expires_at = Time.current + duration
           Pgbus::Semaphore.acquire!(key, max_value, expires_at)
@@ -16,6 +22,34 @@ module Pgbus
           Pgbus::Semaphore.where(key: key).update_all("value = GREATEST(value - 1, 0)")
         end
 
+        # A job holding a slot is done: give the slot back and hand it to the
+        # next parked job for this key, in one transaction. The decrement locks
+        # the semaphore row first, so an enqueue that is parking a job right
+        # now commits before the promote looks for parked rows.
+        def signal(key, client:)
+          Pgbus::Semaphore.transaction do
+            release(key)
+            BlockedExecution.promote_next(key, client: client)
+          end
+        end
+
+        # Push the semaphore's expiry out while a holder is still running.
+        # Driven by the visibility heartbeat, so `duration` is the longest a
+        # holder may go silent before its slot is presumed dead — not a cap on
+        # how long a job may run.
+        def touch(key, duration)
+          # Floored here as well as at acquire: renewing for a raw duration
+          # shorter than the gap to the next beat would let the lease lapse
+          # mid-run and the sweep promote beside a running job.
+          # Start the lease once the connection is in hand: waiting on a busy
+          # pool would otherwise be charged against the renewal.
+          floored = Concurrency.effective_duration(duration)
+          Pgbus::Semaphore.connection_pool.with_connection do
+            Pgbus::Semaphore.where(key: key)
+                            .update_all(["expires_at = GREATEST(expires_at, ?)", Time.current + floored])
+          end
+        end
+
         # Delete semaphores that have expired (safety net for crashed workers).
         # Returns an array of hashes with expired keys.
         # Uses DELETE ... RETURNING for atomicity (no race between pluck and delete).