pgbus 0.16.6 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cddde0da7d83fc84f54404d10bcdbfccb06f25af74379b560ac4f9bb892f0041
-  data.tar.gz: 44eba7a5a2bbe87659f388c7fb10c5a7b7577a1f045bb8d48c527cfbf9266df5
+  metadata.gz: 11b7ad58d91fe1eb9c0388008907523c77324f286f27a0e97a94353e4a8577b0
+  data.tar.gz: '0707593bb7c826f48f9a84db9a666057aaed3407b0d1cb559007f57caf080be2'
 SHA512:
-  metadata.gz: 3bb680972106246ea3a16265730eb8b0567944e80323cbca8a9f68f7b7302b8afa2087cfee74e0fa99b695f038fd5e2104141971096ac8d76b236437ce147e60
-  data.tar.gz: cf822271a70b7ec8bcbbca0591838179678113c2b19849a87b4442cf5e0ccd3b2bac1d7a92e8820596c839ff1005c82d0c0ab45d47ddad2df1bae8094b0a9208
+  metadata.gz: 0f1422dea206dbeaac10b1fd7dfa74da2338c007cffb48d7a2b5429bf3a94e6f3e78b5795832d0a2f45346fe4350d4c7355d16b773247420894ea5234c50db85
+  data.tar.gz: 6d30c3583b7e6b5fa9dc89cf42115f57b182dea18b2d363f1ec413d6096ba32b76d75f008dcf7a2f25de3baf9ceba7e17f1edbb382b96e2aeb23bf52a8824af2

data/CHANGELOG.md

@@ -6,10 +6,16 @@
 
 - **Concurrency is now visible: a section on the Locks page, three gauges, a home stat card and an MCP tool.** `limits_concurrency … on_conflict: :block` became durable in #460 — a parked job is never dropped and a key never runs past `to:` — but nothing showed it, so an operator whose per-record pipeline looked "stuck" had no way to see that the key's slot was held, how many jobs were parked behind it, or how long the oldest had waited, short of SQL. `pgbus_semaphores` and `pgbus_blocked_executions` appeared on no page, in no gauge, in no tool. One new read, `Web::DataSource#concurrency_stats`, now feeds four surfaces: the Locks page's **Concurrency** section (parked jobs, oldest wait, slots held, keys at limit, then a row per key with value / limit, lease state, parked count and oldest wait, auto-refreshing like the other dashboard panels); a **Parked jobs** card on the dashboard home; three unlabelled gauges on both `/pgbus/api/metrics` and the AppSignal probe (`pgbus_concurrency_blocked_executions`, `pgbus_concurrency_blocked_oldest_age_seconds`, `pgbus_concurrency_slots_held` — keys are per-record, so a per-key label would be an unbounded series); and a read-only `pgbus_concurrency` MCP tool returning the same data. The key rows come from a FULL OUTER JOIN, not a LEFT one: a key can have parked jobs and no semaphore (its holder died and the sweep removed the row) or a semaphore and nothing parked, and both shapes matter to an operator. Each row carries two guarded escape hatches. **Release** drops the semaphore and promotes through `Concurrency::BlockedExecution.promote_next`, so it takes each slot through the same guarded upsert an enqueue uses and can never reintroduce the over-admission #460 closed; when the lease is still fresh the confirm says so, because a job is then probably still running and releasing lets another start beside it. **Discard parked** drops a single key's parked jobs, naming the exact count in the confirm, and resolves the bookkeeping those jobs will never resolve themselves — a parked batch child is marked failed so its batch stops waiting and `on_failure` fires (#413), and an `:until_executed` uniqueness lock is released rather than orphaned (#423); each discard logs a warning naming the job and emits `pgbus.blocked_execution_discarded`. There is deliberately no cross-key "discard all parked": not losing work is the whole point of `:block`. Nothing is added to the enqueue or execute path. Refs #461.
 
+- **PGMQ: vendored schema v1.13.0, and the upgrade migration now carries upstream's table fixups.** The 1.12.0 → 1.13.0 delta is entirely partitioned-queue work plus one metrics attribute: `pgmq.create_partitioned` gains a `premake` argument (its three-argument form dropped, so pgmq-ruby's three-argument call binds to the new signature with the default), new partitioned queues use `msg_id … GENERATED BY DEFAULT AS IDENTITY` rather than `GENERATED ALWAYS`, and `pgmq.metrics_result` gains `default_partition_length` (NULL for non-partitioned queues, ignored by pgmq-ruby, which reads rows by name). Nothing pgbus calls through `Pgbus::Client` changes, and pgbus creates only partitioned *archives*, whose `msg_id` is a plain column — so no client or pgmq-ruby change. Fresh embedded installs get 1.13.0; existing *embedded* installs: `rake pgbus:pgmq:status`, then `rails generate pgbus:upgrade_pgmq` + `rails db:migrate` (`rails db:migrate:pgbus` on a separate-database install). An `:extension` install is upgraded by PostgreSQL itself (`ALTER EXTENSION pgmq UPDATE`) once the server has the new version packaged — not by this migration, whose function drop refuses to remove extension-owned objects. **New:** because the upgrade works by dropping every pgmq function and composite type and re-running the target schema, it could never carry an upstream change to an existing *table*. The generated migration now reads the version in `pgbus_pgmq_schema_versions` and applies the fixup vendored for each version between it and the target (`lib/pgbus/pgmq_schema/fixups/pgmq_v<VERSION>.sql`, discovered by the same glob as the schema files, via `PgmqSchema.fixups_sql`). This hop's fixup is upstream's own guarded block moving existing partitioned queues to `GENERATED BY DEFAULT`; it selects on `pgmq.meta.is_partitioned`, so it is a no-op unless partitioned queues were created through PGMQ directly. Fixups must be idempotent — an install with no recorded version gets all of them. Closes #459.
+
 - **The batches list and a batch's progress panel now refresh themselves.** Batches was the only dashboard list whose `turbo-frame` was missing `data-auto-refresh`, and the batch detail page had no frame at all, so watching a batch drain meant reloading by hand. Both now poll on the existing `web_refresh_interval` (5s, pauses while you interact) like every other list — the batch progress panel is served by `GET /batches/:id?frame=progress`. This reuses the dashboard's turbo-frame polling rather than the SSE stack in `lib/pgbus/web/stream_app.rb`: that is the host-app-facing stream feature, and pointing it at the dashboard would open a PG `LISTEN` connection per viewer to move four integers.
 
 ### Fixed
 
+- **A still-running event handler is no longer re-run as if it had crashed, and a slow one is no longer redelivered mid-run.** Two halves of one hole, follow-up to #469. First: `Process::Consumer` had no equivalent of `ActiveJob::Executor#with_visibility_heartbeat`, so an event message's visibility timeout was never re-armed — a handler slower than `visibility_timeout` (30s by default) was redelivered *while it was still running*, `read_ct` climbed on every redelivery, and after `max_retries` the event was dead-lettered without the handler ever raising. Workers have been protected from this since the heartbeat landed; event consumers never were. The consumer now tracks each message through `VisibilityHeartbeat` for exactly as long as its handlers run, releasing the entry before the archive so a beat can never re-arm a message that is already gone. Second: `Handler#claim_idempotency?` read a `pgbus_processed_events` row with `completed_at IS NULL` as proof that the previous holder had been killed mid-handler, and re-ran. That state equally describes a handler that is simply still running — on another thread, another fork or another host — so a second delivery (a genuine redelivery, or a duplicate envelope, whose independent visibility timeouts no heartbeat can serialize) executed the handler *concurrently with* the live one, which is precisely the double-execution `idempotent!` exists to prevent. The claim now carries liveness rather than only a claim instant: `EventBus::ClaimBeat` refreshes every in-flight claim's `processed_at` from the same beat that re-arms the message's visibility timeout, so message visibility and claim liveness go quiet together when a process dies. A pending claim silent for longer than twice the heartbeat interval is abandoned and re-runs, exactly as before; a fresher one is owned and the delivery skips, deferring to the holder — which either completes (nothing is lost) or fails, leaving its own message for visibility-timeout redelivery to recover. A skip is also no longer silent: `pgbus.event_skipped` carries the reason (`:completed`, `:cached` or `:owned`), the claim's age in seconds and the delivery's `read_ct`, and the metrics subscriber counts it as `pgbus_event_count` with `status: "skipped"` and the reason as a tag. No migration, no new column, and no change on a table that has not run `pgbus:add_processed_event_completion` — a single-phase claim has no pending state and therefore no ownership question. Closes #470.
+
+- **An event is no longer handed to every handler whose pattern matches it, so a wildcard handler ran once per subscriber on the topic.** Each subscriber gets its own queue (`Subscriber#setup!` creates and binds one), so a topic with N matching subscribers puts N copies of every event on the bus — but `Consumer#handle_message` resolved handlers with `Registry#handlers_for(routing_key)`, a pattern match that ignored which queue the message had just been read from, and ran every match. Each of the N copies therefore fanned out to all N handlers: **every handler ran N times per event**, with four `"#"` subscribers meaning four invocations of each handler for every event on the bus. `idempotent!` was the only thing hiding it, and it hides it imperfectly by design: the two-phase claim (#385) deliberately *re-runs* when the existing claim is still pending, on the theory that the prior holder crashed — but a pending claim is also exactly what a handler still running on another host looks like. So one event could have host A win the claim and start a 700ms handler while host B, reading a different subscriber's copy of the same event a few hundred milliseconds later, dispatched to that same handler, lost the claim insert, read `completed_at IS NULL` as "crashed, re-run", and executed it concurrently. In one host app that meant a "task completed" record written twice and the user emailed twice, with a single row in `pgbus_processed_events`, `read_ct = 1` on every archived copy, and the second execution's side effects timestamped inside the first's window — dispatch, not redelivery. A non-idempotent handler simply ran N times with no guard at all. `handlers_for` now takes a required `queue_name:` and selects on ownership *and* pattern, so a message read from queue Q goes to Q's owner(s) alone and each handler runs exactly once per event; duplicate execution again requires a real redelivery, which is the at-least-once contract the docs describe. The keyword is required rather than defaulted precisely so a keyword-less call cannot silently restore the fan-out — the two callers that genuinely want the pattern view (the `Testing.inline!` publish path and `Testing::EventStore#drain!`, neither of which has a queue, since the event never reaches PGMQ) moved to an explicitly named `Registry#subscribers_matching`, where per-subscriber delivery counts already match what owner-only dispatch now produces in production. Two handlers registered against the same explicit `queue_name:` still both run on that queue's delivery. The pattern check is kept alongside the ownership check because a routing key the owner's pattern does not match means a stale `pgmq.topic_bindings` row, and a stale binding must not run the handler. A message on a queue no subscriber in this process owns is still archived rather than looped through visibility-timeout redelivery into the DLQ — that was already the behavior when `handlers_for` returned `[]` — but it is no longer silent: it logs a warning naming the queue and routing key, rate-limited to once per queue per process so a permanently stale binding cannot flood the log, and emits `pgbus.event_unrouted` on every occurrence so the real rate stays visible in metrics. The pending-claim re-run in `Handler#claim_idempotency?` is deliberately untouched here; it is a separate question now that dispatch no longer manufactures the concurrency it was misreading. Closes #469.
+
 - **A dropped ActiveRecord socket no longer pages the host app for an event that was handled successfully.** EventBus consumers are long-lived threads holding a leased AR connection, and a pooler restart, an admin disconnect or a brief failover can kill that socket at any point. Rails reconnects most statements transparently, but `Relation#update_all` is marked `allow_retry: false` — and that is exactly the phase-2 claim stamp in `Handler#complete_claim!`, the one AR write that happens *after* `handle` has already returned. A drop there surfaced as `ActiveRecord::ConnectionFailed` ("PQconsumeInput() SSL error: unexpected eof while reading") on a message whose work was done, so the host app's exception tracker paged for a false failure and PGMQ redelivered the event for a re-run. `EventBus::StaleConnectionRetry` now reconnects this thread's lease (via `ConnectionPool#active_connection?`, the accessor that exists across the supported Rails range) and repeats the stamp once; a second drop still raises, leaving the message to VT redelivery. Only the leased connections are reconnected — `clear_all_connections!` would yank sockets out from under sibling consumers in the same process, turning one recoverable drop into many. The retryable patterns are deliberately *broader* than `Client::STALE_CONNECTION_PATTERNS` and for the opposite reason: that list excludes mid-flight drops because a half-committed enqueue would duplicate a message, whereas this only ever repeats an idempotent `SET completed_at = <now>`. Phase 1 (`claim_idempotency?`) is deliberately not wrapped — its INSERT may have committed before the socket died, and on a legacy schema the retry's empty `result.rows` would read as "another consumer owns this claim", turning a recoverable drop into a silently skipped event.
 
 

data/README.md

@@ -221,6 +221,14 @@ Pgbus::EventBus::Registry.instance.subscribe(
 )
 ```
 
+Each subscriber gets its own queue, and a queue is consumed only by the
+handler(s) registered against it: one published event matching N subscribers
+becomes N deliveries, one per handler, so every handler runs exactly once per
+event. (Two handlers sharing an explicit `queue_name:` both run on that queue's
+delivery.) A message on a queue no subscriber in this process owns — a stale
+topic binding left by a renamed or removed handler — is archived, logged once
+per queue, and reported as `pgbus.event_unrouted`.
+
 `idempotent!` uses a **two-phase claim**: a *pending* row in
 `pgbus_processed_events` is inserted before `handle` runs, and only stamped
 `completed_at` after `handle` returns. Deduplication applies to **completed**

data/Rakefile

@@ -16,7 +16,7 @@ require "rubocop/rake_task"
 # on the unresolvable gem inheritance. Passing explicit paths stops the
 # discovery. docs/ lints itself in the Docs site workflow. (Same fix as docs-kit.)
 RuboCop::RakeTask.new do |task|
-  task.patterns = %w[app benchmarks config lib spec Gemfile Rakefile pgbus.gemspec]
+  task.patterns = %w[app benchmarks config lib rakelib spec Gemfile Rakefile pgbus.gemspec]
 end
 
 namespace :bench do
@@ -164,173 +164,8 @@ task :build do
   sh("rm -rf /tmp/gem-verify #{gem_file}")
 end
 
-desc "Release a new version (rake release[1.2.3] or rake release[pre] or rake release[1.2.3,force])"
-task :release, %i[version force] do |_t, args|
-  require_relative "lib/pgbus/version"
-
-  def info(msg)    = puts "\e[34m→\e[0m #{msg}"
-  def success(msg) = puts "\e[32m✓\e[0m #{msg}"
-  def skip(msg)    = puts "\e[33m⊘\e[0m #{msg} \e[33m(skipped)\e[0m"
-  def warn(msg)    = puts "\e[33m⚠\e[0m #{msg}"
-  def error(msg)   = puts "\e[31m✗\e[0m #{msg}"
-  def header(msg)  = puts "\n\e[1;36m#{msg}\e[0m\n#{"─" * msg.length}"
-
-  new_version = args[:version]
-  abort "\e[31mUsage: rake release[X.Y.Z] or rake release[X.Y.Z,force]\e[0m" unless new_version
-
-  force = args[:force]&.to_s&.downcase == "force"
-
-  dirty = `git status --porcelain`.strip
-  abort "\e[31mAborting: working directory is not clean.\e[0m\n#{dirty}" unless dirty.empty?
-
-  current = Pgbus::VERSION
-  prerelease = new_version.match?(/alpha|beta|rc|pre/) || new_version == "pre"
-
-  if new_version == "pre"
-    new_version = current
-    prerelease = true
-  end
-
-  tag = "v#{new_version}"
-  version_file = "lib/pgbus/version.rb"
-
-  title = "Release #{tag}"
-  title += " (force)" if force
-  header title
-  info "Current version: #{current}"
-  info "New version:     #{new_version}"
-  info "Pre-release:     #{prerelease}"
-
-  # Step 0: Force cleanup — delete existing release and tag
-  if force
-    header "Force cleanup"
-    if system("gh release view #{tag} >/dev/null 2>&1")
-      sh("gh release delete #{tag} --yes --cleanup-tag")
-      success "Deleted release and remote tag #{tag}"
-    else
-      skip "No release #{tag} to delete"
-    end
-
-    if system("git rev-parse #{tag} >/dev/null 2>&1")
-      sh("git tag -d #{tag}")
-      success "Deleted local tag #{tag}"
-    else
-      skip "No local tag #{tag} to delete"
-    end
-  end
-
-  # Step 1: Update version file
-  header "Version"
-  if new_version == current
-    skip "Version already #{new_version}"
-  else
-    content = File.read(version_file)
-    content.sub!(/VERSION = ".*"/, "VERSION = \"#{new_version}\"")
-    File.write(version_file, content)
-    success "Updated #{version_file}"
-  end
-
-  # Step 1b: Regenerate the frozen lockfiles that pin the pgbus path gem, so the
-  # bump ships with them in sync. These are installed with `--frozen`/deployment
-  # in CI, so if they still name the OLD version they instant-fail (the root
-  # Gemfile.lock on every main-Gemfile leg AND release.yml's own `bundle install`,
-  # the Rails 7.1 leg with exit 16, and docs-CI on any docs change). Regenerating
-  # here keeps the version-pin drift out of the release commit instead of
-  # surfacing on the next PR — or, worse, in the Release workflow itself.
-  header "Frozen lockfiles"
-  # The ONLY thing a version bump changes in these frozen lockfiles is the pgbus
-  # path-gem pin — so bump exactly that line, in place, with a string edit.
-  #
-  # We deliberately do NOT run `bundle lock` here: a full re-resolve trips over
-  # constraints that have nothing to do with pgbus. Concretely, docs/Gemfile.lock
-  # carries a broad PLATFORMS list (…-gnu / …-musl / arm-linux) for which a
-  # platform gem like `thruster` ships no variant, so `bundle lock` fails with
-  # "Could not find gems matching 'thruster' valid for all resolution platforms"
-  # on any machine whose cache doesn't already hold those exact gems — aborting
-  # the release. `bundle lock --local` was even worse (wrong-file write + no
-  # fetch). A targeted pin edit sidesteps all of it, is deterministic on any
-  # machine, and produces the minimal 2-line diff (the PATH spec + the
-  # DEPENDENCIES pin). See #338/#341 and the surgical-bump fix.
-  frozen_lockfiles = %w[Gemfile.lock gemfiles/rails_7_1.gemfile.lock docs/Gemfile.lock]
-  regenerated_lockfiles = []
-  frozen_lockfiles.each do |lockfile|
-    unless File.exist?(lockfile)
-      skip "#{lockfile} not present"
-      next
-    end
-
-    content = File.read(lockfile)
-    # Matches both the PATH-source spec ("    pgbus (X.Y.Z)") and the
-    # DEPENDENCIES pin ("  pgbus (X.Y.Z)"), leaving everything else untouched.
-    bumped = content.gsub(/^(\s+pgbus) \([^)]*\)$/, "\\1 (#{new_version})")
-
-    if bumped == content
-      skip "#{lockfile} — no pgbus pin to bump"
-      next
-    end
-
-    File.write(lockfile, bumped)
-    regenerated_lockfiles << lockfile
-    success "Bumped pgbus pin in #{lockfile}"
-  end
-
-  # Step 2: Verify gem builds cleanly
-  header "Build verification"
-  sh("gem build pgbus.gemspec --strict")
-  sh("rm -f pgbus-*.gem")
-  success "Gem builds cleanly"
-
-  # Step 3: Commit version bump (+ any re-synced lockfiles)
-  header "Git commit"
-  paths_to_stage = [version_file, *regenerated_lockfiles]
-  staged_changes = paths_to_stage.any? do |path|
-    !`git diff #{path}`.strip.empty? || !`git diff --cached #{path}`.strip.empty?
-  end
-  if staged_changes
-    paths_to_stage.each { |path| sh("git add #{path}") }
-    sh("git commit -m 'chore: bump version to #{new_version}'")
-    success "Committed version bump"
-  else
-    skip "No version change to commit"
-  end
-
-  # Step 4: Push to origin
-  header "Git push"
-  local_sha = `git rev-parse HEAD`.strip
-  remote_sha = `git rev-parse origin/main 2>/dev/null`.strip
-  if local_sha == remote_sha
-    skip "origin/main already at #{local_sha[0..6]}"
-  else
-    sh("git push origin main")
-    success "Pushed to origin/main"
-  end
-
-  # Step 5: Create release
-  header "Release"
-  tag_exists = system("git rev-parse #{tag} >/dev/null 2>&1")
-  release_exists = system("gh release view #{tag} >/dev/null 2>&1")
-
-  if release_exists
-    skip "Release #{tag} already exists (use force to re-create)"
-  elsif tag_exists
-    info "Tag #{tag} exists, creating release from it"
-    pre_flag = prerelease ? "--prerelease" : ""
-    sh("gh release create #{tag} --generate-notes #{pre_flag}".strip)
-    success "Release #{tag} created from existing tag"
-  else
-    pre_flag = prerelease ? "--prerelease" : ""
-    sh("gh release create #{tag} --generate-notes --target main #{pre_flag}".strip)
-    success "Release #{tag} created"
-  end
-
-  puts ""
-  success "\e[1mRelease #{tag} complete!\e[0m CI will handle the rest:"
-  puts "    • Run tests"
-  puts "    • Build + verify gem"
-  puts "    • Sign with Sigstore"
-  puts "    • Publish to RubyGems"
-  puts "    • Upload assets to the release"
-end
+# `rake release[X.Y.Z]` lives in rakelib/release.rake (shared across the
+# zoolutions gems); `bin/release` is its interactive front door.
 
 namespace :frontend do
   # app/frontend/pgbus/style.css is a committed build artifact — the engine ships

data/lib/generators/pgbus/templates/upgrade_pgmq.rb.erb

@@ -8,6 +8,16 @@ class UpgradePgmqToV<%= target_version_slug.camelize %> < ActiveRecord::Migratio
     # This uses the vendored SQL which doesn't require the pgmq extension.
     execute Pgbus::PgmqSchema.install_sql("<%= target_version %>")
 
+    # Apply the table fixups upstream ships for every hop between the
+    # version this database records and the target. Dropping and re-creating
+    # the functions cannot carry a change to an existing TABLE (1.13.0 moves
+    # partitioned queues' msg_id to GENERATED BY DEFAULT), so those ride
+    # here. Runs after install_sql because the fixups call
+    # pgmq.format_table_name, which the drop step removed. Each fixup is
+    # idempotent, so an install with no recorded version gets them all.
+    fixups = Pgbus::PgmqSchema.fixups_sql(after: installed_pgmq_version, upto: "<%= target_version %>")
+    execute fixups unless fixups.empty?
+
     # Re-install the per-queue NOTIFY insert triggers the function drop
     # cascaded away (pgmq.notify_insert_throttle records which queues had
     # them and at what throttle; enable_notify_insert is idempotent).
@@ -34,4 +44,16 @@ class UpgradePgmqToV<%= target_version_slug.camelize %> < ActiveRecord::Migratio
       "PGMQ schema downgrade is not supported. " \
       "Restore from a database backup if needed."
   end
+
+  private
+
+  # The version this database last recorded, or nil when it has never been
+  # tracked (a pre-tracking install, or one bootstrapped by hand).
+  def installed_pgmq_version
+    return nil unless connection.table_exists?("pgbus_pgmq_schema_versions")
+
+    connection.select_value(
+      "SELECT version FROM pgbus_pgmq_schema_versions ORDER BY installed_at DESC LIMIT 1"
+    )
+  end
 end

data/lib/pgbus/event_bus/claim_beat.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    # Liveness for the idempotency claims in flight for one PGMQ message.
+    #
+    # A two-phase claim (issue #385) is a `pgbus_processed_events` row with
+    # `completed_at IS NULL`. That state says "claimed, not finished" — it does
+    # NOT say whether the claimer is dead or simply still running (issue #470).
+    # Handler resolves the ambiguity by age: a claim whose `processed_at` has
+    # gone quiet for longer than the ownership window is abandoned, anything
+    # fresher is owned. For that age to mean "silence" rather than
+    # "time since the claim was taken", something has to keep stamping it while
+    # the handler runs. This is that something.
+    #
+    # One beat per message, created by Process::Consumer and handed to every
+    # handler dispatched for it. A handler registers its claim for exactly the
+    # duration of `handle` and the consumer's VisibilityHeartbeat `on_beat` hook
+    # drives #touch! on the same cadence that re-arms the message's visibility
+    # timeout — so the claim and the message go quiet together when the process
+    # dies, and both stay fresh while it lives.
+    #
+    # #touch! runs on the heartbeat ticker thread while #register / #release run
+    # on a pool thread, hence the mutex.
+    class ClaimBeat
+      def initialize
+        @mutex = Mutex.new
+        @claims = []
+      end
+
+      def register(event_id, handler_class)
+        claim = [event_id, handler_class]
+        @mutex.synchronize { @claims << claim unless @claims.include?(claim) }
+        self
+      end
+
+      def release(event_id, handler_class)
+        @mutex.synchronize { @claims.delete([event_id, handler_class]) }
+        self
+      end
+
+      def size
+        @mutex.synchronize { @claims.size }
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      # Refresh every registered claim's liveness stamp. Returns the number of
+      # claims touched. No-op on a legacy schema: without `completed_at` there
+      # are no pending claims to keep alive, and Handler's single-phase
+      # fallback never consults the age.
+      #
+      # A claim that fails to update is logged and skipped rather than raised:
+      # this runs inside the visibility heartbeat's beat, and one unwritable
+      # row must not cost every other in-flight message its VT extension.
+      def touch!
+        return 0 unless ProcessedEvent.completion_column?
+
+        now = Time.now.utc
+        @mutex.synchronize { @claims.dup }.count { |event_id, handler_class| touch(event_id, handler_class, now) }
+      end
+
+      private
+
+      def touch(event_id, handler_class, now)
+        ProcessedEvent
+          .where(event_id: event_id, handler_class: handler_class, completed_at: nil)
+          .update_all(processed_at: now)
+        true
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus] Could not refresh idempotency claim #{handler_class}/#{event_id}: #{e.class}: #{e.message}"
+        end
+        false
+      end
+    end
+  end
+end

data/lib/pgbus/event_bus/handler.rb

@@ -17,8 +17,20 @@ module Pgbus
         end
       end
 
-      def process(message)
-        with_rails_executor { process!(message) }
+      # Outcome of the two-phase claim. `age` is how long the losing delivery
+      # found the existing claim to have been silent, in seconds (nil unless
+      # the claim was pending).
+      ClaimResult = Data.define(:status, :age) do
+        def granted?
+          status == :claimed
+        end
+      end
+
+      # @param claim_beat [ClaimBeat, nil] the message's claim-liveness beat,
+      #   supplied by Process::Consumer. Absent for a hand-rolled caller: the
+      #   handler still runs, its claim simply ages from the claim instant.
+      def process(message, claim_beat: nil)
+        with_rails_executor { process!(message, claim_beat) }
       end
 
       def handle(event)
@@ -27,12 +39,18 @@ module Pgbus
 
       private
 
-      def process!(message)
+      def process!(message, claim_beat = nil)
         raw = JSON.parse(message.message)
         event = build_event(raw)
         routing_key = raw.dig("headers", "routing_key") || raw["routing_key"]
 
-        return :skipped if self.class.idempotent? && !claim_idempotency?(event.event_id)
+        if self.class.idempotent?
+          claim = claim_idempotency(event.event_id)
+          unless claim.granted?
+            instrument_skip(claim, event, message, routing_key)
+            return :skipped
+          end
+        end
 
         instrument_payload = {
           event_id: event.event_id,
@@ -42,11 +60,13 @@ module Pgbus
           read_ct: message.read_ct.to_i,
           msg_id: message.msg_id.to_i
         }
-        Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
-          # Publisher's Current attributes (issue #431) are set for the handler
-          # and reverted after (CurrentAttributes#set semantics); the Rails
-          # executor wrap above additionally resets at completion.
-          Pgbus::CurrentAttributes.restore(event.context) { handle(event) }
+        with_claim_beat(claim_beat, event.event_id) do
+          Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
+            # Publisher's Current attributes (issue #431) are set for the handler
+            # and reverted after (CurrentAttributes#set semantics); the Rails
+            # executor wrap above additionally resets at completion.
+            Pgbus::CurrentAttributes.restore(event.context) { handle(event) }
+          end
         end
         complete_claim!(event.event_id) if self.class.idempotent?
         :handled
@@ -64,7 +84,7 @@ module Pgbus
 
       # Mirrors Pgbus::ActiveJob::Executor#execute_job: wrap the handler
       # invocation in Rails.application.executor (or the reloader in dev)
-      # so AR connections leased by `claim_idempotency?` and `handle` are
+      # so AR connections leased by `claim_idempotency` and `handle` are
       # released back to the pool when this method returns. Without the
       # wrap, every consumed event leaks one AR connection on the consumer
       # thread — in dev that wedges `clear_reloadable_connections!`,
@@ -113,24 +133,32 @@ module Pgbus
 
       # Two-phase idempotency claim (issue #385). Phase 1: atomically claim
       # via INSERT ... ON CONFLICT DO NOTHING with completed_at NULL — a
-      # *pending* claim. Returns true when this delivery should run handle:
+      # *pending* claim. Returns a ClaimResult whose status is one of:
       #
-      #   - insert won → fresh claim
-      #   - insert lost, completed_at NULL → a prior attempt claimed but was
-      #     killed before finishing (SIGKILL mid-handler); re-run so the crash
-      #     doesn't silently drop the execution. Safe: PGMQ's VT means the
-      #     prior holder is dead or wedged past its timeout — the same
-      #     at-least-once window every non-idempotent handler has.
+      #   :claimed   — insert won (fresh claim), or the row was purged between
+      #                the losing insert and the read, or an existing pending
+      #                claim has gone silent for longer than the ownership
+      #                window: the holder is dead by the heartbeat's own
+      #                definition, so re-run rather than silently drop the
+      #                execution a SIGKILL interrupted.
+      #   :completed — the execution already finished. Skip.
+      #   :owned     — pending, and its liveness stamp is fresh: the holder is
+      #                still running (issue #470). Skip — running `handle`
+      #                concurrently with the holder is exactly the
+      #                double-execution `idempotent!` promises not to do. The
+      #                holder either completes (nothing lost) or fails, leaving
+      #                its own message for VT redelivery to recover.
+      #   :cached    — a completed execution already in this process's memory.
       #
-      # Returns false (skip) only for a *completed* execution. Phase 2 is
-      # complete_claim! after handle returns; only completed executions enter
-      # the in-memory dedup cache.
+      # Phase 2 is complete_claim! after handle returns; only completed
+      # executions enter the in-memory dedup cache.
       #
       # Legacy fallback: without the completed_at column (upgraded gem,
-      # not-yet-migrated table) this degrades to the old single-phase claim.
-      def claim_idempotency?(event_id)
+      # not-yet-migrated table) this degrades to the old single-phase claim,
+      # which has no pending state and therefore no ownership question.
+      def claim_idempotency(event_id)
         cache_key = dedup_key(event_id)
-        return false if self.class.dedup_cache.seen?(cache_key)
+        return ClaimResult.new(status: :cached, age: nil) if self.class.dedup_cache.seen?(cache_key)
 
         result = ProcessedEvent.insert(
           { event_id: event_id, handler_class: self.class.name, processed_at: Time.now.utc },
@@ -139,18 +167,79 @@ module Pgbus
 
         unless ProcessedEvent.completion_column?
           self.class.dedup_cache.mark!(cache_key)
-          return result.rows.any?
+          return ClaimResult.new(status: result.rows.any? ? :claimed : :completed, age: nil)
         end
 
-        return true if result.rows.any?
+        return ClaimResult.new(status: :claimed, age: nil) if result.rows.any?
+
+        inspect_existing_claim(event_id, cache_key)
+      end
+
+      # The insert lost, so a row exists (or existed). `pick` returns nil for
+      # the whole row when it has since been purged — not a pending claim,
+      # nothing is running, so claim it.
+      def inspect_existing_claim(event_id, cache_key)
+        completed_at, processed_at = ProcessedEvent
+                                     .where(event_id: event_id, handler_class: self.class.name)
+                                     .pick(:completed_at, :processed_at)
+
+        if completed_at
+          self.class.dedup_cache.mark!(cache_key)
+          return ClaimResult.new(status: :completed, age: nil)
+        end
+
+        return ClaimResult.new(status: :claimed, age: nil) if processed_at.nil?
+
+        age = Time.now.utc - processed_at.to_time.utc
+        return ClaimResult.new(status: :owned, age: age) if age < claim_ownership_window
+
+        ClaimResult.new(status: :claimed, age: age)
+      end
+
+      # How long a pending claim may stay silent before its holder counts as
+      # dead. ClaimBeat refreshes a live claim from the visibility heartbeat,
+      # which lands every extension inside [interval, 1.5 * interval] of the
+      # previous one — two intervals leaves margin for a late beat without
+      # stretching the window past the visibility timeout it rides on.
+      #
+      # With the heartbeat disabled a claim is never refreshed, so the window
+      # degrades to "roughly the first two thirds of one visibility timeout
+      # after the claim" — a redelivery, which cannot arrive before the VT has
+      # lapsed, still re-runs exactly as it did before issue #470.
+      def claim_ownership_window
+        Pgbus.configuration.effective_visibility_heartbeat_interval * 2
+      end
 
-        completed_at = ProcessedEvent
-                       .where(event_id: event_id, handler_class: self.class.name)
-                       .pick(:completed_at)
-        return true if completed_at.nil? # pending claim (or purged row) → re-run
+      # Register this claim with the message's beat for exactly the duration of
+      # handle: before it, there is nothing to keep alive; after it,
+      # complete_claim! owns the row and a beat touching processed_at would
+      # race the completion stamp.
+      def with_claim_beat(claim_beat, event_id)
+        return yield unless claim_beat && self.class.idempotent? && ProcessedEvent.completion_column?
+
+        claim_beat.register(event_id, self.class.name)
+        begin
+          yield
+        ensure
+          claim_beat.release(event_id, self.class.name)
+        end
+      end
 
-        self.class.dedup_cache.mark!(cache_key)
-        false
+      # A skip used to be silent, which made an over-eager re-run (issue #470)
+      # invisible in production: nothing distinguished "deduplicated" from
+      # "deferred to a live holder". The claim age and read_ct are what tell
+      # an operator which one happened.
+      def instrument_skip(claim, event, message, routing_key)
+        Instrumentation.instrument(
+          "pgbus.event_skipped",
+          event_id: event.event_id,
+          handler: self.class.name,
+          routing_key: routing_key,
+          reason: claim.status,
+          claim_age: claim.age,
+          read_ct: message.read_ct.to_i,
+          msg_id: message.msg_id.to_i
+        )
       end
 
       # Phase 2: stamp the claim completed and only then admit it to the
@@ -165,11 +254,11 @@ module Pgbus
       # The stamp is an idempotent `SET completed_at = <now>`, so repeating a
       # statement that may already have committed is safe.
       #
-      # Phase 1 (claim_idempotency?) is deliberately NOT wrapped. Its INSERT
+      # Phase 1 (claim_idempotency) is deliberately NOT wrapped. Its INSERT
       # may have committed before the socket died, and on a legacy schema the
       # retry's empty `result.rows` would read as "someone else owns this
-      # claim" and return false — turning a recoverable drop into a silently
-      # skipped event. VT redelivery is the correct recovery there.
+      # claim" and report :completed — turning a recoverable drop into a
+      # silently skipped event. VT redelivery is the correct recovery there.
       def complete_claim!(event_id)
         return unless ProcessedEvent.completion_column?
 

data/lib/pgbus/event_bus/publisher.rb

@@ -25,7 +25,7 @@ module Pgbus
           Pgbus::Testing.store.push_event(event)
 
           if Pgbus::Testing.inline? && delay.to_i <= 0
-            Pgbus::EventBus::Registry.instance.handlers_for(routing_key).each do |subscriber|
+            Pgbus::EventBus::Registry.instance.subscribers_matching(routing_key).each do |subscriber|
               Pgbus::CurrentAttributes.restore(event.context) { subscriber.handler_class.new.handle(event) }
             end
           end

data/lib/pgbus/event_bus/registry.rb

@@ -62,7 +62,30 @@ module Pgbus
         end
       end
 
-      def handlers_for(routing_key)
+      # Subscribers a message read from +queue_name+ must be dispatched to
+      # (issue #469). Every subscriber gets its own queue, so a topic with N
+      # matching subscribers produces N queue copies of each event; selecting by
+      # pattern alone fanned every copy out to every match, running each handler
+      # N times per event — and, across hosts, concurrently. Ownership is the
+      # primary filter; the pattern check still applies because a routing key
+      # the owner's pattern does not match means a stale pgmq.topic_bindings
+      # row, and a stale binding must not run the handler.
+      #
+      # +queue_name+ is required on purpose: a keyword-less call would silently
+      # restore the fan-out this closed. Callers that genuinely want the
+      # pattern view (the Testing inline/drain paths, which never touch a
+      # queue) use #subscribers_matching.
+      def handlers_for(routing_key, queue_name:)
+        @subscribers.select do |s|
+          s.queue_name == queue_name && matches?(s.pattern, routing_key)
+        end
+      end
+
+      # Pattern-only selection, with no queue in play. Used by the Testing
+      # inline/drain paths, where the event never reaches PGMQ and each matching
+      # subscriber is invoked exactly once — the same per-subscriber delivery
+      # count owner-only dispatch produces in production.
+      def subscribers_matching(routing_key)
         @subscribers.select { |s| matches?(s.pattern, routing_key) }
       end
 

data/lib/pgbus/instrumentation.rb

@@ -20,6 +20,10 @@ module Pgbus
   #                                  payload: queue, job_class, msg_id, vt, extensions
   #   pgbus.event_processed        — event handler succeeded
   #   pgbus.event_failed           — event handler raised; carries :exception_object
+  #   pgbus.event_unrouted         — a consumer read an event from a queue no
+  #                                  subscriber in this process owns (stale topic
+  #                                  binding); the message is archived
+  #                                  payload: queue_name, routing_key
   #   pgbus.stream.broadcast       — stream broadcast (sync or deferred)
   #   pgbus.outbox.publish         — outbox row created
   #   pgbus.recurring.enqueue      — scheduler enqueued a due recurring task