tasker-engine 1.0.0

data/config/routes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# typed: false
+
+Tasker::Engine.routes.draw do
+  # Health check endpoints
+  scope '/health', as: :health do
+    get :ready, to: 'health#ready'
+    get :live, to: 'health#live'
+    get :status, to: 'health#status'
+  end
+
+  # Metrics endpoint
+  get '/metrics', to: 'metrics#index'
+
+  # Analytics endpoints
+  scope '/analytics', as: :analytics do
+    get :performance, to: 'analytics#performance'
+    get :bottlenecks, to: 'analytics#bottlenecks'
+  end
+
+  # Handler discovery endpoints
+  get '/handlers', to: 'handlers#index' # List namespaces
+  get '/handlers/:namespace', to: 'handlers#show_namespace' # List handlers in namespace
+  get '/handlers/:namespace/:name', to: 'handlers#show'     # Show specific handler with dependency graph
+
+  post '/graphql', to: 'graphql#execute'
+  # mount Rswag::Ui::Engine => '/api-docs'
+  # mount Rswag::Api::Engine => '/api-docs'
+  resources :tasks do
+    resources :workflow_steps
+    resources :task_diagrams, only: %i[index]
+  end
+end

data/config/tasker/subscriptions/example_integrations.yml

@@ -0,0 +1,67 @@
+# Example Event Subscription Configuration
+# This file demonstrates how to configure event subscriptions for various integrations
+# Place your subscription files in config/tasker/subscriptions/
+
+subscriptions:
+  # Sentry Integration - Error tracking for failed tasks and steps
+  sentry_integration:
+    class: 'SentrySubscriber'
+    enabled: true
+    events:
+      - 'task.failed'
+      - 'step.failed'
+      - 'workflow.error'
+    config:
+      dsn: 'https://your-sentry-dsn@sentry.io/project-id'
+      environment: 'production'
+      tags:
+        component: 'tasker'
+
+  # PagerDuty Integration - Critical alerts for system issues
+  pagerduty_alerts:
+    class: 'PagerDutySubscriber'
+    enabled: false  # Disabled by default
+    events:
+      - 'task.failed'
+      - 'workflow.blocked'
+      - 'system.error'
+    config:
+      integration_key: 'your-pagerduty-integration-key'
+      severity: 'critical'
+
+  # Slack Integration - Team notifications for task completion
+  slack_notifications:
+    class: 'SlackSubscriber'
+    enabled: true
+    events:
+      - 'task.completed'
+      - 'task.failed'
+      - 'workflow.completed'
+    config:
+      webhook_url: 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK'
+      channel: '#engineering'
+      username: 'Tasker Bot'
+
+  # Custom Analytics Integration - Track task metrics
+  analytics_tracker:
+    class: 'AnalyticsSubscriber'
+    enabled: true
+    events:
+      - 'task.started'
+      - 'task.completed'
+      - 'task.failed'
+      - 'step.completed'
+      - 'step.failed'
+    config:
+      api_key: 'your-analytics-api-key'
+      endpoint: 'https://api.analytics.com/events'
+
+  # Development Debug Subscriber - Detailed logging for development
+  debug_logger:
+    class: 'DebugSubscriber'
+    enabled: false  # Only enable in development
+    events:
+      - '*'  # Subscribe to all events
+    config:
+      log_level: 'debug'
+      include_payload: true

data/config/tasker/system_events.yml

@@ -0,0 +1,305 @@
+---
+# Tasker System Events Metadata & State Machine Configuration
+#
+# This file provides rich metadata about system events and state machine mappings.
+# The actual event constants are defined in lib/tasker/constants.rb.
+#
+# This file serves two purposes:
+# 1. Event metadata for runtime introspection (descriptions, schemas, etc.)
+# 2. State machine transition mappings for declarative configuration
+
+# Event metadata for runtime introspection and documentation
+event_metadata:
+  # Task lifecycle events
+  task:
+    initialize_requested:
+      description: "Fired when a task is being created and initialized"
+      constant_ref: "Tasker::Constants::TaskEvents::INITIALIZE_REQUESTED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        task_name: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["TaskBuilder", "TaskStateMachine"]
+
+    start_requested:
+      description: "Fired when a task processing begins"
+      constant_ref: "Tasker::Constants::TaskEvents::START_REQUESTED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        task_name: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["TaskHandler", "TaskStateMachine"]
+
+    completed:
+      description: "Fired when a task completes successfully"
+      constant_ref: "Tasker::Constants::TaskEvents::COMPLETED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        task_name: { type: "String", required: true }
+        total_steps: { type: "Integer", required: true }
+        completed_steps: { type: "Integer", required: true }
+        total_duration: { type: "Float", required: false }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["TaskHandler", "TaskStateMachine"]
+
+    failed:
+      description: "Fired when a task fails due to errors"
+      constant_ref: "Tasker::Constants::TaskEvents::FAILED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        task_name: { type: "String", required: true }
+        error_message: { type: "String", required: true }
+        failed_steps: { type: "Array", required: false }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["TaskHandler", "TaskStateMachine"]
+
+    retry_requested:
+      description: "Fired when a task is queued for retry"
+      constant_ref: "Tasker::Constants::TaskEvents::RETRY_REQUESTED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        task_name: { type: "String", required: true }
+        retry_reason: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["TaskHandler", "TaskStateMachine"]
+
+  # Step lifecycle events
+  step:
+    execution_requested:
+      description: "Fired when a step is queued for execution"
+      constant_ref: "Tasker::Constants::StepEvents::EXECUTION_REQUESTED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        step_id: { type: "String", required: true }
+        step_name: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["StepExecutor", "StepStateMachine"]
+
+    before_handle:
+      description: "Fired just before a step handler is called"
+      constant_ref: "Tasker::Constants::StepEvents::BEFORE_HANDLE"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        step_id: { type: "String", required: true }
+        step_name: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["StepHandler::Base", "StepHandler::Api"]
+
+    completed:
+      description: "Fired when a step completes successfully"
+      constant_ref: "Tasker::Constants::StepEvents::COMPLETED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        step_id: { type: "String", required: true }
+        step_name: { type: "String", required: true }
+        execution_duration: { type: "Float", required: true }
+        attempt_number: { type: "Integer", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["StepHandler::Base", "StepHandler::Api", "StepStateMachine"]
+
+    failed:
+      description: "Fired when a step fails during execution"
+      constant_ref: "Tasker::Constants::StepEvents::FAILED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        step_id: { type: "String", required: true }
+        step_name: { type: "String", required: true }
+        error_message: { type: "String", required: true }
+        error_class: { type: "String", required: true }
+        backtrace: { type: "Array", required: false }
+        attempt_number: { type: "Integer", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["StepHandler::Base", "StepHandler::Api", "StepStateMachine"]
+
+  # Workflow orchestration events
+  workflow:
+    viable_steps_discovered:
+      description: "Fired when steps are identified as ready for execution"
+      constant_ref: "Tasker::Constants::WorkflowEvents::VIABLE_STEPS_DISCOVERED"
+      payload_schema:
+        task_id: { type: "String", required: true }
+        step_ids: { type: "Array", required: true }
+        step_count: { type: "Integer", required: true }
+        processing_mode: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["ViableStepDiscovery", "WorkflowOrchestrator"]
+
+  # Registry system events
+  handler:
+    registered:
+      description: "Fired when a handler is successfully registered"
+      constant_ref: "Tasker::Constants::RegistryEvents::HANDLER_REGISTERED"
+      payload_schema:
+        handler_class: { type: "String", required: true }
+        namespace_name: { type: "String", required: true }
+        version: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["HandlerFactory", "Registry::BaseRegistry"]
+
+    unregistered:
+      description: "Fired when a handler is unregistered"
+      constant_ref: "Tasker::Constants::RegistryEvents::HANDLER_UNREGISTERED"
+      payload_schema:
+        handler_class: { type: "String", required: true }
+        namespace_name: { type: "String", required: true }
+        version: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["HandlerFactory", "Registry::BaseRegistry"]
+
+    validation_failed:
+      description: "Fired when handler validation fails during registration"
+      constant_ref: "Tasker::Constants::RegistryEvents::HANDLER_VALIDATION_FAILED"
+      payload_schema:
+        handler_class: { type: "String", required: true }
+        validation_error: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["HandlerFactory", "Registry::InterfaceValidator"]
+
+  plugin:
+    registered:
+      description: "Fired when a plugin is successfully registered"
+      constant_ref: "Tasker::Constants::RegistryEvents::PLUGIN_REGISTERED"
+      payload_schema:
+        plugin_class: { type: "String", required: true }
+        plugin_format: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["PluginRegistry", "ExportCoordinator"]
+
+    unregistered:
+      description: "Fired when a plugin is unregistered"
+      constant_ref: "Tasker::Constants::RegistryEvents::PLUGIN_UNREGISTERED"
+      payload_schema:
+        plugin_class: { type: "String", required: true }
+        plugin_format: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["PluginRegistry", "ExportCoordinator"]
+
+    validation_failed:
+      description: "Fired when plugin validation fails during registration"
+      constant_ref: "Tasker::Constants::RegistryEvents::PLUGIN_VALIDATION_FAILED"
+      payload_schema:
+        plugin_class: { type: "String", required: true }
+        validation_error: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["PluginRegistry", "Registry::InterfaceValidator"]
+
+  subscriber:
+    registered:
+      description: "Fired when a subscriber is successfully registered"
+      constant_ref: "Tasker::Constants::RegistryEvents::SUBSCRIBER_REGISTERED"
+      payload_schema:
+        subscriber_class: { type: "String", required: true }
+        events: { type: "Array", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["SubscriberRegistry", "Events::CustomRegistry"]
+
+    unregistered:
+      description: "Fired when a subscriber is unregistered"
+      constant_ref: "Tasker::Constants::RegistryEvents::SUBSCRIBER_UNREGISTERED"
+      payload_schema:
+        subscriber_class: { type: "String", required: true }
+        events: { type: "Array", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["SubscriberRegistry", "Events::CustomRegistry"]
+
+    validation_failed:
+      description: "Fired when subscriber validation fails during registration"
+      constant_ref: "Tasker::Constants::RegistryEvents::SUBSCRIBER_VALIDATION_FAILED"
+      payload_schema:
+        subscriber_class: { type: "String", required: true }
+        validation_error: { type: "String", required: true }
+        timestamp: { type: "Time", required: true }
+      fired_by: ["SubscriberRegistry", "Registry::InterfaceValidator"]
+
+# State machine transition mappings (declarative configuration)
+state_machine_mappings:
+  task_transitions:
+    # Initial state transitions (from nil/initial)
+    - from_state: null
+      to_state: "pending"
+      event_constant: "task.initialize_requested"
+      description: "Task initialization"
+
+    - from_state: null
+      to_state: "in_progress"
+      event_constant: "task.start_requested"
+      description: "Direct task start"
+
+    - from_state: null
+      to_state: "complete"
+      event_constant: "task.completed"
+      description: "Direct task completion"
+
+    - from_state: null
+      to_state: "error"
+      event_constant: "task.failed"
+      description: "Direct task failure"
+
+    - from_state: null
+      to_state: "cancelled"
+      event_constant: "task.cancelled"
+      description: "Direct task cancellation"
+
+    - from_state: null
+      to_state: "resolved_manually"
+      event_constant: "task.resolved_manually"
+      description: "Direct manual resolution"
+
+    # Normal state transitions
+    - from_state: "pending"
+      to_state: "in_progress"
+      event_constant: "task.start_requested"
+      description: "Task starts processing"
+
+    - from_state: "pending"
+      to_state: "cancelled"
+      event_constant: "task.cancelled"
+      description: "Pending task cancelled"
+
+    - from_state: "pending"
+      to_state: "error"
+      event_constant: "task.failed"
+      description: "Pending task failed"
+
+    - from_state: "in_progress"
+      to_state: "pending"
+      event_constant: "task.initialize_requested"
+      description: "Reset task to pending"
+
+    - from_state: "in_progress"
+      to_state: "complete"
+      event_constant: "task.completed"
+      description: "Task completed successfully"
+
+    - from_state: "in_progress"
+      to_state: "error"
+      event_constant: "task.failed"
+      description: "Task failed during processing"
+
+    - from_state: "in_progress"
+      to_state: "cancelled"
+      event_constant: "task.cancelled"
+      description: "Running task cancelled"
+
+    - from_state: "error"
+      to_state: "pending"
+      event_constant: "task.retry_requested"
+      description: "Failed task retry"
+
+    - from_state: "error"
+      to_state: "resolved_manually"
+      event_constant: "task.resolved_manually"
+      description: "Failed task manually resolved"
+
+    # Admin override scenarios
+    - from_state: "complete"
+      to_state: "cancelled"
+      event_constant: "task.cancelled"
+      description: "Admin cancellation override"
+
+    - from_state: "resolved_manually"
+      to_state: "cancelled"
+      event_constant: "task.cancelled"
+      description: "Manual resolution cancelled"
+
+

data/db/functions/calculate_dependency_levels_v01.sql

@@ -0,0 +1,45 @@
+-- Calculate Dependency Levels Function
+-- Calculates the dependency level (depth) of each workflow step in a task
+-- Uses recursive CTE to traverse the dependency graph and assign levels
+-- Input: task_id
+-- Output: workflow_step_id and its dependency level (0 = root, 1+ = depth from root)
+
+CREATE OR REPLACE FUNCTION calculate_dependency_levels(input_task_id BIGINT)
+RETURNS TABLE(
+  workflow_step_id BIGINT,
+  dependency_level INTEGER
+) LANGUAGE plpgsql STABLE AS $$
+BEGIN
+  RETURN QUERY
+  WITH RECURSIVE dependency_levels AS (
+    -- Base case: Find root nodes (steps with no dependencies)
+    SELECT
+      ws.workflow_step_id,
+      0 as level
+    FROM tasker_workflow_steps ws
+    WHERE ws.task_id = input_task_id
+      AND NOT EXISTS (
+        SELECT 1
+        FROM tasker_workflow_step_edges wse
+        WHERE wse.to_step_id = ws.workflow_step_id
+      )
+
+    UNION ALL
+
+    -- Recursive case: Find children of current level nodes
+    SELECT
+      wse.to_step_id as workflow_step_id,
+      dl.level + 1 as level
+    FROM dependency_levels dl
+    JOIN tasker_workflow_step_edges wse ON wse.from_step_id = dl.workflow_step_id
+    JOIN tasker_workflow_steps ws ON ws.workflow_step_id = wse.to_step_id
+    WHERE ws.task_id = input_task_id
+  )
+  SELECT
+    dl.workflow_step_id,
+    MAX(dl.level) as dependency_level  -- Use MAX to handle multiple paths to same node
+  FROM dependency_levels dl
+  GROUP BY dl.workflow_step_id
+  ORDER BY dependency_level, workflow_step_id;
+END;
+$$;

data/db/functions/get_analytics_metrics_v01.sql

@@ -0,0 +1,137 @@
+-- Analytics Metrics Function
+-- Returns comprehensive analytics metrics for performance monitoring
+-- Input: since_timestamp for time-based filtering
+-- Output: Single row with all analytics metrics
+
+CREATE OR REPLACE FUNCTION get_analytics_metrics_v01(since_timestamp TIMESTAMPTZ DEFAULT NULL)
+RETURNS TABLE (
+    -- System overview metrics
+    active_tasks_count BIGINT,
+    total_namespaces_count BIGINT,
+    unique_task_types_count BIGINT,
+    system_health_score NUMERIC(5,3),
+    
+    -- Performance metrics since timestamp
+    task_throughput BIGINT,
+    completion_count BIGINT,
+    error_count BIGINT,
+    completion_rate NUMERIC(5,2),
+    error_rate NUMERIC(5,2),
+    
+    -- Duration metrics (in seconds)
+    avg_task_duration NUMERIC(10,3),
+    avg_step_duration NUMERIC(10,3),
+    step_throughput BIGINT,
+    
+    -- Metadata
+    analysis_period_start TIMESTAMPTZ,
+    calculated_at TIMESTAMPTZ
+) LANGUAGE plpgsql STABLE AS $$
+DECLARE
+    analysis_start TIMESTAMPTZ;
+BEGIN
+    -- Set analysis start time (default to 1 hour ago if not provided)
+    analysis_start := COALESCE(since_timestamp, NOW() - INTERVAL '1 hour');
+    
+    RETURN QUERY
+    WITH active_tasks AS (
+        SELECT COUNT(DISTINCT t.task_id) as active_count
+        FROM tasker_tasks t
+        INNER JOIN tasker_workflow_steps ws ON ws.task_id = t.task_id
+        INNER JOIN tasker_workflow_step_transitions wst ON wst.workflow_step_id = ws.workflow_step_id
+        WHERE wst.most_recent = true
+          AND wst.to_state NOT IN ('complete', 'error', 'skipped', 'resolved_manually')
+    ),
+    namespace_summary AS (
+        SELECT COUNT(DISTINCT tn.name) as namespace_count
+        FROM tasker_task_namespaces tn
+        INNER JOIN tasker_named_tasks nt ON nt.task_namespace_id = tn.task_namespace_id
+        INNER JOIN tasker_tasks t ON t.named_task_id = nt.named_task_id
+    ),
+    task_type_summary AS (
+        SELECT COUNT(DISTINCT nt.name) as task_type_count
+        FROM tasker_named_tasks nt
+        INNER JOIN tasker_tasks t ON t.named_task_id = nt.named_task_id
+    ),
+    recent_task_health AS (
+        SELECT 
+            COUNT(DISTINCT t.task_id) as total_recent_tasks,
+            COUNT(DISTINCT t.task_id) FILTER (
+                WHERE wst.to_state = 'complete' AND wst.most_recent = true
+            ) as completed_tasks,
+            COUNT(DISTINCT t.task_id) FILTER (
+                WHERE wst.to_state = 'error' AND wst.most_recent = true
+            ) as error_tasks
+        FROM tasker_tasks t
+        INNER JOIN tasker_workflow_steps ws ON ws.task_id = t.task_id
+        INNER JOIN tasker_workflow_step_transitions wst ON wst.workflow_step_id = ws.workflow_step_id
+        WHERE t.created_at > NOW() - INTERVAL '1 hour'
+    ),
+    period_metrics AS (
+        SELECT 
+            COUNT(DISTINCT t.task_id) as throughput,
+            COUNT(DISTINCT t.task_id) FILTER (
+                WHERE completed_wst.to_state = 'complete' AND completed_wst.most_recent = true
+            ) as completions,
+            COUNT(DISTINCT t.task_id) FILTER (
+                WHERE error_wst.to_state = 'error' AND error_wst.most_recent = true
+            ) as errors,
+            COUNT(DISTINCT ws.workflow_step_id) as step_count,
+            AVG(
+                CASE 
+                    WHEN completed_wst.to_state = 'complete' AND completed_wst.most_recent = true
+                    THEN EXTRACT(EPOCH FROM (completed_wst.created_at - t.created_at))
+                    ELSE NULL
+                END
+            ) as avg_task_seconds,
+            AVG(
+                CASE 
+                    WHEN step_completed.to_state = 'complete' AND step_completed.most_recent = true
+                    THEN EXTRACT(EPOCH FROM (step_completed.created_at - ws.created_at))
+                    ELSE NULL
+                END
+            ) as avg_step_seconds
+        FROM tasker_tasks t
+        LEFT JOIN tasker_workflow_steps ws ON ws.task_id = t.task_id
+        LEFT JOIN tasker_workflow_step_transitions completed_wst ON completed_wst.workflow_step_id = ws.workflow_step_id
+            AND completed_wst.to_state = 'complete' AND completed_wst.most_recent = true
+        LEFT JOIN tasker_workflow_step_transitions error_wst ON error_wst.workflow_step_id = ws.workflow_step_id
+            AND error_wst.to_state = 'error' AND error_wst.most_recent = true
+        LEFT JOIN tasker_workflow_step_transitions step_completed ON step_completed.workflow_step_id = ws.workflow_step_id
+            AND step_completed.to_state = 'complete' AND step_completed.most_recent = true
+        WHERE t.created_at > analysis_start
+    )
+    SELECT 
+        at.active_count,
+        ns.namespace_count,
+        tts.task_type_count,
+        CASE 
+            WHEN (rth.completed_tasks + rth.error_tasks) > 0 
+            THEN ROUND((rth.completed_tasks::NUMERIC / (rth.completed_tasks + rth.error_tasks)), 3)
+            ELSE 1.0
+        END as health_score,
+        pm.throughput,
+        pm.completions,
+        pm.errors,
+        CASE 
+            WHEN pm.throughput > 0 
+            THEN ROUND((pm.completions::NUMERIC / pm.throughput * 100), 2)
+            ELSE 0.0
+        END as completion_rate_pct,
+        CASE 
+            WHEN pm.throughput > 0 
+            THEN ROUND((pm.errors::NUMERIC / pm.throughput * 100), 2)
+            ELSE 0.0
+        END as error_rate_pct,
+        ROUND(COALESCE(pm.avg_task_seconds, 0), 3),
+        ROUND(COALESCE(pm.avg_step_seconds, 0), 3),
+        pm.step_count,
+        analysis_start,
+        NOW()
+    FROM active_tasks at
+    CROSS JOIN namespace_summary ns
+    CROSS JOIN task_type_summary tts
+    CROSS JOIN recent_task_health rth
+    CROSS JOIN period_metrics pm;
+END;
+$$;

data/db/functions/get_slowest_steps_v01.sql

@@ -0,0 +1,82 @@
+-- Slowest Steps Analysis Function  
+-- Returns the slowest workflow steps within a specified time period
+-- Input: since_timestamp, limit_count, and optional filters
+-- Output: Ranked list of slowest steps with duration and context
+
+CREATE OR REPLACE FUNCTION get_slowest_steps_v01(
+    since_timestamp TIMESTAMPTZ DEFAULT NULL,
+    limit_count INTEGER DEFAULT 10,
+    namespace_filter TEXT DEFAULT NULL,
+    task_name_filter TEXT DEFAULT NULL,
+    version_filter TEXT DEFAULT NULL
+)
+RETURNS TABLE (
+    workflow_step_id BIGINT,
+    task_id BIGINT,
+    step_name VARCHAR(128),
+    task_name VARCHAR(64),
+    namespace_name VARCHAR(64),
+    version VARCHAR(64),
+    duration_seconds NUMERIC(10,3),
+    attempts INTEGER,
+    created_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    retryable BOOLEAN,
+    step_status VARCHAR(64)
+) LANGUAGE plpgsql STABLE AS $$
+DECLARE
+    analysis_start TIMESTAMPTZ;
+BEGIN
+    -- Set analysis start time (default to 24 hours ago if not provided)
+    analysis_start := COALESCE(since_timestamp, NOW() - INTERVAL '24 hours');
+    
+    RETURN QUERY
+    WITH step_durations AS (
+        SELECT 
+            ws.workflow_step_id,
+            ws.task_id,
+            ns.name as step_name,
+            nt.name as task_name,
+            tn.name as namespace_name,
+            nt.version,
+            ws.created_at,
+            ws.attempts,
+            ws.retryable,
+            -- Find the completion time
+            wst.created_at as completion_time,
+            wst.to_state as final_state,
+            -- Calculate duration from step creation to completion
+            EXTRACT(EPOCH FROM (wst.created_at - ws.created_at)) as duration_seconds
+        FROM tasker_workflow_steps ws
+        INNER JOIN tasker_named_steps ns ON ns.named_step_id = ws.named_step_id
+        INNER JOIN tasker_tasks t ON t.task_id = ws.task_id
+        INNER JOIN tasker_named_tasks nt ON nt.named_task_id = t.named_task_id
+        INNER JOIN tasker_task_namespaces tn ON tn.task_namespace_id = nt.task_namespace_id
+        INNER JOIN tasker_workflow_step_transitions wst ON wst.workflow_step_id = ws.workflow_step_id
+        WHERE ws.created_at > analysis_start
+          AND wst.most_recent = true
+          AND wst.to_state = 'complete'  -- Only include completed steps for accurate duration
+          AND (namespace_filter IS NULL OR tn.name = namespace_filter)
+          AND (task_name_filter IS NULL OR nt.name = task_name_filter)
+          AND (version_filter IS NULL OR nt.version = version_filter)
+    )
+    SELECT 
+        sd.workflow_step_id,
+        sd.task_id,
+        sd.step_name,
+        sd.task_name,
+        sd.namespace_name,
+        sd.version,
+        ROUND(sd.duration_seconds, 3),
+        sd.attempts,
+        sd.created_at,
+        sd.completion_time,
+        sd.retryable,
+        sd.final_state
+    FROM step_durations sd
+    WHERE sd.duration_seconds IS NOT NULL
+      AND sd.duration_seconds > 0  -- Filter out negative durations (data integrity check)
+    ORDER BY sd.duration_seconds DESC
+    LIMIT limit_count;
+END;
+$$;