pgbus 0.0.1 → 0.1.2

data/lib/pgbus/web/data_source.rb

@@ -23,24 +23,28 @@ module Pgbus
           total_visible: total_visible,
           active_processes: processes.count,
           failed_count: failed_events_count,
-          dlq_depth: dlq_depth
+          dlq_depth: dlq_depth,
+          recurring_count: recurring_tasks_count
         }
       end
 
-      # Queues
+      # Queues — query via ActiveRecord for reliability in web processes
+      # (avoids PGMQ client connection issues when the web server uses a
+      # different connection lifecycle than the worker processes).
       def queues_with_metrics
-        metrics = @client.metrics || []
-        Array(metrics).map { |m| format_metrics(m) }
+        queue_names = connection.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+        queue_names.map { |name| queue_metrics_via_sql(name) }.compact
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error fetching queue metrics: #{e.message}" }
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching queue metrics: #{e.class}: #{e.message}" }
         []
       end
 
+      # name is the full PGMQ queue name (e.g. "pgbus_default") as returned
+      # by queues_with_metrics. No prefix is added.
       def queue_detail(name)
-        m = @client.metrics(name)
-        m ? format_metrics(m) : nil
+        queue_metrics_via_sql(name)
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error fetching queue detail for #{name}: #{e.message}" }
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching queue detail for #{name}: #{e.class}: #{e.message}" }
         nil
       end
 
@@ -63,9 +67,8 @@ module Pgbus
       end
 
       def job_detail(queue_name, msg_id)
-        full_name = Pgbus.configuration.queue_name(queue_name)
         row = connection.select_one(
-          "SELECT * FROM pgmq.q_#{sanitize_name(full_name)} WHERE msg_id = $1",
+          "SELECT * FROM pgmq.q_#{sanitize_name(queue_name)} WHERE msg_id = $1",
           "Pgbus Job Detail",
           [msg_id.to_i]
         )
@@ -76,8 +79,7 @@ module Pgbus
       end
 
       def retry_job(queue_name, msg_id)
-        full_name = Pgbus.configuration.queue_name(queue_name)
-        @client.set_visibility_timeout(full_name, msg_id.to_i, vt: 0)
+        @client.set_visibility_timeout(queue_name, msg_id.to_i, vt: 0)
       end
 
       def discard_job(queue_name, msg_id)
@@ -127,7 +129,9 @@ module Pgbus
 
         connection.transaction do
           @client.send_message(event["queue_name"], payload, headers: headers)
-          connection.execute("DELETE FROM pgbus_failed_events WHERE id = #{id.to_i}")
+          connection.exec_delete(
+            "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [id.to_i]
+          )
         end
         true
       rescue StandardError => e
@@ -136,7 +140,9 @@ module Pgbus
       end
 
       def discard_failed_event(id)
-        connection.execute("DELETE FROM pgbus_failed_events WHERE id = #{id.to_i}")
+        connection.exec_delete(
+          "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [id.to_i]
+        )
         true
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error discarding failed event #{id}: #{e.message}" }
@@ -145,18 +151,27 @@ module Pgbus
 
       def retry_all_failed
         count = 0
-        connection.select_all("SELECT * FROM pgbus_failed_events").each do |event|
-          payload = JSON.parse(event["payload"])
-          headers = event["headers"]
-          headers = JSON.parse(headers) if headers.is_a?(String)
-
-          connection.transaction do
-            @client.send_message(event["queue_name"], payload, headers: headers)
-            connection.execute("DELETE FROM pgbus_failed_events WHERE id = #{event["id"].to_i}")
+        loop do
+          batch = connection.select_all(
+            "SELECT * FROM pgbus_failed_events ORDER BY id LIMIT 100", "Pgbus Retry Batch"
+          ).to_a
+          break if batch.empty?
+
+          batch.each do |event|
+            payload = JSON.parse(event["payload"])
+            headers = event["headers"]
+            headers = JSON.parse(headers) if headers.is_a?(String)
+
+            connection.transaction do
+              @client.send_message(event["queue_name"], payload, headers: headers)
+              connection.exec_delete(
+                "DELETE FROM pgbus_failed_events WHERE id = $1", "Pgbus Delete Failed Event", [event["id"].to_i]
+              )
+            end
+            count += 1
+          rescue StandardError => e
+            Pgbus.logger.error { "[Pgbus::Web] Failed to retry event #{event["id"]}: #{e.message}" }
           end
-          count += 1
-        rescue StandardError => e
-          Pgbus.logger.error { "[Pgbus::Web] Failed to retry event #{event["id"]}: #{e.message}" }
         end
         count
       end
@@ -315,6 +330,127 @@ module Pgbus
         false
       end
 
+      # Recurring tasks
+      def recurring_tasks
+        records = RecurringTask.order(:key).to_a
+        last_runs = RecurringExecution
+                    .where(task_key: records.map(&:key))
+                    .select("task_key, MAX(run_at) AS run_at")
+                    .group(:task_key)
+                    .index_by(&:task_key)
+
+        records.map do |record|
+          last_exec = last_runs[record.key]
+          task = Recurring::Task.from_configuration(record.key,
+                                                    class: record.class_name,
+                                                    command: record.command,
+                                                    schedule: record.schedule,
+                                                    queue: record.queue_name,
+                                                    args: parse_arguments(record.arguments),
+                                                    priority: record.priority,
+                                                    description: record.description)
+
+          {
+            id: record.id,
+            key: record.key,
+            class_name: record.class_name,
+            command: record.command,
+            schedule: record.schedule,
+            human_schedule: task.human_schedule,
+            queue_name: record.queue_name,
+            priority: record.priority,
+            description: record.description,
+            enabled: record.enabled,
+            static: record.static,
+            next_run_at: task.next_time,
+            last_run_at: last_exec&.run_at,
+            created_at: record.created_at,
+            updated_at: record.updated_at
+          }
+        end
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching recurring tasks: #{e.class}: #{e.message}" }
+        []
+      end
+
+      def recurring_task(id)
+        record = RecurringTask.find_by(id: id)
+        return nil unless record
+
+        task = Recurring::Task.from_configuration(record.key,
+                                                  class: record.class_name,
+                                                  command: record.command,
+                                                  schedule: record.schedule,
+                                                  queue: record.queue_name,
+                                                  args: parse_arguments(record.arguments),
+                                                  priority: record.priority,
+                                                  description: record.description)
+
+        executions = RecurringExecution.for_task(record.key).recent(25).map do |exec|
+          { run_at: exec.run_at, created_at: exec.created_at }
+        end
+
+        {
+          id: record.id,
+          key: record.key,
+          class_name: record.class_name,
+          command: record.command,
+          schedule: record.schedule,
+          human_schedule: task.human_schedule,
+          queue_name: record.queue_name,
+          arguments: parse_arguments(record.arguments),
+          priority: record.priority,
+          description: record.description,
+          enabled: record.enabled,
+          static: record.static,
+          next_run_at: task.next_time,
+          executions: executions,
+          created_at: record.created_at,
+          updated_at: record.updated_at
+        }
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching recurring task #{id}: #{e.class}: #{e.message}" }
+        nil
+      end
+
+      def toggle_recurring_task(id)
+        record = RecurringTask.find_by(id: id)
+        return false unless record
+
+        record.update!(enabled: !record.enabled)
+        true
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error toggling recurring task #{id}: #{e.message}" }
+        false
+      end
+
+      def enqueue_recurring_task_now(id)
+        record = RecurringTask.find_by(id: id)
+        return false unless record
+
+        task = Recurring::Task.from_configuration(record.key,
+                                                  class: record.class_name,
+                                                  command: record.command,
+                                                  schedule: record.schedule,
+                                                  queue: record.queue_name,
+                                                  args: parse_arguments(record.arguments),
+                                                  priority: record.priority)
+
+        schedule = Recurring::Schedule.new(config: Pgbus.configuration)
+        schedule.enqueue_task(task, run_at: Time.now.utc)
+        true
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error enqueuing recurring task #{id}: #{e.message}" }
+        false
+      end
+
+      def recurring_tasks_count
+        RecurringTask.count
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error counting recurring tasks: #{e.message}" }
+        0
+      end
+
       # Subscriber registry
       def registered_subscribers
         EventBus::Registry.instance.subscribers.map do |s|
@@ -328,12 +464,12 @@ module Pgbus
       private
 
       def connection
-        ActiveRecord::Base.connection
+        Pgbus::ApplicationRecord.connection
       end
 
+      # name is the full PGMQ queue name (already prefixed)
       def query_queue_messages(name, limit, offset)
-        full_name = Pgbus.configuration.queue_name(name)
-        query_queue_messages_raw(full_name, limit, offset).map { |m| m.merge(queue: name) }
+        query_queue_messages_raw(name, limit, offset).map { |m| m.merge(queue: name) }
       end
 
       def query_queue_messages_raw(full_name, limit, offset)
@@ -357,15 +493,45 @@ module Pgbus
         messages.sort_by { |m| -m[:msg_id].to_i }.slice(offset, limit) || []
       end
 
-      def format_metrics(m)
+      def queue_metrics_via_sql(queue_name)
+        qtable = "q_#{sanitize_name(queue_name)}"
+        seq_name = "#{qtable}_msg_id_seq"
+
+        row = connection.select_one(<<~SQL, "Pgbus Queue Metrics")
+          WITH q_summary AS (
+            SELECT
+              count(*) AS queue_length,
+              count(CASE WHEN vt <= NOW() THEN 1 END) AS queue_visible_length,
+              EXTRACT(epoch FROM (NOW() - max(enqueued_at)))::int AS newest_msg_age_sec,
+              EXTRACT(epoch FROM (NOW() - min(enqueued_at)))::int AS oldest_msg_age_sec
+            FROM pgmq.#{qtable}
+          ),
+          all_metrics AS (
+            SELECT CASE WHEN is_called THEN last_value ELSE 0 END AS total_messages
+            FROM pgmq.#{seq_name}
+          )
+          SELECT
+            q_summary.queue_length,
+            q_summary.queue_visible_length,
+            q_summary.newest_msg_age_sec,
+            q_summary.oldest_msg_age_sec,
+            all_metrics.total_messages
+          FROM q_summary, all_metrics
+        SQL
+
+        return nil unless row
+
         {
-          name: m.queue_name.to_s,
-          queue_length: m.queue_length.to_i,
-          queue_visible_length: m.queue_visible_length.to_i,
-          oldest_msg_age_sec: m.oldest_msg_age_sec&.to_i,
-          newest_msg_age_sec: m.newest_msg_age_sec&.to_i,
-          total_messages: m.total_messages.to_i
+          name: queue_name,
+          queue_length: row["queue_length"].to_i,
+          queue_visible_length: row["queue_visible_length"].to_i,
+          oldest_msg_age_sec: row["oldest_msg_age_sec"]&.to_i,
+          newest_msg_age_sec: row["newest_msg_age_sec"]&.to_i,
+          total_messages: row["total_messages"].to_i
         }
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching metrics for #{queue_name}: #{e.class}: #{e.message}" }
+        nil
       end
 
       def format_message(row, queue_name)
@@ -399,7 +565,22 @@ module Pgbus
       end
 
       def sanitize_name(name)
-        name.gsub(/[^a-zA-Z0-9_]/, "")
+        sanitized = name.gsub(/[^a-zA-Z0-9_]/, "")
+        raise ArgumentError, "Invalid queue name: #{name.inspect}" if sanitized.empty?
+
+        sanitized
+      end
+
+      def parse_arguments(args)
+        case args
+        when Array then args
+        when String then JSON.parse(args)
+        when NilClass then []
+        else Array(args)
+        end
+      rescue JSON::ParserError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Invalid recurring task arguments JSON: #{e.message}" }
+        []
       end
     end
   end

data/lib/pgbus.rb

@@ -16,6 +16,13 @@ module Pgbus
         loader = Zeitwerk::Loader.for_gem
         loader.inflector.inflect("pgbus" => "Pgbus", "cli" => "CLI", "dsl" => "DSL")
         loader.ignore("#{__dir__}/generators")
+        loader.ignore("#{__dir__}/active_job")
+        # Register app/models for non-Rails usage (specs, standalone).
+        # When Rails is running, the Engine handles autoloading app/models.
+        unless defined?(Rails::Engine)
+          models_dir = File.expand_path("../app/models", __dir__)
+          loader.push_dir(models_dir) if File.directory?(models_dir)
+        end
         loader
       end
     end
@@ -46,4 +53,5 @@ module Pgbus
   loader.setup
 end
 
+require "active_job/queue_adapters/pgbus_adapter" if defined?(ActiveJob)
 require "pgbus/engine" if defined?(Rails::Engine)

data/lib/tasks/pgbus_pgmq.rake

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+namespace :pgbus do
+  namespace :pgmq do
+    desc "Show current PGMQ schema status (installed version, available updates)"
+    task status: :environment do
+      require "pgbus/pgmq_schema"
+
+      puts "PGMQ Schema Status"
+      puts "=" * 40
+
+      latest = Pgbus::PgmqSchema.latest_version
+      puts "Vendored version:  #{latest}"
+
+      if ActiveRecord::Base.connection.table_exists?("pgbus_pgmq_schema_versions")
+        row = ActiveRecord::Base.connection.select_one(
+          "SELECT version, install_method, installed_at FROM pgbus_pgmq_schema_versions ORDER BY installed_at DESC LIMIT 1"
+        )
+        if row
+          puts "Installed version: #{row["version"]}"
+          puts "Install method:    #{row["install_method"]}"
+          puts "Installed at:      #{row["installed_at"]}"
+
+          puts ""
+          if Gem::Version.new(row["version"]) < Gem::Version.new(latest)
+            puts "Update available! Run: rails generate pgbus:upgrade_pgmq"
+          else
+            puts "Schema is up to date."
+          end
+        else
+          puts "Installed version: unknown (no records in tracking table)"
+        end
+      else
+        # Check if pgmq schema exists at all
+        schema_exists = ActiveRecord::Base.connection.select_value(
+          "SELECT 1 FROM information_schema.schemata WHERE schema_name = 'pgmq'"
+        )
+        if schema_exists
+          puts "Installed version: unknown (installed before version tracking)"
+          puts ""
+          puts "Run: rails generate pgbus:upgrade_pgmq"
+          puts "This will add version tracking and ensure latest functions."
+        else
+          puts "PGMQ is not installed."
+          puts ""
+          puts "Run: rails generate pgbus:install"
+        end
+      end
+    end
+
+    desc "Show available vendored PGMQ versions"
+    task versions: :environment do
+      require "pgbus/pgmq_schema"
+
+      puts "Available vendored PGMQ versions:"
+      Pgbus::PgmqSchema.available_versions.each do |v|
+        marker = v == Pgbus::PgmqSchema.latest_version ? " (latest)" : ""
+        puts "  #{v}#{marker}"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -23,6 +23,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.11.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.11.1
 - !ruby/object:Gem::Dependency
   name: pgmq-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -83,21 +103,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".bun-version"
-- ".claude/commands/architect.md"
-- ".claude/commands/github-review-comments.md"
-- ".claude/commands/lfg.md"
-- ".claude/commands/review-pr.md"
-- ".claude/commands/security.md"
-- ".claude/commands/tdd.md"
-- ".claude/rules/agents.md"
-- ".claude/rules/coding-style.md"
-- ".claude/rules/git-workflow.md"
-- ".claude/rules/performance.md"
-- ".claude/rules/testing.md"
 - CHANGELOG.md
-- CLAUDE.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -109,7 +115,16 @@ files:
 - app/controllers/pgbus/jobs_controller.rb
 - app/controllers/pgbus/processes_controller.rb
 - app/controllers/pgbus/queues_controller.rb
+- app/controllers/pgbus/recurring_tasks_controller.rb
 - app/helpers/pgbus/application_helper.rb
+- app/models/pgbus/application_record.rb
+- app/models/pgbus/batch_entry.rb
+- app/models/pgbus/blocked_execution.rb
+- app/models/pgbus/process_entry.rb
+- app/models/pgbus/processed_event.rb
+- app/models/pgbus/recurring_execution.rb
+- app/models/pgbus/recurring_task.rb
+- app/models/pgbus/semaphore.rb
 - app/views/layouts/pgbus/application.html.erb
 - app/views/pgbus/dashboard/_processes_table.html.erb
 - app/views/pgbus/dashboard/_queues_table.html.erb
@@ -130,17 +145,21 @@ files:
 - app/views/pgbus/queues/_queues_list.html.erb
 - app/views/pgbus/queues/index.html.erb
 - app/views/pgbus/queues/show.html.erb
-- bun.lock
+- app/views/pgbus/recurring_tasks/_tasks_table.html.erb
+- app/views/pgbus/recurring_tasks/index.html.erb
+- app/views/pgbus/recurring_tasks/show.html.erb
 - config/routes.rb
-- docs/README.md
-- docs/switch_from_good_job.md
-- docs/switch_from_sidekiq.md
-- docs/switch_from_solid_queue.md
 - exe/pgbus
+- lib/active_job/queue_adapters/pgbus_adapter.rb
+- lib/generators/pgbus/add_recurring_generator.rb
 - lib/generators/pgbus/install_generator.rb
+- lib/generators/pgbus/templates/add_recurring_tables.rb.erb
 - lib/generators/pgbus/templates/migration.rb.erb
 - lib/generators/pgbus/templates/pgbus.yml.erb
 - lib/generators/pgbus/templates/pgbus_binstub.erb
+- lib/generators/pgbus/templates/recurring.yml.erb
+- lib/generators/pgbus/templates/upgrade_pgmq.rb.erb
+- lib/generators/pgbus/upgrade_pgmq_generator.rb
 - lib/pgbus.rb
 - lib/pgbus/active_job/adapter.rb
 - lib/pgbus/active_job/executor.rb
@@ -158,24 +177,32 @@ files:
 - lib/pgbus/event_bus/publisher.rb
 - lib/pgbus/event_bus/registry.rb
 - lib/pgbus/event_bus/subscriber.rb
+- lib/pgbus/instrumentation.rb
+- lib/pgbus/pgmq_schema.rb
+- lib/pgbus/pgmq_schema/pgmq_v1.11.0.sql
 - lib/pgbus/process/consumer.rb
 - lib/pgbus/process/dispatcher.rb
 - lib/pgbus/process/heartbeat.rb
 - lib/pgbus/process/signal_handler.rb
 - lib/pgbus/process/supervisor.rb
 - lib/pgbus/process/worker.rb
+- lib/pgbus/recurring/already_recorded.rb
+- lib/pgbus/recurring/command_job.rb
+- lib/pgbus/recurring/config_loader.rb
+- lib/pgbus/recurring/schedule.rb
+- lib/pgbus/recurring/scheduler.rb
+- lib/pgbus/recurring/task.rb
 - lib/pgbus/serializer.rb
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb
 - lib/pgbus/web/data_source.rb
-- package.json
-- sig/pgbus.rbs
+- lib/tasks/pgbus_pgmq.rake
 homepage: https://github.com/mhenrixon/pgbus
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/mhenrixon/pgbus
-  source_code_uri: https://github.com/mhenrixon/pgbus
+  source_code_uri: https://github.com/mhenrixon/pgbus/tree/main
   changelog_uri: https://github.com/mhenrixon/pgbus/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -192,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: PostgreSQL-native job processing and event bus for Rails, built on PGMQ
 test_files: []

data/.bun-version

@@ -1 +0,0 @@
-1.3.11

data/.claude/commands/architect.md

@@ -1,100 +0,0 @@
----
-description: "Coordinates development across pgbus layers. Use when planning multi-layer features, orchestrating implementation order, or designing new subsystems."
-model: claude-opus-4-6
-argument-hint: "feature or task to coordinate"
----
-
-# Pgbus Architect Mode
-
-You are now in **Architect Mode** - coordinating development across all pgbus layers.
-
-## Why This Skill Exists
-
-Pgbus spans multiple layers (PGMQ transport, ActiveJob adapter, event bus, process model, dashboard). Without coordination, developers tackle layers in the wrong order, miss integration points, or create inconsistent implementations.
-
-## Pgbus Architecture Layers
-
-```
-Layer 6: Dashboard (Web UI)          app/controllers/pgbus/, app/views/pgbus/
-Layer 5: CLI                         lib/pgbus/cli.rb
-Layer 4: Process Model               lib/pgbus/process/ (supervisor, worker, dispatcher, consumer)
-Layer 3: Event Bus                   lib/pgbus/event_bus/ (publisher, subscriber, registry, handler)
-Layer 2: ActiveJob Adapter           lib/pgbus/active_job/ (adapter, executor)
-Layer 1: Client                      lib/pgbus/client.rb (PGMQ wrapper)
-Layer 0: Configuration               lib/pgbus/configuration.rb, config_loader.rb
-```
-
-## Typical Implementation Flow
-
-1. **Configuration** - Add new config options if needed
-2. **Client** - Add PGMQ operations to the client wrapper
-3. **Adapter / Event Bus** - Build the feature's core logic
-4. **Process Model** - Add worker/consumer support
-5. **Dashboard** - Expose in the web UI via DataSource
-6. **Tests** - Coverage across all touched layers
-
-## When to Delegate vs. Do Directly
-
-**Delegate when**:
-- Multiple files across a layer need changes
-- Deep domain expertise is needed (e.g., PGMQ internals)
-- Work is clearly scoped to one layer
-
-**Handle directly when**:
-- Simple, single-file changes
-- Cross-cutting concerns affecting multiple layers
-- Quick fixes or minor adjustments
-
-## Decision Guidelines
-
-| Decision | Use When |
-|----------|----------|
-| New config option | Feature needs user-configurable behavior |
-| New Client method | New PGMQ operation needed |
-| New event handler | Business event needs processing |
-| New worker type | Different processing pattern needed |
-| Dashboard page | Users need visibility into new feature |
-| Migration change | New metadata table or PGMQ queue |
-
-## Integration Points
-
-| When working on... | Also consider... |
-|-------------------|------------------|
-| Client changes | Worker/consumer that calls it |
-| New queue type | Dead letter queue, dashboard visibility |
-| Event bus feature | Idempotency table, subscriber registry |
-| Process model | Heartbeat, supervisor restart logic |
-| Dashboard | DataSource queries, authentication |
-| Configuration | Config loader YAML, generator template |
-
-## Common Mistakes to Avoid
-
-| Wrong | Right |
-|-------|-------|
-| Start with dashboard | Start with client/adapter layer |
-| Skip configuration | Make it configurable from the start |
-| Direct PGMQ calls | Go through Client wrapper |
-| Forget DLQ | Every queue needs a dead letter strategy |
-| Skip tests | TDD -- tests first at every layer |
-| Monolith methods | Small files, focused classes |
-
-## Verification Checklist
-
-- [ ] Implementation order planned (bottom-up)
-- [ ] Dependencies between layers identified
-- [ ] PGMQ operations go through Client
-- [ ] Configuration is extensible
-- [ ] Dashboard exposes new data via DataSource
-- [ ] Tests cover all touched layers
-- [ ] `bundle exec rubocop` passes
-- [ ] `bundle exec rspec` passes
-
-## Handoff
-
-When complete, summarize:
-- Implementation plan with layer order
-- Files to create/modify per layer
-- Integration points identified
-- Architectural decisions made
-
-Now, coordinate pgbus development with this architectural perspective.