postburner 1.0.0.pre.11 → 1.0.0.pre.12

data/lib/postburner/configuration.rb

@@ -22,6 +22,7 @@ module Postburner
   class Configuration
     # Global settings
     attr_accessor :beanstalk_url, :logger, :default_queue, :default_priority, :default_ttr
+    attr_accessor :default_scheduler_interval, :default_scheduler_priority
 
     # Worker-specific settings (loaded for a single worker)
     attr_accessor :worker_config
@@ -32,6 +33,8 @@ module Postburner
     # @option options [String] :default_queue Default queue name (default: 'default')
     # @option options [Integer] :default_priority Default job priority (default: 65536, lower = higher priority)
     # @option options [Integer] :default_ttr Default time-to-run in seconds (default: 300)
+    # @option options [Integer] :default_scheduler_interval Scheduler check interval in seconds (default: 300)
+    # @option options [Integer] :default_scheduler_priority Scheduler job priority (default: 100)
     # @option options [Hash] :worker_config Worker configuration hash with keys:
     #   - :name [String] Worker name
     #   - :queues [Array<String>] Queue/tube names to process
@@ -39,6 +42,7 @@ module Postburner
     #   - :threads [Integer] Number of threads per fork
     #   - :gc_limit [Integer, nil] Jobs to process before restart (nil = unlimited)
     #   - :timeout [Integer] Reserve command timeout in seconds (1-10, default: 3)
+    #   - :shutdown_timeout [Integer] Seconds to wait for graceful shutdown (default: default_ttr)
     #
     def initialize(options = {})
       @beanstalk_url = options[:beanstalk_url] || ENV['BEANSTALK_URL'] || 'beanstalk://localhost:11300'
@@ -46,13 +50,16 @@ module Postburner
       @default_queue = options[:default_queue] || 'default'
       @default_priority = options[:default_priority] || 65536
       @default_ttr = options[:default_ttr] || 300
+      @default_scheduler_interval = options[:default_scheduler_interval] || 300
+      @default_scheduler_priority = options[:default_scheduler_priority] || 100
       @worker_config = options[:worker_config] || {
         name: 'default',
         queues: ['default'],
         forks: 0,
         threads: 1,
         gc_limit: nil,
-        timeout: 3
+        timeout: 3,
+        shutdown_timeout: @default_ttr
       }
     end
 
@@ -90,13 +97,15 @@ module Postburner
     #     default_threads: 10
     #     default_gc_limit: 5000
     #     default_ttr: 300
+    #     default_shutdown_timeout: 300  # Defaults to default_ttr if not set
     #     workers: # <- worker configs
     #       imports: # <- worker name
-    #         timeout: 3       # Reserve timeout in seconds (1-10, default: 3)
-    #                          # Lower values enable faster graceful shutdowns
-    #         forks: 4         # Overrides default_forks
-    #         threads: 1       # Overrides default_threads
-    #         gc_limit: 500    # Overrides default_gc_limit
+    #         timeout: 3           # Reserve timeout in seconds (1-10, default: 3)
+    #                              # Lower values enable faster graceful shutdowns
+    #         forks: 4             # Overrides default_forks
+    #         threads: 1           # Overrides default_threads
+    #         gc_limit: 500        # Overrides default_gc_limit
+    #         shutdown_timeout: 600  # Wait 10 min for long imports to finish
     #         queues:
     #           - imports
     #           - data_processing
@@ -135,13 +144,15 @@ module Postburner
       worker_yaml = workers[worker_name]
 
       # Build worker_config hash - worker-level overrides env-level defaults
+      default_ttr = env_config['default_ttr'] || 300
       worker_config = {
         name: worker_name,
         queues: worker_yaml['queues'] || ['default'],
         forks: worker_yaml['forks'] || env_config['default_forks'] || 0,
         threads: worker_yaml['threads'] || env_config['default_threads'] || 1,
         gc_limit: worker_yaml['gc_limit'] || env_config['default_gc_limit'],
-        timeout: worker_yaml['timeout'] || 3
+        timeout: worker_yaml['timeout'] || 3,
+        shutdown_timeout: worker_yaml['shutdown_timeout'] || env_config['default_shutdown_timeout'] || default_ttr
       }
 
       options = {
@@ -149,6 +160,8 @@ module Postburner
         default_queue: env_config['default_queue'],
         default_priority: env_config['default_priority'],
         default_ttr: env_config['default_ttr'],
+        default_scheduler_interval: env_config['default_scheduler_interval'],
+        default_scheduler_priority: env_config['default_scheduler_priority'],
         worker_config: worker_config
       }
 
@@ -232,6 +245,20 @@ module Postburner
     def expanded_tube_names(env = nil)
       queue_names.map { |q| expand_tube_name(q, env) }
     end
+
+    # Returns the scheduler tube name with environment prefix.
+    #
+    # @param env [String, nil] Environment name (defaults to Rails.env)
+    #
+    # @return [String] Expanded scheduler tube name
+    #
+    # @example
+    #   config.scheduler_tube_name
+    #   # => 'postburner.production.scheduler'
+    #
+    def scheduler_tube_name(env = nil)
+      expand_tube_name(Postburner::Scheduler::SCHEDULER_TUBE_NAME, env)
+    end
   end
 
   # Returns the global configuration instance.
@@ -242,6 +269,15 @@ module Postburner
     @configuration ||= Configuration.new
   end
 
+  # Sets the global configuration instance.
+  #
+  # @param config [Configuration] Configuration to use globally
+  # @return [Configuration]
+  #
+  def self.configuration=(config)
+    @configuration = config
+  end
+
   # Configures Postburner via block.
   #
   # @yield [config] Configuration instance

data/lib/postburner/connection.rb

@@ -5,6 +5,7 @@ module Postburner
   #
   # Provides a simplified interface to Beanstalkd via Beaneater, with
   # automatic connection management and reconnection on failures.
+  # Each worker thread creates its own connection instance for thread safety.
   #
   # @example Direct usage
   #   conn = Postburner::Connection.new
@@ -95,8 +96,8 @@ module Postburner
     # For user-facing output, use Postburner.clear_jobs! instead.
     #
     # SAFETY: Only allows clearing tubes that are defined in the loaded
-    # configuration (watched_tube_names). This prevents accidentally clearing
-    # tubes from other applications or environments.
+    # configuration (watched_tube_names) or the scheduler tube. This prevents
+    # accidentally clearing tubes from other applications or environments.
     #
     # @param tube_names [Array<String>, nil] Array of tube names to clear, or nil to only collect stats
     #
@@ -122,16 +123,16 @@ module Postburner
     def clear_tubes!(tube_names = nil)
       ensure_connected!
 
-      # Validate that tubes to clear are in the loaded configuration
+      # Validate that tubes to clear are in the loaded configuration (or scheduler tube)
       if tube_names&.any?
-        watched = Postburner.watched_tube_names
-        invalid_tubes = tube_names - watched
+        allowed = Postburner.watched_tube_names + [Postburner.scheduler_tube_name]
+        invalid_tubes = tube_names - allowed
 
         if invalid_tubes.any?
           raise ArgumentError, <<~ERROR
             Cannot clear tubes not in configuration.
             Invalid tubes: #{invalid_tubes.join(', ')}
-            Configured tubes: #{watched.join(', ')}
+            Configured tubes: #{allowed.join(', ')}
           ERROR
         end
       end

data/lib/postburner/runner.rb

@@ -17,7 +17,12 @@ module Postburner
   #   runner = Postburner::Runner.new(options)
   #   runner.run
   #
+  # @see Postburner::Worker
+  # @see Postburner::Configuration
+  #
   class Runner
+    # @!attribute [r] options
+    #   @return [Hash] The runner options
     attr_reader :options
 
     # Initialize runner with options.
@@ -50,10 +55,15 @@ module Postburner
 
     # Load configuration from YAML file.
     #
+    # Sets the global {Postburner.configuration} after loading.
+    #
     # @return [Postburner::Configuration]
+    # @api private
     def load_configuration
       config_path = File.expand_path(options[:config], root_directory)
-      Postburner::Configuration.load_yaml(config_path, options[:env], options[:worker])
+      config = Postburner::Configuration.load_yaml(config_path, options[:env], options[:worker])
+      Postburner.configuration = config
+      config
     rescue ArgumentError => e
       logger.error "[Postburner] ERROR: #{e.message}"
       exit 1
@@ -61,8 +71,12 @@ module Postburner
 
     # Filter configuration to only include specified queues.
     #
+    # Validates that all specified queues exist in config and exits
+    # with error if unknown queues are specified.
+    #
     # @param config [Postburner::Configuration]
     # @return [void]
+    # @api private
     def filter_queues(config)
       # Validate that all specified queues exist in config
       invalid_queues = options[:queues] - config.queue_names
@@ -81,11 +95,15 @@ module Postburner
     #
     # @param config [Postburner::Configuration]
     # @return [void]
+    # @api private
     def log_configuration(config)
       config_path = File.expand_path(options[:config], root_directory)
       config.logger.info "[Postburner] Configuration: #{config_path}"
       config.logger.info "[Postburner] Environment: #{options[:env]}"
-      config.logger.info "[Postburner] Worker: #{options[:worker] || '(auto-selected)'}" if options[:worker] || options[:queues].nil?
+      if options[:worker] || options[:queues].nil?
+        worker_label = options[:worker] || "(auto-selected: #{config.worker_config[:name]})"
+        config.logger.info "[Postburner] Worker: #{worker_label}"
+      end
       config.logger.info "[Postburner] Queues: #{config.queue_names.join(', ')}"
       wc = config.worker_config
       config.logger.info "[Postburner] Worker config: forks=#{wc[:forks]}, threads=#{wc[:threads]}, gc_limit=#{wc[:gc_limit] || 'none'}, timeout=#{wc[:timeout]}s"
@@ -96,6 +114,7 @@ module Postburner
     # Uses Rails.root when Rails is defined, otherwise falls back to current directory.
     #
     # @return [String] Root directory path
+    # @api private
     def root_directory
       if defined?(Rails) && Rails.respond_to?(:root)
         Rails.root.to_s
@@ -108,14 +127,18 @@ module Postburner
     #
     # @param config [Postburner::Configuration]
     # @return [void]
+    # @api private
     def start_worker(config)
-      worker = Postburner::Workers::Worker.new(config)
+      worker = Postburner::Worker.new(config)
       worker.start
     end
 
     # Returns logger for error reporting during initialization.
     #
+    # Falls back to stderr when Rails is not available.
+    #
     # @return [Logger]
+    # @api private
     def logger
       if defined?(Rails)
         Rails.logger

data/lib/postburner/scheduler.rb

@@ -0,0 +1,427 @@
+# frozen_string_literal: true
+
+require 'postburner/advisory_lock'
+
+module Postburner
+  # Lightweight scheduler that acts as a safety net for recurring job execution.
+  #
+  # Unlike traditional schedulers that poll for due jobs, Postburner uses **immediate
+  # enqueue** where executions are created and immediately queued to Beanstalkd's
+  # delayed queue. The scheduler acts as a **watchdog safety net** to ensure every
+  # schedule has a future execution queued.
+  #
+  # ## Architecture
+  #
+  # This class is NOT persisted to the database. It's instantiated on-the-fly by
+  # workers when they reserve a watchdog job from the scheduler tube. The watchdog
+  # is ephemeral data in Beanstalkd with this payload:
+  #
+  #   { "scheduler": true, "interval": 300 }
+  #
+  # No dedicated scheduler process is needed - existing workers handle everything.
+  #
+  # ## Watchdog Pattern
+  #
+  # 1. Workers automatically watch the 'scheduler' tube
+  # 2. On reserve timeout, workers check if watchdog exists and create if missing
+  # 3. When worker reserves watchdog, it instantiates Postburner::Scheduler
+  # 4. Scheduler executes with PostgreSQL advisory lock for coordination
+  # 5. After completion, watchdog re-queues itself with delay for next interval
+  #
+  # ## Safety Net Functions
+  #
+  # The watchdog performs three safety net functions:
+  #
+  # 1. **Auto-bootstrap**: Creates first execution for schedules that haven't been started
+  # 2. **Future execution guarantee**: Ensures each schedule has a future execution queued
+  # 3. **Orphan cleanup**: Enqueues any pending executions that weren't properly queued
+  #
+  # Note: For Postburner::Job schedules, a before_attempt callback creates the next
+  # execution when the current job runs, providing immediate pickup without waiting
+  # for the watchdog. The watchdog is just the safety net.
+  #
+  # ## Configuration
+  #
+  # Add to config/postburner.yml:
+  #
+  #   production:
+  #     default_scheduler_interval: 300  # Check every 5 minutes (default)
+  #     default_scheduler_priority: 100  # Watchdog priority (default)
+  #
+  # The interval primarily affects:
+  # - How quickly new schedules are auto-bootstrapped (if you don't call start!)
+  # - Recovery time if an execution somehow fails to enqueue
+  # - How often last_audit_at is updated for monitoring
+  #
+  # Since executions are enqueued immediately to Beanstalkd's delayed queue, the
+  # watchdog interval doesn't affect execution timing - only the safety net checks.
+  #
+  # ## Execution Flow
+  #
+  # 1. Worker reserves watchdog from scheduler tube
+  # 2. Instantiates Scheduler with interval from payload
+  # 3. Scheduler#perform acquires PostgreSQL advisory lock
+  # 4. Processes all enabled schedules:
+  #    - Auto-bootstraps unstarted schedules (creates + enqueues first execution)
+  #    - Ensures future execution exists (creates + enqueues if missing)
+  #    - Enqueues any orphaned pending executions
+  #    - Updates last_audit_at timestamp
+  # 5. Re-queues watchdog with delay for next interval
+  #
+  # ## Observability
+  #
+  # Monitor scheduler health via last_audit_at:
+  #
+  #   stale = Postburner::Schedule.enabled
+  #     .where('last_audit_at < ?', 15.minutes.ago)
+  #     .or(Postburner::Schedule.where(last_audit_at: nil))
+  #
+  # @example Watchdog payload in Beanstalkd
+  #   {
+  #     "scheduler": true,
+  #     "interval": 300
+  #   }
+  #
+  # @example Manual watchdog creation (usually automatic)
+  #   Postburner::Scheduler.enqueue_watchdog(interval: 300, priority: 100)
+  #
+  # @see Postburner::Schedule
+  # @see Postburner::ScheduleExecution
+  #
+  class Scheduler
+    SCHEDULER_TUBE_NAME = 'scheduler'
+    DEFAULT_INTERVAL = 300 # 5 minutes
+    DEFAULT_PRIORITY = 100 # Lower number = higher priority
+
+    attr_reader :interval, :logger
+
+    # Initialize a new scheduler instance.
+    #
+    # The scheduler is instantiated by workers when they reserve a watchdog job
+    # from the scheduler tube. It's not persisted - each run creates a new instance.
+    #
+    # @param interval [Integer] Seconds until next run (default: 300)
+    # @param logger [Logger, nil] Logger instance (default: Rails.logger or stdout)
+    #
+    # @example
+    #   scheduler = Postburner::Scheduler.new(interval: 300)
+    #   scheduler.perform
+    #
+    def initialize(interval: DEFAULT_INTERVAL, logger: nil)
+      @interval = interval
+      @logger = logger || (defined?(Rails) ? Rails.logger : Logger.new($stdout))
+    end
+
+    # Execute the scheduler.
+    #
+    # Processes all enabled schedules with PostgreSQL advisory lock coordination
+    # to prevent concurrent execution across multiple workers. After processing,
+    # automatically re-queues the watchdog for the next run.
+    #
+    # The scheduler performs two main functions:
+    # 1. Auto-bootstrap new schedules (create first execution if not started)
+    # 2. Ensure each schedule has a future execution queued
+    # 3. Enqueue any orphaned pending executions that weren't properly queued
+    #
+    # @return [void]
+    #
+    # @example Called by worker
+    #   # Worker reserves watchdog job with payload:
+    #   # { "scheduler" => true, "interval" => 300 }
+    #   scheduler = Postburner::Scheduler.new(interval: 300)
+    #   scheduler.perform
+    #
+    def perform
+      logger.info "[Postburner::Scheduler] Starting scheduler run"
+
+      # Use advisory lock to coordinate multiple workers
+      acquired = Postburner::AdvisoryLock.with_lock(AdvisoryLock::SCHEDULER_LOCK_KEY, blocking: false) do
+        process_all_schedules
+        true
+      end
+
+      if acquired
+        logger.info "[Postburner::Scheduler] Scheduler run complete"
+      else
+        logger.info "[Postburner::Scheduler] Could not acquire lock, skipping"
+      end
+    ensure
+      # Always re-queue watchdog for next run
+      requeue_watchdog
+    end
+
+    # Class method to enqueue watchdog to Beanstalkd
+    # Mutex for coordinating watchdog checks across threads
+    WATCHDOG_MUTEX = Mutex.new
+    @watchdog_last_checked_at = nil
+    @watchdog_check_failed_at = nil
+
+    class << self
+      attr_accessor :watchdog_last_checked_at, :watchdog_check_failed_at
+    end
+
+    # Ensure a scheduler watchdog exists in the queue.
+    #
+    # Uses process-level mutex coordination so only one thread checks at a time.
+    # Called by workers on reserve timeout to automatically recreate watchdog
+    # if it's missing (e.g., after Beanstalkd restart or watchdog expiration).
+    #
+    # Implements throttling:
+    # - Skips check if successful check within last 60 seconds
+    # - Skips check if failed check within last 60 seconds
+    # - Only one thread can check at a time (mutex)
+    #
+    # @param connection [Postburner::Connection] Existing beanstalkd connection
+    # @return [void]
+    #
+    # @example Called by worker on timeout
+    #   Postburner.connected do |conn|
+    #     Postburner::Scheduler.ensure_watchdog!(connection: conn)
+    #   end
+    #
+    def self.ensure_watchdog!(connection:)
+      # Quick check without lock - skip if recently checked
+      return if watchdog_last_checked_at && Time.current - watchdog_last_checked_at < 60
+      return if watchdog_check_failed_at && Time.current - watchdog_check_failed_at < 60
+
+      # Try to acquire lock, skip if another thread is checking
+      return unless WATCHDOG_MUTEX.try_lock
+
+      begin
+        # Double-check after acquiring lock
+        return if watchdog_last_checked_at && Time.current - watchdog_last_checked_at < 60
+
+        if watchdog_exists?(connection: connection)
+          self.watchdog_last_checked_at = Time.current
+          return
+        end
+
+        enqueue_watchdog
+        self.watchdog_last_checked_at = Time.current
+        self.watchdog_check_failed_at = nil
+      rescue => e
+        self.watchdog_check_failed_at = Time.current
+        Rails.logger.error "[Postburner::Scheduler] Watchdog check failed, will retry in 60s: #{e.message}"
+      ensure
+        WATCHDOG_MUTEX.unlock
+      end
+    end
+
+    # Enqueue a new scheduler watchdog job.
+    #
+    # Creates a watchdog job in the scheduler tube with a delay equal to the interval.
+    # The watchdog will execute after the delay, process all schedules, and re-queue itself.
+    #
+    # Reads interval and priority from configuration if not provided:
+    # - default_scheduler_interval (default: 300 seconds)
+    # - default_scheduler_priority (default: 100)
+    #
+    # @param interval [Integer, nil] Seconds until next run (default: from config)
+    # @param priority [Integer, nil] Beanstalkd priority (default: from config)
+    # @return [Hash] Beanstalkd response with :status and :id keys
+    #
+    # @example Enqueue with defaults
+    #   Postburner::Scheduler.enqueue_watchdog
+    #   # => { status: "INSERTED", id: 12345 }
+    #
+    # @example Enqueue with custom interval
+    #   Postburner::Scheduler.enqueue_watchdog(interval: 60, priority: 0)
+    #
+    def self.enqueue_watchdog(interval: nil, priority: nil)
+      interval ||= Postburner.configuration.default_scheduler_interval || DEFAULT_INTERVAL
+      priority ||= Postburner.configuration.default_scheduler_priority || DEFAULT_PRIORITY
+
+      payload = {
+        'scheduler' => true,
+        'interval' => interval
+      }
+
+      tube_name = Postburner.scheduler_tube_name
+      response = nil
+
+      Postburner.connected do |conn|
+        response = conn.tubes[tube_name].put(
+          JSON.generate(payload),
+          pri: priority,
+          delay: interval,
+          ttr: 120 # 2 minutes to complete
+        )
+      end
+
+      if response[:status] == "INSERTED"
+        runs_at = Time.current + interval
+        Rails.logger.info "[Postburner::Scheduler] Inserted watchdog: #{response[:id]} (#{Time.current.iso8601}, delay: #{interval}s (#{runs_at.iso8601}), tube: #{tube_name})"
+      else
+        Rails.logger.error "[Postburner::Scheduler] Failed to insert watchdog: #{response.inspect} (delay: #{interval}s, tube: #{tube_name})"
+      end
+
+      response
+    end
+
+    # Check if scheduler watchdog exists in queue.
+    #
+    # Peeks both the delayed and ready queues in the scheduler tube.
+    # Returns true if watchdog exists in either state.
+    #
+    # @param connection [Postburner::Connection] Existing beanstalkd connection
+    # @return [Boolean] true if watchdog exists (delayed or ready), false otherwise
+    #
+    # @example Check for watchdog
+    #   Postburner.connected do |conn|
+    #     exists = Postburner::Scheduler.watchdog_exists?(connection: conn)
+    #     puts "Watchdog present" if exists
+    #   end
+    #
+    def self.watchdog_exists?(connection:)
+      tube_name = Postburner.scheduler_tube_name
+      tube = connection.beanstalk.tubes[tube_name]
+
+      # Peek is lighter than stats
+      delayed = tube.peek(:delayed) rescue nil
+      ready = tube.peek(:ready) rescue nil
+
+      delayed.present? || ready.present?
+    rescue Beaneater::NotFoundError
+      false
+    end
+
+    private
+
+    # Process all enabled schedules.
+    #
+    # Iterates through all enabled schedules and calls process_schedule for each.
+    # Logs count of successful and failed schedule processing.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def process_all_schedules
+      processed_count = 0
+      failed_count = 0
+
+      Postburner::Schedule.enabled.find_each do |schedule|
+        begin
+          process_schedule(schedule)
+          processed_count += 1
+        rescue => e
+          logger.error "[Postburner::Scheduler] Failed to process schedule '#{schedule.name}': #{e.class} - #{e.message}"
+          logger.error e.backtrace.join("\n")
+          failed_count += 1
+        end
+      end
+
+      logger.info "[Postburner::Scheduler] Processed #{processed_count} schedules, #{failed_count} failed"
+    end
+
+    # Process a single schedule.
+    #
+    # The watchdog performs three safety net functions:
+    # 1. Auto-bootstrap: Create first execution if schedule hasn't been started
+    # 2. Ensure there's always a future execution (creates + enqueues if missing)
+    # 3. Enqueue any orphaned pending executions (that somehow weren't enqueued)
+    #
+    # Note: We check for future executions FIRST, then clean up any orphans.
+    # This ensures newly created executions are available for processing in the
+    # same run if they happen to be due.
+    #
+    # @param schedule [Postburner::Schedule] The schedule to process
+    # @return [void]
+    #
+    # @api private
+    #
+    def process_schedule(schedule)
+      # Auto-bootstrap: create first execution if schedule hasn't been started
+      # This will create the execution AND enqueue it to Beanstalkd
+      unless schedule.started?
+        logger.info "[Postburner::Scheduler] Bootstrapping schedule '#{schedule.name}'"
+        schedule.start!
+      end
+
+      # Safety net 1: Ensure schedule has a future execution
+      # If missing, this will create AND enqueue it to Beanstalkd's delayed queue
+      ensure_future_execution!(schedule)
+
+      # Safety net 2: Find any orphaned pending executions and enqueue them
+      # This should rarely happen - only if enqueue! previously failed
+      execution_count = 0
+      schedule.executions.due.find_each do |execution|
+        begin
+          logger.warn "[Postburner::Scheduler] Found orphaned pending execution #{execution.id} for schedule '#{schedule.name}', enqueuing"
+          execution.enqueue!
+          execution_count += 1
+        rescue => e
+          logger.error "[Postburner::Scheduler] Failed to enqueue execution #{execution.id}: #{e.class} - #{e.message}"
+          raise
+        end
+      end
+
+      # Update last_audit_at
+      schedule.update_column(:last_audit_at, Time.current)
+
+      logger.debug "[Postburner::Scheduler] Schedule '#{schedule.name}': enqueued #{execution_count} orphaned executions" if execution_count > 0
+    end
+
+    # Ensure schedule has a future scheduled or pending execution.
+    #
+    # Uses Schedule#create_next_execution! which is idempotent and only
+    # creates an execution if none exists in the future. If no executions
+    # exist at all, bootstraps the schedule first.
+    #
+    # This is the key safety net that ensures every schedule always has
+    # at least one future execution ready to run.
+    #
+    # @param schedule [Postburner::Schedule] The schedule to ensure future execution for
+    # @return [void]
+    #
+    # @api private
+    #
+    def ensure_future_execution!(schedule)
+      # Find the most recent execution to calculate next from
+      last_execution = schedule.executions.order(run_at: :desc).first
+
+      unless last_execution
+        # No executions at all - this shouldn't happen since we bootstrap first,
+        # but handle it as a safety net
+        logger.warn "[Postburner::Scheduler] Schedule '#{schedule.name}' has no executions, bootstrapping"
+        schedule.start!
+        return
+      end
+
+      # Delegate to Schedule - it knows whether a future execution is needed
+      execution = schedule.create_next_execution!(after: last_execution)
+
+      if execution
+        logger.info "[Postburner::Scheduler] Created future execution for '#{schedule.name}'"
+      end
+    end
+
+    # Re-queue the watchdog for the next run (if not already queued).
+    #
+    # Called in the ensure block of perform to guarantee the watchdog
+    # perpetuates itself. Always reads interval from config to pick up
+    # any runtime configuration changes.
+    #
+    # If re-queueing fails, logs error but doesn't raise - workers will
+    # recreate the watchdog on next timeout via ensure_watchdog!
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def requeue_watchdog
+      Postburner.connected do |conn|
+        if self.class.watchdog_exists?(connection: conn)
+          logger.debug "[Postburner::Scheduler] Watchdog already exists, skipping re-queue"
+          return
+        end
+
+        self.class.enqueue_watchdog
+      end
+    rescue => e
+      logger.error "[Postburner::Scheduler] Failed to re-queue watchdog: #{e.class} - #{e.message}"
+      # This is critical - if watchdog isn't re-queued, scheduling stops
+      # Workers will recreate it on next timeout, but log loudly
+    end
+  end
+end