tasker-engine 1.0.0

data/lib/tasker/types/cache_config.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for intelligent cache strategy settings
+    #
+    # This configuration provides strategic control over cache behavior while
+    # maintaining consistent infrastructure naming through constants.
+    #
+    # Strategic Design:
+    # - CONFIGURABLE: Algorithm parameters that vary by workload characteristics
+    # - CONFIGURABLE: Performance thresholds that vary by deployment environment
+    # - CONSTANTS: Infrastructure naming for consistency across deployments
+    #
+    # @example Basic usage
+    #   config = CacheConfig.new(
+    #     default_ttl: 600,                    # 10 minutes for stable data
+    #     hit_rate_smoothing_factor: 0.8       # Less aggressive smoothing
+    #   )
+    #
+    # @example Environment-specific tuning
+    #   # Development environment - shorter TTLs for rapid iteration
+    #   config = CacheConfig.new(
+    #     default_ttl: 120,                    # 2 minutes
+    #     adaptive_ttl_enabled: false,         # Disable complexity
+    #     performance_tracking_enabled: false  # Reduce overhead
+    #   )
+    #
+    #   # Production environment - optimized for performance
+    #   config = CacheConfig.new(
+    #     default_ttl: 300,                    # 5 minutes
+    #     hit_rate_smoothing_factor: 0.95,     # Aggressive smoothing
+    #     access_frequency_decay_rate: 0.98,   # Slow decay
+    #     adaptive_ttl_enabled: true,          # Enable intelligence
+    #     performance_tracking_enabled: true   # Full observability
+    #   )
+    #
+    #   # High-performance environment - maximum efficiency
+    #   config = CacheConfig.new(
+    #     default_ttl: 600,                    # 10 minutes
+    #     min_adaptive_ttl: 60,                # 1 minute minimum
+    #     max_adaptive_ttl: 7200,              # 2 hours maximum
+    #     cache_pressure_threshold: 0.9,       # High threshold
+    #     adaptive_calculation_interval: 15    # Frequent recalculation
+    #   )
+    class CacheConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # ====================
+      # CONFIGURABLE SETTINGS
+      # ====================
+      # These affect performance characteristics and should vary by deployment
+
+      # Default cache TTL in seconds
+      #
+      # Base time-to-live for cache entries before adaptive calculation.
+      # Fast-changing data might need 60-120s, stable data can use 300-600s.
+      #
+      # @!attribute [r] default_ttl
+      #   @return [Integer] Default TTL in seconds (default: 300)
+      attribute :default_ttl, Types::Integer.default(300)
+
+      # Enable adaptive TTL calculation
+      #
+      # Whether to use intelligent TTL adjustment based on hit rates and generation time.
+      # Development environments might disable this for simplicity.
+      #
+      # @!attribute [r] adaptive_ttl_enabled
+      #   @return [Boolean] Whether adaptive TTL is enabled (default: true)
+      attribute :adaptive_ttl_enabled, Types::Bool.default(true)
+
+      # Enable performance tracking
+      #
+      # Whether to track cache performance metrics for adaptive calculation.
+      # Adds small overhead but enables intelligent optimization.
+      #
+      # @!attribute [r] performance_tracking_enabled
+      #   @return [Boolean] Whether performance tracking is enabled (default: true)
+      attribute :performance_tracking_enabled, Types::Bool.default(true)
+
+      # Hit rate smoothing factor for exponential moving average
+      #
+      # Controls how quickly hit rate adapts to new data.
+      # Higher values (0.95+) = slower adaptation, more stable
+      # Lower values (0.8-) = faster adaptation, more responsive
+      #
+      # @!attribute [r] hit_rate_smoothing_factor
+      #   @return [Float] Smoothing factor (default: 0.9)
+      attribute :hit_rate_smoothing_factor, Types::Float.default(0.9)
+
+      # Access frequency decay rate for daily patterns
+      #
+      # Controls how access frequency decays over time.
+      # Higher values (0.98+) = slow decay, long memory
+      # Lower values (0.9-) = fast decay, short memory
+      #
+      # @!attribute [r] access_frequency_decay_rate
+      #   @return [Float] Decay rate (default: 0.95)
+      attribute :access_frequency_decay_rate, Types::Float.default(0.95)
+
+      # Minimum adaptive TTL bound
+      #
+      # Absolute minimum TTL regardless of adaptive calculation.
+      # Prevents thrashing with very short cache times.
+      #
+      # @!attribute [r] min_adaptive_ttl
+      #   @return [Integer] Minimum TTL in seconds (default: 30)
+      attribute :min_adaptive_ttl, Types::Integer.default(30)
+
+      # Maximum adaptive TTL bound
+      #
+      # Absolute maximum TTL regardless of adaptive calculation.
+      # Prevents stale data with very long cache times.
+      #
+      # @!attribute [r] max_adaptive_ttl
+      #   @return [Integer] Maximum TTL in seconds (default: 3600)
+      attribute :max_adaptive_ttl, Types::Integer.default(3600)
+
+      # Dashboard cache TTL
+      #
+      # Specific TTL for dashboard and analytics queries.
+      # Should be shorter than default for responsive dashboards.
+      #
+      # @!attribute [r] dashboard_cache_ttl
+      #   @return [Integer] Dashboard TTL in seconds (default: 120)
+      attribute :dashboard_cache_ttl, Types::Integer.default(120)
+
+      # Cache pressure threshold
+      #
+      # Utilization threshold that triggers cache pressure responses.
+      # Higher values = more aggressive caching, lower = more conservative.
+      #
+      # @!attribute [r] cache_pressure_threshold
+      #   @return [Float] Pressure threshold (default: 0.8)
+      attribute :cache_pressure_threshold, Types::Float.default(0.8)
+
+      # Adaptive calculation interval
+      #
+      # How often to recalculate adaptive TTL values in seconds.
+      # Shorter intervals = more responsive, longer = more stable.
+      #
+      # @!attribute [r] adaptive_calculation_interval
+      #   @return [Integer] Calculation interval in seconds (default: 30)
+      attribute :adaptive_calculation_interval, Types::Integer.default(30)
+
+      # ====================
+      # VALIDATION METHODS
+      # ====================
+
+      # Validate TTL configuration
+      #
+      # Ensures TTL values are positive and logical
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate_ttl_configuration
+        errors = []
+
+        errors << "default_ttl must be positive (got: #{default_ttl})" if default_ttl <= 0
+
+        errors << "min_adaptive_ttl must be positive (got: #{min_adaptive_ttl})" if min_adaptive_ttl <= 0
+
+        errors << "max_adaptive_ttl must be positive (got: #{max_adaptive_ttl})" if max_adaptive_ttl <= 0
+
+        if min_adaptive_ttl >= max_adaptive_ttl
+          errors << "min_adaptive_ttl (#{min_adaptive_ttl}) must be less than max_adaptive_ttl (#{max_adaptive_ttl})"
+        end
+
+        errors << "dashboard_cache_ttl must be positive (got: #{dashboard_cache_ttl})" if dashboard_cache_ttl <= 0
+
+        errors
+      end
+
+      # Validate algorithm parameters
+      #
+      # Ensures smoothing factors and thresholds are within valid ranges
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate_algorithm_parameters
+        errors = []
+
+        unless (0.0..1.0).cover?(hit_rate_smoothing_factor)
+          errors << "hit_rate_smoothing_factor must be between 0.0 and 1.0 (got: #{hit_rate_smoothing_factor})"
+        end
+
+        unless (0.0..1.0).cover?(access_frequency_decay_rate)
+          errors << "access_frequency_decay_rate must be between 0.0 and 1.0 (got: #{access_frequency_decay_rate})"
+        end
+
+        unless (0.0..1.0).cover?(cache_pressure_threshold)
+          errors << "cache_pressure_threshold must be between 0.0 and 1.0 (got: #{cache_pressure_threshold})"
+        end
+
+        if adaptive_calculation_interval <= 0
+          errors << "adaptive_calculation_interval must be positive (got: #{adaptive_calculation_interval})"
+        end
+
+        errors
+      end
+
+      # Validate entire configuration
+      #
+      # Runs all validation checks and raises if any errors found
+      # @raise [ArgumentError] If configuration is invalid
+      def validate!
+        errors = validate_ttl_configuration + validate_algorithm_parameters
+
+        return if errors.empty?
+
+        raise ArgumentError, "Invalid cache configuration: #{errors.join(', ')}"
+      end
+
+      # Calculate adaptive TTL based on performance data
+      #
+      # @param base_ttl [Integer] Base TTL to adjust
+      # @param hit_rate [Float] Current cache hit rate (0.0-1.0)
+      # @param generation_time [Float] Average generation time in seconds
+      # @param access_frequency [Integer] Access frequency count
+      # @return [Integer] Calculated adaptive TTL
+      def calculate_adaptive_ttl(base_ttl, hit_rate: 0.0, generation_time: 0.0, access_frequency: 0)
+        return base_ttl unless adaptive_ttl_enabled
+
+        # Start with base TTL as float for more precise calculations
+        adaptive_ttl = base_ttl.to_f
+
+        # Adjust based on hit rate (only if we have meaningful data)
+        if hit_rate > 0.8
+          adaptive_ttl *= 1.5  # High hit rate, extend TTL
+        elsif hit_rate > 0.0 && hit_rate < 0.3
+          adaptive_ttl *= 0.7  # Low hit rate, reduce TTL
+        end
+
+        # Adjust based on generation time (only if we have meaningful data)
+        if generation_time > 1.0
+          adaptive_ttl *= 1.3  # Expensive to generate, cache longer
+        elsif generation_time > 0.0 && generation_time < 0.1
+          adaptive_ttl *= 0.8  # Cheap to generate, cache shorter
+        end
+
+        # Adjust based on access frequency (only if we have meaningful data)
+        if access_frequency > 100
+          adaptive_ttl *= 1.2  # Frequently accessed, cache longer
+        elsif access_frequency.positive? && access_frequency < 5
+          adaptive_ttl *= 0.9  # Rarely accessed, cache shorter
+        end
+
+        # Convert to integer and apply bounds
+        adaptive_ttl.to_i.clamp(min_adaptive_ttl, max_adaptive_ttl)
+      end
+
+      # Check if cache is under pressure
+      #
+      # @param utilization [Float] Current cache utilization (0.0-1.0)
+      # @return [Boolean] Whether cache is under pressure
+      def cache_under_pressure?(utilization)
+        utilization >= cache_pressure_threshold
+      end
+    end
+  end
+end

data/lib/tasker/types/database_config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for database settings
+    #
+    # This configuration handles database connection settings for Tasker.
+    # It provides the same functionality as the original DatabaseConfiguration but with
+    # dry-struct type safety and immutability.
+    #
+    # @example Basic usage
+    #   config = DatabaseConfig.new(
+    #     name: :secondary,
+    #     enable_secondary_database: true
+    #   )
+    #
+    # @example Default configuration
+    #   config = DatabaseConfig.new
+    #   # Uses default database, no secondary database
+    class DatabaseConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Database name or configuration key type that accepts strings or symbols
+      NameType = Types::String | Types::Symbol
+
+      # Named database configuration from database.yml
+      #
+      # @!attribute [r] name
+      #   @return [String, Symbol, nil] Named database configuration key
+      attribute? :name, NameType.optional.default(nil)
+
+      # Whether to use a secondary database for Tasker models
+      #
+      # @!attribute [r] enable_secondary_database
+      #   @return [Boolean] Whether to use secondary database
+      attribute :enable_secondary_database, Types::Bool.default(false)
+    end
+  end
+end

data/lib/tasker/types/dependency_graph.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Represents a single node in a dependency graph
+    #
+    # A node can represent either a step template (for template graphs)
+    # or a workflow step instance (for runtime graphs).
+    #
+    # @example Template graph node
+    #   node = GraphNode.new(
+    #     id: 'validate_payment',
+    #     name: 'validate_payment',
+    #     type: 'step_template',
+    #     metadata: { retryable: true, retry_limit: 3 }
+    #   )
+    #
+    # @example Runtime graph node
+    #   node = GraphNode.new(
+    #     id: '12345',
+    #     name: 'validate_payment',
+    #     type: 'workflow_step',
+    #     state: 'complete',
+    #     readiness_status: { ready_for_execution: false },
+    #     metadata: { step_class: 'ValidatePaymentStep' }
+    #   )
+    class GraphNode < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # Unique identifier for this node
+      # For templates: step name
+      # For runtime: step ID as string
+      #
+      # @!attribute [r] id
+      #   @return [String] Node identifier
+      attribute :id, Types::String
+
+      # Human-readable name of the node
+      #
+      # @!attribute [r] name
+      #   @return [String] Node name
+      attribute :name, Types::String
+
+      # Type of node: 'step_template' or 'workflow_step'
+      #
+      # @!attribute [r] type
+      #   @return [String] Node type
+      attribute :type, Types::String
+
+      # Current state (for runtime graphs only)
+      #
+      # @!attribute [r] state
+      #   @return [String, nil] Current state of the step
+      attribute? :state, Types::String.optional
+
+      # Readiness status information (for runtime graphs only)
+      #
+      # @!attribute [r] readiness_status
+      #   @return [Hash, nil] Step readiness information
+      attribute? :readiness_status, Types::Hash.optional
+
+      # Additional metadata about the node
+      #
+      # @!attribute [r] metadata
+      #   @return [Hash] Node metadata
+      attribute :metadata, Types::Hash.default({}.freeze)
+    end
+
+    # Represents a relationship between two nodes in a dependency graph
+    #
+    # @example Basic edge
+    #   edge = GraphEdge.new(
+    #     from: 'validate_payment',
+    #     to: 'update_inventory',
+    #     relationship: 'prerequisite'
+    #   )
+    #
+    # @example Edge with metadata
+    #   edge = GraphEdge.new(
+    #     from: 'step_1',
+    #     to: 'step_2',
+    #     relationship: 'prerequisite',
+    #     metadata: { weight: 1.5, critical_path: true }
+    #   )
+    class GraphEdge < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # Source node identifier
+      #
+      # @!attribute [r] from
+      #   @return [String] Source node ID
+      attribute :from, Types::String
+
+      # Target node identifier
+      #
+      # @!attribute [r] to
+      #   @return [String] Target node ID
+      attribute :to, Types::String
+
+      # Type of relationship between nodes
+      #
+      # @!attribute [r] relationship
+      #   @return [String] Relationship type
+      attribute :relationship, Types::String.default('prerequisite')
+
+      # Additional metadata about the relationship
+      #
+      # @!attribute [r] metadata
+      #   @return [Hash] Edge metadata
+      attribute :metadata, Types::Hash.default({}.freeze)
+    end
+
+    # Metadata about the overall dependency graph
+    #
+    # @example Template graph metadata
+    #   metadata = GraphMetadata.new(
+    #     graph_type: 'template',
+    #     handler_name: 'order_processing',
+    #     total_nodes: 5,
+    #     total_edges: 4
+    #   )
+    #
+    # @example Runtime graph metadata
+    #   metadata = GraphMetadata.new(
+    #     graph_type: 'runtime',
+    #     task_id: '12345',
+    #     total_nodes: 5,
+    #     total_edges: 4,
+    #     execution_context: {
+    #       ready_steps: 2,
+    #       blocked_steps: 1,
+    #       completed_steps: 2
+    #     }
+    #   )
+    class GraphMetadata < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # Type of graph: 'template' or 'runtime'
+      #
+      # @!attribute [r] graph_type
+      #   @return [String] Graph type
+      attribute :graph_type, Types::String
+
+      # Handler name (for template graphs)
+      #
+      # @!attribute [r] handler_name
+      #   @return [String, nil] Task handler name
+      attribute? :handler_name, Types::String.optional
+
+      # Task ID (for runtime graphs)
+      #
+      # @!attribute [r] task_id
+      #   @return [String, nil] Task identifier
+      attribute? :task_id, Types::String.optional
+
+      # Total number of nodes in the graph
+      #
+      # @!attribute [r] total_nodes
+      #   @return [Integer] Node count
+      attribute :total_nodes, Types::Integer
+
+      # Total number of edges in the graph
+      #
+      # @!attribute [r] total_edges
+      #   @return [Integer] Edge count
+      attribute :total_edges, Types::Integer
+
+      # Execution context information (for runtime graphs only)
+      #
+      # @!attribute [r] execution_context
+      #   @return [Hash, nil] Runtime execution information
+      attribute? :execution_context, Types::Hash.optional
+
+      # Additional metadata
+      #
+      # @!attribute [r] additional_data
+      #   @return [Hash] Additional graph metadata
+      attribute :additional_data, Types::Hash.default({}.freeze)
+    end
+
+    # Complete dependency graph structure
+    #
+    # @example Template dependency graph
+    #   graph = DependencyGraph.new(
+    #     nodes: [node1, node2],
+    #     edges: [edge1],
+    #     metadata: template_metadata
+    #   )
+    #
+    # @example Runtime dependency graph
+    #   graph = DependencyGraph.new(
+    #     nodes: [runtime_node1, runtime_node2],
+    #     edges: [runtime_edge1],
+    #     metadata: runtime_metadata
+    #   )
+    class DependencyGraph < BaseConfig
+      transform_keys(&:to_sym)
+
+      # All nodes in the dependency graph
+      #
+      # @!attribute [r] nodes
+      #   @return [Array<GraphNode>] Graph nodes
+      attribute :nodes, Types::Array.of(GraphNode)
+
+      # All edges in the dependency graph
+      #
+      # @!attribute [r] edges
+      #   @return [Array<GraphEdge>] Graph edges
+      attribute :edges, Types::Array.of(GraphEdge)
+
+      # Metadata about the overall graph
+      #
+      # @!attribute [r] metadata
+      #   @return [GraphMetadata] Graph metadata
+      attribute :metadata, GraphMetadata
+
+      def initialize(*)
+        super
+        # Explicitly freeze arrays for immutability
+        nodes.freeze
+        edges.freeze
+      end
+    end
+  end
+end

data/lib/tasker/types/dependency_graph_config.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for dependency graph calculation settings
+    #
+    # This configuration exposes previously hardcoded calculation constants
+    # used in dependency graph analysis and bottleneck detection.
+    #
+    # @example Basic usage
+    #   config = DependencyGraphConfig.new(
+    #     impact_multipliers: { downstream_weight: 5, blocked_weight: 15 }
+    #   )
+    #
+    # @example With all options
+    #   config = DependencyGraphConfig.new(
+    #     impact_multipliers: {
+    #       downstream_weight: 5,
+    #       blocked_weight: 15,
+    #       path_length_weight: 10,
+    #       completed_penalty: 15,
+    #       blocked_penalty: 25,
+    #       error_penalty: 30,
+    #       retry_penalty: 10
+    #     },
+    #     severity_multipliers: {
+    #       error_state: 2.0,
+    #       exhausted_retry_bonus: 0.5,
+    #       dependency_issue: 1.2
+    #     },
+    #     penalty_constants: {
+    #       retry_instability: 3,
+    #       non_retryable: 10,
+    #       exhausted_retry: 20
+    #     },
+    #     severity_thresholds: {
+    #       critical: 100,
+    #       high: 50,
+    #       medium: 20
+    #     },
+    #     duration_estimates: {
+    #       base_step_seconds: 30,
+    #       error_penalty_seconds: 60,
+    #       retry_penalty_seconds: 30
+    #     }
+    #   )
+    class DependencyGraphConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Impact multipliers for bottleneck scoring calculations
+      #
+      # These multipliers affect how different factors influence the final
+      # bottleneck impact scores in RuntimeGraphAnalyzer.
+      #
+      # @!attribute [r] impact_multipliers
+      #   @return [Hash<Symbol, Integer>] Impact calculation multipliers
+      attribute :impact_multipliers, Types::Hash.schema(
+        downstream_weight: Types::Integer.default(5),
+        blocked_weight: Types::Integer.default(15),
+        path_length_weight: Types::Integer.default(10),
+        completed_penalty: Types::Integer.default(15),
+        blocked_penalty: Types::Integer.default(25),
+        error_penalty: Types::Integer.default(30),
+        retry_penalty: Types::Integer.default(10)
+      ).constructor { |value| value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value }
+                                                .default({
+                                                  downstream_weight: 5,
+                                                  blocked_weight: 15,
+                                                  path_length_weight: 10,
+                                                  completed_penalty: 15,
+                                                  blocked_penalty: 25,
+                                                  error_penalty: 30,
+                                                  retry_penalty: 10
+                                                }.freeze)
+
+      # Severity multipliers for state-based calculations
+      #
+      # These multipliers adjust impact scores based on step states
+      # and execution conditions.
+      #
+      # @!attribute [r] severity_multipliers
+      #   @return [Hash<Symbol, Float>] State severity multipliers
+      attribute :severity_multipliers, Types::Hash.schema(
+        error_state: Types::Float.default(2.0),
+        exhausted_retry_bonus: Types::Float.default(0.5),
+        dependency_issue: Types::Float.default(1.2)
+      ).constructor { |value| value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value }
+                                                  .default({
+                                                    error_state: 2.0,
+                                                    exhausted_retry_bonus: 0.5,
+                                                    dependency_issue: 1.2
+                                                  }.freeze)
+
+      # Penalty constants for problematic step conditions
+      #
+      # These constants add penalty points for retry instability,
+      # non-retryable issues, and exhausted retry attempts.
+      #
+      # @!attribute [r] penalty_constants
+      #   @return [Hash<Symbol, Integer>] Penalty calculation constants
+      attribute :penalty_constants, Types::Hash.schema(
+        retry_instability: Types::Integer.default(3),
+        non_retryable: Types::Integer.default(10),
+        exhausted_retry: Types::Integer.default(20)
+      ).constructor { |value| value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value }
+                                               .default({
+                                                 retry_instability: 3,
+                                                 non_retryable: 10,
+                                                 exhausted_retry: 20
+                                               }.freeze)
+
+      # Severity thresholds for impact score classification
+      #
+      # These thresholds determine when bottlenecks are classified as
+      # Critical, High, Medium, or Low severity.
+      #
+      # @!attribute [r] severity_thresholds
+      #   @return [Hash<Symbol, Integer>] Severity classification thresholds
+      attribute :severity_thresholds, Types::Hash.schema(
+        critical: Types::Integer.default(100),
+        high: Types::Integer.default(50),
+        medium: Types::Integer.default(20)
+      ).constructor { |value| value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value }
+                                                 .default({
+                                                   critical: 100,
+                                                   high: 50,
+                                                   medium: 20
+                                                 }.freeze)
+
+      # Duration estimation constants for path analysis
+      #
+      # These constants are used for estimating execution times
+      # and calculating path durations.
+      #
+      # @!attribute [r] duration_estimates
+      #   @return [Hash<Symbol, Integer>] Duration estimation constants in seconds
+      attribute :duration_estimates, Types::Hash.schema(
+        base_step_seconds: Types::Integer.default(30),
+        error_penalty_seconds: Types::Integer.default(60),
+        retry_penalty_seconds: Types::Integer.default(30)
+      ).constructor { |value| value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value }
+                                                .default({
+                                                  base_step_seconds: 30,
+                                                  error_penalty_seconds: 60,
+                                                  retry_penalty_seconds: 30
+                                                }.freeze)
+    end
+  end
+end