tasker-rb 0.1.1

data/lib/tasker_core/errors/common.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Errors
+    # Base error class for all TaskerCore-related errors
+    class Error < StandardError; end
+
+    # Raised when there are configuration-related issues in TaskerCore
+    class ConfigurationError < Error; end
+
+    # Base class for all TaskerCore-specific errors that occur during workflow execution
+    # Maps to the comprehensive error system in Rust orchestration/errors.rs
+    class ProceduralError < Error; end
+
+    # Raised when there are orchestration-related issues in TaskerCore
+    class OrchestrationError < Error; end
+
+    # Raised when there are database-related issues in TaskerCore
+    class DatabaseError < Error; end
+
+    # Error indicating a step failed but should be retried with backoff
+    # Maps to Rust StepExecutionError::Retryable
+    #
+    # Use this error when an operation fails due to temporary conditions like:
+    # - Network timeouts
+    # - Rate limiting (429 status)
+    # - Server errors (5xx status)
+    # - Temporary service unavailability
+    # - Resource exhaustion that may resolve
+    #
+    # @example Basic retryable error
+    #   raise TaskerCore::Errors::RetryableError, "Payment service timeout"
+    #
+    # @example With retry delay
+    #   raise TaskerCore::Errors::RetryableError.new("Rate limited", retry_after: 60)
+    #
+    # @example With context for monitoring
+    #   raise TaskerCore::Errors::RetryableError.new(
+    #     "External API unavailable",
+    #     retry_after: 30,
+    #     context: { service: 'billing_api', error_code: 503 }
+    #   )
+    class RetryableError < ProceduralError
+      # @return [Integer, nil] Suggested retry delay in seconds
+      attr_reader :retry_after
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param retry_after [Integer, nil] Suggested retry delay in seconds
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, retry_after: nil, context: {})
+        super(message)
+        @retry_after = retry_after
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'RetryableError'
+      end
+    end
+
+    # Error indicating a step failed permanently and should not be retried
+    # Maps to Rust StepExecutionError::Permanent
+    #
+    # Use this error when an operation fails due to permanent conditions like:
+    # - Invalid request data (400 status)
+    # - Authentication/authorization failures (401/403 status)
+    # - Validation errors (422 status)
+    # - Resource not found when it should exist (404 status in some contexts)
+    # - Business logic violations
+    # - Configuration errors
+    #
+    # @example Basic permanent error
+    #   raise TaskerCore::Errors::PermanentError, "Invalid user ID format"
+    #
+    # @example With error code for categorization
+    #   raise TaskerCore::Errors::PermanentError.new(
+    #     "Insufficient funds for transaction",
+    #     error_code: 'INSUFFICIENT_FUNDS'
+    #   )
+    #
+    # @example With context for monitoring
+    #   raise TaskerCore::Errors::PermanentError.new(
+    #     "User not authorized for this operation",
+    #     error_code: 'AUTHORIZATION_FAILED',
+    #     context: { user_id: 123, operation: 'admin_access' }
+    #   )
+    class PermanentError < ProceduralError
+      # @return [String, nil] Machine-readable error code for categorization
+      attr_reader :error_code
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param error_code [String, nil] Machine-readable error code
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, error_code: nil, context: {})
+        super(message)
+        @error_code = error_code
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'PermanentError'
+      end
+    end
+
+    # Error indicating a timeout occurred during step execution
+    # Maps to Rust StepExecutionError::Timeout
+    #
+    # Use this error when an operation fails due to timeout conditions:
+    # - Step execution timeout
+    # - Network request timeout
+    # - Database operation timeout
+    # - External service timeout
+    #
+    # @example Basic timeout error
+    #   raise TaskerCore::Errors::TimeoutError, "Payment processing timed out"
+    #
+    # @example With timeout duration
+    #   raise TaskerCore::Errors::TimeoutError.new(
+    #     "Database query timed out",
+    #     timeout_duration: 30
+    #   )
+    class TimeoutError < ProceduralError
+      # @return [Integer, nil] Timeout duration in seconds
+      attr_reader :timeout_duration
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param timeout_duration [Integer, nil] Timeout duration in seconds
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, timeout_duration: nil, context: {})
+        super(message)
+        @timeout_duration = timeout_duration
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'TimeoutError'
+      end
+    end
+
+    # Error indicating a network-related failure
+    # Maps to Rust StepExecutionError::NetworkError
+    #
+    # Use this error when an operation fails due to network conditions:
+    # - Connection failures
+    # - DNS resolution errors
+    # - HTTP errors (4xx/5xx when network-related)
+    # - TLS/SSL errors
+    # - Network timeouts
+    #
+    # @example Basic network error
+    #   raise TaskerCore::Errors::NetworkError, "Connection refused"
+    #
+    # @example With HTTP status code
+    #   raise TaskerCore::Errors::NetworkError.new(
+    #     "Service unavailable",
+    #     status_code: 503
+    #   )
+    class NetworkError < ProceduralError
+      # @return [Integer, nil] HTTP status code if applicable
+      attr_reader :status_code
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param status_code [Integer, nil] HTTP status code if applicable
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, status_code: nil, context: {})
+        super(message)
+        @status_code = status_code
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'NetworkError'
+      end
+    end
+
+    # Error indicating validation failed
+    # Maps to Rust OrchestrationError::ValidationError
+    #
+    # Use this error when data validation fails:
+    # - Schema validation errors
+    # - Business rule validation
+    # - Input format validation
+    # - Required field validation
+    class ValidationError < PermanentError
+      # @return [String, nil] Field that failed validation
+      attr_reader :field
+
+      # @param message [String] Error message
+      # @param field [String, nil] Field that failed validation
+      # @param error_code [String, nil] Machine-readable error code
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, field: nil, error_code: nil, context: {})
+        super(message, error_code: error_code, context: context)
+        @field = field
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'ValidationError'
+      end
+    end
+
+    # Error indicating a handler or step was not found
+    # Maps to Rust OrchestrationError::HandlerNotFound and StepHandlerNotFound
+    class NotFoundError < PermanentError
+      # @return [String, nil] Type of resource not found (handler, step, etc.)
+      attr_reader :resource_type
+
+      # @param message [String] Error message
+      # @param resource_type [String, nil] Type of resource not found
+      # @param error_code [String, nil] Machine-readable error code
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, resource_type: nil, error_code: nil, context: {})
+        super(message, error_code: error_code, context: context)
+        @resource_type = resource_type
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'NotFoundError'
+      end
+    end
+
+    # Error indicating an FFI operation failed
+    # Maps to Rust OrchestrationError::FfiBridgeError
+    class FFIError < Error
+      # @return [String, nil] FFI operation that failed
+      attr_reader :operation
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param operation [String, nil] FFI operation that failed
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, operation: nil, context: {})
+        super(message)
+        @operation = operation
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'FFIError'
+      end
+    end
+
+    # Error indicating embedded server operation failed
+    # Maps to Rust ServerError types
+    #
+    # Use this error when embedded server operations fail:
+    # - Server startup failures
+    # - Server shutdown failures
+    # - Configuration errors
+    # - Runtime errors
+    # - Server already running/not running
+    #
+    # @example Basic server error
+    #   raise TaskerCore::Errors::ServerError, "Failed to start embedded server"
+    #
+    # @example With server operation context
+    #   raise TaskerCore::Errors::ServerError.new(
+    #     "Server startup failed",
+    #     operation: 'start',
+    #     context: { bind_address: '127.0.0.1:8080', error_code: 'ADDRESS_IN_USE' }
+    #   )
+    class ServerError < Error
+      # @return [String, nil] Server operation that failed
+      attr_reader :operation
+
+      # @return [Hash] Additional context for error monitoring and debugging
+      attr_reader :context
+
+      # @param message [String] Error message
+      # @param operation [String, nil] Server operation that failed (start, stop, config, etc.)
+      # @param context [Hash] Additional context for monitoring
+      def initialize(message, operation: nil, context: {})
+        super(message)
+        @operation = operation
+        @context = context
+      end
+
+      # Get the error class name for Rust FFI compatibility
+      def error_class
+        'ServerError'
+      end
+    end
+  end
+end

data/lib/tasker_core/errors/error_classifier.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'common'
+
+module TaskerCore
+  module Errors
+    # ErrorClassifier provides systematic classification of errors for retry logic
+    #
+    # This classifier determines whether errors should be retried based on their type.
+    # It maintains explicit lists of permanent (non-retryable) and retryable error classes.
+    #
+    # @example Classify a configuration error
+    #   ErrorClassifier.retryable?(ConfigurationError.new("Missing handler"))
+    #   # => false
+    #
+    # @example Classify a network error
+    #   ErrorClassifier.retryable?(NetworkError.new("Connection timeout"))
+    #   # => true
+    class ErrorClassifier
+      # System-level errors that should NEVER be retried
+      # These represent fundamental configuration or setup issues that won't resolve on retry
+      PERMANENT_ERROR_CLASSES = [
+        ConfigurationError,      # Configuration issues (missing config, invalid settings)
+        PermanentError,          # Explicitly marked permanent errors
+        ValidationError,         # Data validation failures
+        NotFoundError,           # Resource not found (handler, step, etc.)
+        DatabaseError,           # Database schema/constraint errors
+        FFIError                 # FFI bridge failures
+      ].freeze
+
+      # Application errors that are retryable by default
+      # These represent transient failures that may resolve on subsequent attempts
+      RETRYABLE_ERROR_CLASSES = [
+        RetryableError,          # Explicitly marked retryable errors
+        NetworkError,            # Network/connection failures
+        TimeoutError             # Timeout errors
+      ].freeze
+
+      # Determine if an error should be retried
+      #
+      # @param error [StandardError] The error to classify
+      # @return [Boolean] true if the error should be retried, false otherwise
+      #
+      # @note The default behavior is to mark errors as retryable unless they are
+      #   explicitly in the PERMANENT_ERROR_CLASSES list. This follows the principle
+      #   that it's safer to retry an error that shouldn't be retried (will eventually
+      #   hit retry limit) than to not retry an error that should be (will fail immediately).
+      def self.retryable?(error)
+        # Explicit permanent errors - never retry
+        return false if PERMANENT_ERROR_CLASSES.any? { |klass| error.is_a?(klass) }
+
+        # Explicit retryable errors - always retry
+        return true if RETRYABLE_ERROR_CLASSES.any? { |klass| error.is_a?(klass) }
+
+        # Default: StandardError and subclasses are retryable unless explicitly marked permanent
+        # This is a safe default - worst case, we retry until max_attempts is hit
+        true
+      end
+    end
+  end
+end

data/lib/tasker_core/errors.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'errors/common'
+require_relative 'errors/error_classifier'

data/lib/tasker_core/event_bridge.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require_relative 'models'
+
+module TaskerCore
+  module Worker
+    # Event bridge between Rust and Ruby using dry-events
+    #
+    # Handles bidirectional event communication between the Rust orchestration
+    # layer and Ruby business logic handlers. The bridge uses dry-events for
+    # Ruby-side pub/sub and FFI for cross-language communication.
+    #
+    # Event Flow:
+    # 1. **Rust → Ruby**: StepExecutionEvent indicates step is ready for processing
+    # 2. **Ruby Processing**: Handler executes business logic
+    # 3. **Ruby → Rust**: StepExecutionCompletionEvent returns results
+    #
+    # The EventBridge automatically wraps raw FFI data in accessor objects for
+    # developer convenience and maintains event schema validation.
+    #
+    # @example Publishing step execution (from Rust FFI)
+    #   # This is called automatically by Rust via FFI when a step is ready
+    #   bridge = TaskerCore::Worker::EventBridge.instance
+    #   bridge.publish_step_execution({
+    #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     task_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+    #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+    #     task_sequence_step: {
+    #       task: { context: { amount: 100.00, currency: "USD" } },
+    #       step: { name: "process_payment", handler_class: "ProcessPaymentHandler" },
+    #       workflow_step: { state: "in_progress", attempts: 1 }
+    #     }
+    #   })
+    #   # => Publishes 'step.execution.received' event to Ruby subscribers
+    #
+    # @example Subscribing to step execution events
+    #   # This is typically done in StepExecutionSubscriber
+    #   bridge.subscribe_to_step_execution do |event|
+    #     # Resolve handler
+    #     handler_class = event[:task_sequence_step].handler_class
+    #     handler = registry.resolve_handler(handler_class)
+    #
+    #     # Create context and execute handler
+    #     context = TaskerCore::Types::StepContext.new(event[:task_sequence_step])
+    #     result = handler.call(context)
+    #
+    #     # Send completion back to Rust
+    #     bridge.publish_step_completion({
+    #       event_id: event[:event_id],
+    #       task_uuid: event[:task_uuid],
+    #       step_uuid: event[:step_uuid],
+    #       success: true,
+    #       result: result
+    #     })
+    #   end
+    #
+    # @example Sending completion back to Rust
+    #   bridge.publish_step_completion({
+    #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     task_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+    #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+    #     success: true,
+    #     result: { payment_id: "pay_123", status: "succeeded" },
+    #     metadata: {
+    #       handler_class: "ProcessPaymentHandler",
+    #       execution_time_ms: 125
+    #     }
+    #   })
+    #   # => Sends completion to Rust via FFI and publishes 'step.completion.sent'
+    #
+    # @example Handling errors in step execution
+    #   begin
+    #     result = handler.call(context)
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: true,
+    #       result: result
+    #     })
+    #   rescue TaskerCore::Errors::RetryableError => e
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: false,
+    #       error_message: e.message,
+    #       error_class: e.class.name,
+    #       retryable: true,
+    #       retry_after: e.retry_after
+    #     })
+    #   rescue TaskerCore::Errors::PermanentError => e
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: false,
+    #       error_message: e.message,
+    #       error_class: e.class.name,
+    #       retryable: false
+    #     })
+    #   end
+    #
+    # Event Flow Diagram:
+    #
+    # ```
+    # Rust Orchestration                EventBridge                 Ruby Handler
+    # -----------------                -----------                 ------------
+    #       |                                |                           |
+    #       | 1. Step ready for execution    |                           |
+    #       |------------------------------->|                           |
+    #       |    publish_step_execution      |                           |
+    #       |                                | 2. Publish event          |
+    #       |                                |-------------------------->|
+    #       |                                |    step.execution.received|
+    #       |                                |                           |
+    #       |                                |                  3. Execute handler
+    #       |                                |                           |
+    #       |                                | 4. Completion             |
+    #       |                                |<--------------------------|
+    #       | 5. FFI completion              |    publish_step_completion|
+    #       |<-------------------------------|                           |
+    #       |    send_step_completion_event  |                           |
+    # ```
+    #
+    # Registered Events:
+    # - **step.execution.received**: Step ready for execution (Rust → Ruby)
+    # - **step.completion.sent**: Step execution completed (Ruby → Rust)
+    # - **bridge.error**: Error in event processing
+    #
+    # Completion Data Validation:
+    # The bridge validates completion data before sending to Rust:
+    # - **event_id**: Required, UUID of the original execution event
+    # - **task_uuid**: Required, UUID of the task
+    # - **step_uuid**: Required, UUID of the step
+    # - **success**: Required, boolean indicating success/failure
+    # - **metadata**: Optional, hash with additional context
+    # - **completed_at**: Optional, ISO 8601 timestamp (auto-generated if missing)
+    #
+    # @see TaskerCore::Subscriber For event subscription implementation
+    # @see TaskerCore::Worker::EventPoller For polling mechanism
+    # @see TaskerCore::FFI For Rust FFI operations
+    # @see TaskerCore::Models::TaskSequenceStepWrapper For data wrappers
+    class EventBridge
+      include Singleton
+      include Dry::Events::Publisher[:tasker_core]
+
+      attr_reader :logger, :active
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @active = true
+
+        setup_event_schema!
+      end
+
+      # Check if bridge is active
+      def active?
+        @active
+      end
+
+      # Stop the event bridge
+      def stop!
+        @active = false
+        logger.info 'Event bridge stopped'
+      end
+
+      # Called by Rust FFI when StepExecutionEvent is received
+      # This is the entry point for events from Rust
+      def publish_step_execution(event_data)
+        return unless active?
+
+        event_data = event_data.to_h.deep_symbolize_keys
+        logger.debug "Publishing step execution event: #{event_data[:event_id]}"
+
+        # Wrap the raw data in accessor objects for easier use
+        wrapped_event = wrap_step_execution_event(event_data)
+
+        # Publish to dry-events subscribers (Ruby handlers)
+        publish('step.execution.received', wrapped_event)
+
+        logger.debug 'Step execution event published successfully'
+        true
+      rescue StandardError => e
+        logger.error "Failed to publish step execution: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      # Subscribe to step execution events (used by StepExecutionSubscriber)
+      def subscribe_to_step_execution(&)
+        subscribe('step.execution.received', &)
+      end
+
+      # Send completion event back to Rust
+      # Called by StepExecutionSubscriber after handler execution
+      def publish_step_completion(completion_data)
+        return unless active?
+
+        logger.debug "Sending step completion to Rust: #{completion_data[:event_id]}"
+
+        # Validate completion data
+        validate_completion!(completion_data)
+
+        # Send to Rust via FFI (TAS-67: complete_step_event takes event_id and completion_data)
+        TaskerCore::FFI.complete_step_event(completion_data[:event_id].to_s, completion_data)
+
+        # Also publish locally for monitoring/debugging
+        publish('step.completion.sent', completion_data)
+
+        logger.debug 'Step completion sent to Rust'
+      rescue StandardError => e
+        logger.error "Failed to send step completion: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      # TAS-125: Send checkpoint yield back to Rust for batch processing
+      #
+      # Called by batch processing handlers when they want to persist progress
+      # and be re-dispatched for continuation. Unlike publish_step_completion,
+      # this does NOT complete the step - instead it persists checkpoint data
+      # and causes the step to be re-dispatched for continued processing.
+      #
+      # @param checkpoint_data [Hash] Checkpoint data to persist:
+      #   - :event_id [String] Required, UUID of the original execution event
+      #   - :step_uuid [String] Required, UUID of the step
+      #   - :cursor [Object] Required, position to resume from (Integer, String, or Hash)
+      #   - :items_processed [Integer] Required, count of items processed so far
+      #   - :accumulated_results [Hash] Optional, partial results to carry forward
+      # @return [Boolean] true if checkpoint was persisted and step re-dispatched
+      #
+      # @example Yield checkpoint in batch processing
+      #   bridge.publish_step_checkpoint_yield({
+      #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+      #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+      #     cursor: 1000,
+      #     items_processed: 1000,
+      #     accumulated_results: { total_amount: 50000.00, processed_count: 1000 }
+      #   })
+      def publish_step_checkpoint_yield(checkpoint_data)
+        return false unless active?
+
+        logger.debug "Sending checkpoint yield to Rust: #{checkpoint_data[:event_id]}"
+
+        # Validate checkpoint data
+        validate_checkpoint_yield!(checkpoint_data)
+
+        # Send to Rust via FFI (TAS-125)
+        success = TaskerCore::FFI.checkpoint_yield_step_event(
+          checkpoint_data[:event_id].to_s,
+          checkpoint_data
+        )
+
+        if success
+          # Publish locally for monitoring/debugging
+          publish('step.checkpoint_yield.sent', checkpoint_data)
+          logger.debug 'Checkpoint yield sent to Rust - step will be re-dispatched'
+        else
+          logger.warn 'Checkpoint yield failed - checkpoint support may not be configured'
+        end
+
+        success
+      rescue StandardError => e
+        logger.error "Failed to send checkpoint yield: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      private
+
+      def setup_event_schema!
+        # Register event types
+        register_event('step.execution.received')
+        register_event('step.completion.sent')
+        register_event('step.checkpoint_yield.sent') # TAS-125
+        register_event('bridge.error')
+      end
+
+      def wrap_step_execution_event(event_data)
+        wrapped = {
+          event_id: event_data[:event_id],
+          task_uuid: event_data[:task_uuid],
+          step_uuid: event_data[:step_uuid],
+          task_sequence_step: TaskerCore::Models::TaskSequenceStepWrapper.new(event_data[:task_sequence_step])
+        }
+
+        # TAS-29: Expose correlation_id at top level for easy access
+        wrapped[:correlation_id] = event_data[:correlation_id] if event_data[:correlation_id]
+        wrapped[:parent_correlation_id] = event_data[:parent_correlation_id] if event_data[:parent_correlation_id]
+
+        # TAS-65 Phase 1.5b: Expose trace_id and span_id for distributed tracing
+        wrapped[:trace_id] = event_data[:trace_id] if event_data[:trace_id]
+        wrapped[:span_id] = event_data[:span_id] if event_data[:span_id]
+
+        wrapped
+      end
+
+      def validate_completion!(completion_data)
+        required_fields = %i[event_id task_uuid step_uuid success]
+        missing_fields = required_fields - completion_data.keys
+
+        if missing_fields.any?
+          raise ArgumentError, "Missing required fields in completion: #{missing_fields.join(', ')}"
+        end
+
+        # Ensure metadata is a hash
+        completion_data[:metadata] ||= {}
+
+        # Ensure timestamps
+        completion_data[:completed_at] ||= Time.now.utc.iso8601
+      end
+
+      # TAS-125: Validate checkpoint yield data before sending to Rust
+      def validate_checkpoint_yield!(checkpoint_data)
+        required_fields = %i[event_id step_uuid cursor items_processed]
+        missing_fields = required_fields - checkpoint_data.keys
+
+        if missing_fields.any?
+          raise ArgumentError, "Missing required fields in checkpoint yield: #{missing_fields.join(', ')}"
+        end
+
+        # Validate items_processed is a non-negative integer
+        return if checkpoint_data[:items_processed].is_a?(Integer) && checkpoint_data[:items_processed] >= 0
+
+        raise ArgumentError, 'items_processed must be a non-negative integer'
+      end
+    end
+  end
+end