senro_usecaser 0.3.0 → 0.4.1

data/sig/generated/senro_usecaser/base.rbs

@@ -89,30 +89,14 @@ module SenroUsecaser
   #     organize StepA, StepB
   #   end
   class Base
-    # Declares a dependency to be injected from the container
-    #
-    # : (Symbol, ?Class) -> void
-    def self.depends_on: (Symbol, ?Class) -> void
+    extend DependsOn
 
-    # Returns the list of declared dependencies
-    #
-    # : () -> Array[Symbol]
-    def self.dependencies: () -> Array[Symbol]
+    include DependsOn::InstanceMethods
 
-    # Returns the dependency type mapping
-    #
-    # : () -> Hash[Symbol, Class]
-    def self.dependency_types: () -> Hash[Symbol, Class]
-
-    # Sets the namespace for dependency resolution
-    #
-    # : ((Symbol | String)) -> void
-    def self.namespace: (Symbol | String) -> void
-
-    # Returns the declared namespace
+    # Alias for backward compatibility
     #
     # : () -> (Symbol | String)?
-    attr_reader use_case_namespace: untyped
+    alias self.use_case_namespace self.declared_namespace
 
     # Declares a sequence of UseCases to execute as a pipeline
     #
@@ -188,6 +172,73 @@ module SenroUsecaser
     # : () -> Array[Proc]
     def self.around_hooks: () -> Array[Proc]
 
+    # Adds an on_failure hook
+    #
+    # : () { (untyped, Result[untyped], ?RetryContext?) -> void } -> void
+    def self.on_failure: () { (untyped, Result[untyped], ?RetryContext?) -> void } -> void
+
+    # Returns the list of on_failure hooks
+    #
+    # : () -> Array[Proc]
+    def self.on_failure_hooks: () -> Array[Proc]
+
+    # Configures automatic retry for specific error types
+    #
+    # @example Retry on network errors
+    #   retry_on :network_error, attempts: 3, wait: 1
+    #
+    # @example Retry on exception class
+    #   retry_on Net::OpenTimeout, attempts: 5, wait: 2, backoff: :exponential
+    #
+    # @example Multiple error types with jitter
+    #   retry_on :rate_limited, :timeout, attempts: 3, wait: 1, jitter: 0.1
+    #
+    # rubocop:disable Metrics/ParameterLists
+    # : (*(Symbol | Class), ?attempts: Integer, ?wait: (Float | Integer),
+    # :  ?backoff: Symbol, ?max_wait: (Float | Integer)?, ?jitter: (Float | Integer)) -> void
+    def self.retry_on: (*untyped error_matchers, ?attempts: untyped, ?wait: untyped, ?backoff: untyped, ?max_wait: untyped, ?jitter: untyped) -> untyped
+
+    # Returns the list of retry configurations
+    #
+    # : () -> Array[RetryConfiguration]
+    def self.retry_configurations: () -> Array[RetryConfiguration]
+
+    # Configures errors that should immediately discard (no retry)
+    #
+    # @example Discard on validation errors
+    #   discard_on :validation_error, :not_found
+    #
+    # @example Discard on exception class
+    #   discard_on ArgumentError
+    #
+    # : (*(Symbol | Class)) -> void
+    def self.discard_on: (*Symbol | Class) -> void
+
+    # Returns the list of discard matchers
+    #
+    # : () -> Array[(Symbol | Class)]
+    def self.discard_matchers: () -> Array[Symbol | Class]
+
+    # Adds a before_retry hook
+    #
+    # : () { (untyped, Result[untyped], RetryContext) -> void } -> void
+    def self.before_retry: () { (untyped, Result[untyped], RetryContext) -> void } -> void
+
+    # Returns the list of before_retry hooks
+    #
+    # : () -> Array[Proc]
+    def self.before_retry_hooks: () -> Array[Proc]
+
+    # Adds an after_retries_exhausted hook
+    #
+    # : () { (untyped, Result[untyped], RetryContext) -> void } -> void
+    def self.after_retries_exhausted: () { (untyped, Result[untyped], RetryContext) -> void } -> void
+
+    # Returns the list of after_retries_exhausted hooks
+    #
+    # : () -> Array[Proc]
+    def self.after_retries_exhausted_hooks: () -> Array[Proc]
+
     # Declares the expected input type(s) for this UseCase
     # Accepts a Class or one or more Modules that input must include
     #
@@ -261,6 +312,18 @@ module SenroUsecaser
     # : (?untyped input) -> Result[untyped]
     def call: (?untyped input) -> Result[untyped]
 
+    # Represents a record of a step execution in a pipeline
+    class StepExecutionRecord < Struct[untyped]
+      attr_accessor step(): untyped
+
+      attr_accessor input(): untyped
+
+      attr_accessor result(): untyped
+
+      def self.new: (?step: untyped, ?input: untyped, ?result: untyped) -> instance
+                  | ({ ?step: untyped, ?input: untyped, ?result: untyped }) -> instance
+    end
+
     private
 
     # Creates a success Result with the given value
@@ -301,6 +364,36 @@ module SenroUsecaser
     # : (untyped) { () -> Result[untyped] } -> Result[untyped]
     def execute_with_hooks: (untyped) { () -> Result[untyped] } -> Result[untyped]
 
+    # Executes the UseCase with retry support
+    #
+    # : (untyped) -> Result[untyped]
+    def execute_with_retry: (untyped) -> Result[untyped]
+
+    # Builds a retry context with max attempts from configurations
+    #
+    # : () -> RetryContext
+    def build_retry_context: () -> RetryContext
+
+    # Finds a retry configuration that matches the result
+    #
+    # : (Result[untyped]) -> RetryConfiguration?
+    def find_matching_retry_config: (Result[untyped]) -> RetryConfiguration?
+
+    # Checks if the result should be discarded (no retry)
+    #
+    # : (Result[untyped]) -> bool
+    def should_discard?: (Result[untyped]) -> bool
+
+    # Runs before_retry hooks
+    #
+    # : (untyped, Result[untyped], RetryContext) -> void
+    def run_before_retry_hooks: (untyped, Result[untyped], RetryContext) -> void
+
+    # Runs after_retries_exhausted hooks
+    #
+    # : (untyped, Result[untyped], RetryContext) -> void
+    def run_after_retries_exhausted_hooks: (untyped, Result[untyped], RetryContext) -> void
+
     # Wraps a non-Result value in Result.success
     #
     # : (untyped) -> Result[untyped]
@@ -336,6 +429,16 @@ module SenroUsecaser
     # : (untyped, Result[untyped]) -> void
     def run_after_hooks: (untyped, Result[untyped]) -> void
 
+    # Runs all on_failure hooks when result is a failure
+    #
+    # : (untyped, Result[untyped], ?RetryContext?) -> void
+    def run_on_failure_hooks: (untyped, Result[untyped], ?RetryContext?) -> void
+
+    # Calls an on_failure hook with appropriate arguments
+    #
+    # : (untyped, Symbol, untyped, Result[untyped], RetryContext?) -> void
+    def call_on_failure_hook: (untyped, Symbol, untyped, Result[untyped], RetryContext?) -> void
+
     # Returns instantiated hook objects
     #
     # : () -> Array[Hook]
@@ -352,20 +455,11 @@ module SenroUsecaser
     def resolve_dependencies: (Container, Hash[Symbol, untyped]) -> void
 
     # Resolves a single dependency from the container
+    # Overrides DependsOn::InstanceMethods to accept container as parameter
     #
     # : (Container, Symbol) -> untyped
     def resolve_from_container: (Container, Symbol) -> untyped
 
-    # Returns the effective namespace for dependency resolution
-    #
-    # : () -> (Symbol | String)?
-    def effective_namespace: () -> (Symbol | String)?
-
-    # Infers namespace from the class's module structure
-    #
-    # : () -> String?
-    def infer_namespace_from_class: () -> String?
-
     # Executes the organized UseCase pipeline
     #
     # : (untyped) -> Result[untyped]
@@ -408,8 +502,27 @@ module SenroUsecaser
 
     # Calls a single UseCase in the pipeline
     # Requires input type(s) to be defined for pipeline steps
+    # Note: on_failure hooks are not called here - they're called in pipeline rollback
     #
     # : (singleton(Base), untyped) -> Result[untyped]
     def call_use_case: (singleton(Base), untyped) -> Result[untyped]
+
+    # Performs the UseCase as a pipeline step (without on_failure hooks)
+    # on_failure hooks are handled by the pipeline's rollback mechanism instead
+    #
+    # : (untyped, ?capture_exceptions: bool) -> Result[untyped]
+    def perform_as_pipeline_step: (untyped, ?capture_exceptions: bool) -> Result[untyped]
+
+    # Executes rollback by calling on_failure hooks on executed steps in reverse order
+    # Unlike run_on_failure_hooks, this method calls hooks regardless of result status
+    # because we want to rollback even successfully completed steps when pipeline fails
+    #
+    # : (Array[StepExecutionRecord]) -> void
+    def execute_pipeline_rollback: (Array[StepExecutionRecord]) -> void
+
+    # Runs on_failure hooks for rollback purposes (regardless of result status)
+    #
+    # : (untyped, Result[untyped]) -> void
+    def run_rollback_hooks: (untyped, Result[untyped]) -> void
   end
 end

data/sig/generated/senro_usecaser/depends_on.rbs

@@ -0,0 +1,197 @@
+# Generated from lib/senro_usecaser/depends_on.rb with RBS::Inline
+
+module SenroUsecaser
+  # Module that provides dependency injection support
+  #
+  # This module can be extended into any class to enable the full DI functionality
+  # similar to UseCase and Hook classes, including:
+  # - `depends_on` for declaring dependencies
+  # - `namespace` for scoped dependency resolution
+  # - Automatic `infer_namespace_from_module` support
+  # - Default `initialize` that sets up dependency injection (uses SenroUsecaser.container if not provided)
+  #
+  # @example Basic usage (no initialize needed)
+  #   class MyService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :logger, Logger
+  #     depends_on :repository
+  #
+  #     # No initialize needed! Default is provided automatically.
+  #
+  #     def perform
+  #       logger.info("Performing...")
+  #       repository.find(1)
+  #     end
+  #   end
+  #
+  #   service = MyService.new  # Uses SenroUsecaser.container
+  #   service.logger  # => Logger instance
+  #
+  # @example Custom initialize with super
+  #   class MyService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :logger
+  #     attr_reader :extra
+  #
+  #     def initialize(extra:, container: nil)
+  #       super(container: container)  # Handles dependency resolution
+  #       @extra = extra
+  #     end
+  #   end
+  #
+  # @example With explicit namespace
+  #   class Admin::UserService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     namespace :admin
+  #     depends_on :user_repository, UserRepository
+  #   end
+  #
+  # @example With infer_namespace_from_module (when configured)
+  #   # When SenroUsecaser.configuration.infer_namespace_from_module = true
+  #   class Admin::Orders::ProcessService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :order_repository  # resolved from "admin::orders" namespace
+  #   end
+  module DependsOn
+    # Hook called when module is extended into a class
+    # Automatically includes InstanceMethods
+    def self.extended: (untyped base) -> untyped
+
+    # Declares a dependency to be injected from the container
+    #
+    # @param name [Symbol] The name of the dependency
+    # @param type [Class, nil] Optional expected type for the dependency
+    #
+    # @example Basic dependency
+    #   depends_on :logger
+    #
+    # @example Typed dependency
+    #   depends_on :repository, UserRepository
+    #
+    # : (Symbol, ?Class) -> void
+    def depends_on: (Symbol, ?Class) -> void
+
+    # Returns the list of declared dependencies
+    #
+    # : () -> Array[Symbol]
+    def dependencies: () -> Array[Symbol]
+
+    # Returns the dependency type mapping
+    #
+    # : () -> Hash[Symbol, Class]
+    def dependency_types: () -> Hash[Symbol, Class]
+
+    # Sets or returns the namespace for dependency resolution
+    #
+    # @param name [Symbol, String, nil] The namespace to set
+    # @return [Symbol, String, nil] The current namespace when no argument given
+    #
+    # @example Setting namespace
+    #   namespace :admin
+    #
+    # @example Getting namespace
+    #   current_ns = namespace
+    #
+    # : (?(Symbol | String)) -> (Symbol | String)?
+    def namespace: (?Symbol | String) -> (Symbol | String)?
+
+    # Returns the declared namespace
+    #
+    # : () -> (Symbol | String)?
+    def declared_namespace: () -> (Symbol | String)?
+
+    # Copies dependency configuration to a subclass
+    #
+    # @param subclass [Class] The subclass to copy dependencies to
+    #
+    # @example In inherited hook
+    #   def self.inherited(subclass)
+    #     super
+    #     copy_depends_on_to(subclass)
+    #   end
+    #
+    # : (Class) -> void
+    def copy_depends_on_to: (Class) -> void
+
+    # Instance methods for dependency resolution
+    #
+    # These methods are automatically included when DependsOn is extended.
+    # They require @_container and @_dependencies instance variables to be set.
+    module InstanceMethods
+      # Default initialize for classes using DependsOn
+      #
+      # This provides a default initialize that sets up dependency injection.
+      # Classes can override this and call super to extend the behavior.
+      #
+      # @param container [Container, nil] The DI container to resolve dependencies from.
+      #   If nil, uses SenroUsecaser.container.
+      #
+      # @example Default usage (no arguments needed)
+      #   class MyService
+      #     extend SenroUsecaser::DependsOn
+      #     depends_on :logger
+      #   end
+      #   service = MyService.new  # Uses SenroUsecaser.container
+      #
+      # @example With explicit container
+      #   service = MyService.new(container: custom_container)
+      #
+      # @example Custom initialize with super
+      #   class MyService
+      #     extend SenroUsecaser::DependsOn
+      #     depends_on :logger
+      #     attr_reader :extra
+      #
+      #     def initialize(extra:, container: nil)
+      #       super(container: container)
+      #       @extra = extra
+      #     end
+      #   end
+      #
+      # : (?container: Container?) -> void
+      def initialize: (?container: Container?) -> void
+
+      # Resolves all declared dependencies from the container
+      #
+      # Call this in your initialize method after setting @_container and @_dependencies.
+      #
+      # @example
+      #   def initialize(container:)
+      #     @_container = container
+      #     @_dependencies = {}
+      #     resolve_dependencies
+      #   end
+      #
+      # : () -> void
+      def resolve_dependencies: () -> void
+
+      private
+
+      # Returns the effective namespace for dependency resolution
+      #
+      # Priority:
+      # 1. Explicitly declared namespace via `namespace :name`
+      # 2. Inferred namespace from module structure (if configured)
+      #
+      # : () -> (Symbol | String)?
+      def effective_namespace: () -> (Symbol | String)?
+
+      # Infers namespace from the class's module structure
+      #
+      # Converts CamelCase module names to snake_case and joins with "::"
+      # e.g., Admin::Orders::ProcessService -> "admin::orders"
+      #
+      # : () -> String?
+      def infer_namespace_from_class: () -> String?
+
+      # Resolves a single dependency from the container
+      #
+      # : (Symbol) -> untyped
+      def resolve_from_container: (Symbol) -> untyped
+    end
+  end
+end

data/sig/generated/senro_usecaser/hook.rbs

@@ -36,30 +36,14 @@ module SenroUsecaser
   #     end
   #   end
   class Hook
-    # Declares a dependency to be injected from the container
-    #
-    # : (Symbol, ?Class) -> void
-    def self.depends_on: (Symbol, ?Class) -> void
-
-    # Returns the list of declared dependencies
-    #
-    # : () -> Array[Symbol]
-    def self.dependencies: () -> Array[Symbol]
-
-    # Returns the dependency type mapping
-    #
-    # : () -> Hash[Symbol, Class]
-    def self.dependency_types: () -> Hash[Symbol, Class]
+    extend DependsOn
 
-    # Sets or returns the namespace for dependency resolution
-    #
-    # : (?(Symbol | String)) -> (Symbol | String)?
-    def self.namespace: (?Symbol | String) -> (Symbol | String)?
+    include DependsOn::InstanceMethods
 
-    # Alias for namespace() without arguments
+    # Alias for backward compatibility
     #
     # : () -> (Symbol | String)?
-    def self.hook_namespace: () -> (Symbol | String)?
+    alias self.hook_namespace self.declared_namespace
 
     # @api private
     def self.inherited: (untyped subclass) -> untyped
@@ -87,26 +71,30 @@ module SenroUsecaser
     # : (untyped) { () -> Result[untyped] } -> Result[untyped]
     def around: (untyped) { () -> Result[untyped] } -> Result[untyped]
 
+    # Called when the UseCase fails
+    # Override in subclass to add failure handling or rollback logic
+    #
+    # @example Basic logging
+    #   def on_failure(input, result)
+    #     logger.error("Failed: #{result.errors.first&.message}")
+    #   end
+    #
+    # @example Request retry
+    #   def on_failure(input, result, context)
+    #     if result.errors.first&.code == :network_error && context.attempt < 3
+    #       context.retry!(wait: 2.0)
+    #     end
+    #   end
+    #
+    # : (untyped, Result[untyped], ?RetryContext?) -> void
+    def on_failure: (untyped, Result[untyped], ?RetryContext?) -> void
+
     private
 
     # Returns the effective namespace for dependency resolution
+    # Overrides DependsOn::InstanceMethods to add use_case_namespace fallback
     #
     # : () -> (Symbol | String)?
     def effective_namespace: () -> (Symbol | String)?
-
-    # Infers namespace from the class's module structure
-    #
-    # : () -> String?
-    def infer_namespace_from_class: () -> String?
-
-    # Resolves dependencies from the container
-    #
-    # : () -> void
-    def resolve_dependencies: () -> void
-
-    # Resolves a single dependency from the container
-    #
-    # : (Symbol) -> untyped
-    def resolve_from_container: (Symbol) -> untyped
   end
 end

data/sig/generated/senro_usecaser/retry_configuration.rbs

@@ -0,0 +1,90 @@
+# Generated from lib/senro_usecaser/retry_configuration.rb with RBS::Inline
+
+module SenroUsecaser
+  # Configuration for automatic retry behavior
+  #
+  # This class defines when and how retries should occur based on
+  # error codes or exception classes, with configurable backoff strategies.
+  #
+  # @example Basic retry configuration
+  #   RetryConfiguration.new(
+  #     matchers: [:network_error, Net::OpenTimeout],
+  #     attempts: 3,
+  #     wait: 1.0
+  #   )
+  #
+  # @example With exponential backoff
+  #   RetryConfiguration.new(
+  #     matchers: [:rate_limited],
+  #     attempts: 5,
+  #     wait: 2.0,
+  #     backoff: :exponential,
+  #     max_wait: 60
+  #   )
+  class RetryConfiguration
+    # Returns the list of error matchers (Symbols for error codes, Classes for exceptions)
+    # : () -> Array[(Symbol | Class)]
+    attr_reader matchers: untyped
+
+    # Returns the maximum number of attempts
+    # : () -> Integer
+    attr_reader attempts: untyped
+
+    # Returns the base wait time in seconds
+    # : () -> (Float | Integer)
+    attr_reader wait: untyped
+
+    # Returns the backoff strategy (:fixed, :linear, :exponential)
+    # : () -> Symbol
+    attr_reader backoff: untyped
+
+    # Returns the maximum wait time in seconds
+    # : () -> (Float | Integer)
+    attr_reader max_wait: untyped
+
+    # Returns the jitter factor (0.0 to 1.0)
+    # : () -> (Float | Integer)
+    attr_reader jitter: untyped
+
+    # Initializes a new retry configuration
+    #
+    # @param matchers [Array<Symbol, Class>] Error codes or exception classes to match
+    # @param attempts [Integer] Maximum number of attempts (default: 3)
+    # @param wait [Numeric] Base wait time in seconds (default: 0)
+    # @param backoff [Symbol] Backoff strategy: :fixed, :linear, or :exponential (default: :fixed)
+    # @param max_wait [Numeric] Maximum wait time in seconds (default: 3600)
+    # @param jitter [Numeric] Jitter factor 0.0-1.0 to randomize wait times (default: 0)
+    #
+    # rubocop:disable Metrics/ParameterLists
+    # : (matchers: Array[(Symbol | Class)], ?attempts: Integer, ?wait: (Float | Integer),
+    # :  ?backoff: Symbol, ?max_wait: (Float | Integer)?, ?jitter: (Float | Integer)) -> void
+    def initialize: (matchers: untyped, ?attempts: untyped, ?wait: untyped, ?backoff: untyped, ?max_wait: untyped, ?jitter: untyped) -> untyped
+
+    # Checks if this configuration matches the given result
+    #
+    # : (Result[untyped]) -> bool
+    def matches?: (Result[untyped]) -> bool
+
+    # Calculates the wait time for the given attempt number
+    #
+    # : (Integer) -> Float
+    def calculate_wait: (Integer) -> Float
+
+    private
+
+    # Checks if an error matches any of the configured matchers
+    #
+    # : (Error) -> bool
+    def matches_error?: (Error) -> bool
+
+    # Calculates the base wait time based on backoff strategy
+    #
+    # : (Integer) -> (Float | Integer)
+    def calculate_base_wait: (Integer) -> (Float | Integer)
+
+    # Applies jitter to the wait time
+    #
+    # : ((Float | Integer)) -> Float
+    def apply_jitter: (Float | Integer) -> Float
+  end
+end

data/sig/generated/senro_usecaser/retry_context.rbs

@@ -0,0 +1,101 @@
+# Generated from lib/senro_usecaser/retry_context.rb with RBS::Inline
+
+module SenroUsecaser
+  # Represents the context of a retry operation
+  #
+  # This class tracks the state of retry attempts including:
+  # - Current attempt number
+  # - Maximum attempts allowed
+  # - Elapsed time since first attempt
+  # - Whether a retry should occur
+  #
+  # @example Basic usage in on_failure hook
+  #   on_failure do |input, result, context|
+  #     if context.attempt < 3
+  #       context.retry!(wait: 1.0)
+  #     end
+  #   end
+  #
+  # @example With modified input
+  #   on_failure do |input, result, context|
+  #     if result.errors.first&.code == :rate_limited
+  #       context.retry!(input: input.with_reduced_batch_size, wait: 5.0)
+  #     end
+  #   end
+  class RetryContext
+    # Returns the current attempt number (1-indexed)
+    # : () -> Integer
+    attr_reader attempt: untyped
+
+    # Returns the maximum number of attempts allowed
+    # : () -> Integer?
+    attr_reader max_attempts: untyped
+
+    # Returns the time when the first attempt started
+    # : () -> Time
+    attr_reader started_at: untyped
+
+    # Returns the error from the last failed attempt
+    # : () -> Error?
+    attr_reader last_error: untyped
+
+    # Returns the input to use for the retry (nil means use original)
+    # : () -> untyped
+    attr_reader retry_input: untyped
+
+    # Returns the wait time before retrying
+    # : () -> (Float | Integer)?
+    attr_reader retry_wait: untyped
+
+    # Initializes a new retry context
+    #
+    # : (?max_attempts: Integer?) -> void
+    def initialize: (?max_attempts: Integer?) -> void
+
+    # Returns true if this is a retry (attempt > 1)
+    #
+    # : () -> bool
+    def retried?: () -> bool
+
+    # Returns the elapsed time since the first attempt
+    #
+    # : () -> Float
+    def elapsed_time: () -> Float
+
+    # Returns true if max_attempts has been reached
+    #
+    # : () -> bool
+    def exhausted?: () -> bool
+
+    # Returns true if a retry has been requested
+    #
+    # : () -> bool
+    def should_retry?: () -> bool
+
+    # Requests a retry with optional modified input and wait time
+    #
+    # @example Retry with default settings
+    #   context.retry!
+    #
+    # @example Retry with wait time
+    #   context.retry!(wait: 2.0)
+    #
+    # @example Retry with modified input
+    #   context.retry!(input: modified_input, wait: 1.0)
+    #
+    # : (?input: untyped, ?wait: (Float | Integer)?) -> void
+    def retry!: (?input: untyped, ?wait: (Float | Integer)?) -> void
+
+    # Increments the attempt counter and resets retry state
+    # Called internally between retry attempts
+    #
+    # : (?last_error: Error?) -> void
+    def increment!: (?last_error: Error?) -> void
+
+    # Resets the retry request state
+    # Called internally after processing retry decision
+    #
+    # : () -> void
+    def reset_retry_state!: () -> void
+  end
+end

data/sig/overrides.rbs

@@ -10,7 +10,6 @@ module SenroUsecaser
   class Base
     # Class methods that rbs-inline doesn't generate correctly
     def self.organized_steps: () -> Array[Step]?
-    def self.use_case_namespace: () -> (Symbol | String)?
     def self.output_schema: () -> (Class | Hash[Symbol, Class])?
   end
 end