@cascade-flow/backend-interface 0.1.0

package/dist/interface.d.ts

@@ -0,0 +1,745 @@
+import type { StepRecord, StepError, LogEntry, RunSubmission, RunState, WorkflowMetadata, WorkflowRegistration, StepDefinition } from "./schemas.ts";
+import type { Event, StepEvent, WorkflowEvent } from "./events.ts";
+import type { AnalyticsOptions, ErrorAnalysis, RetryAnalysis, SchedulingLatency, StepDuration, WorkflowDuration, WorkerStability, Throughput, QueueDepth, QueueDepthByWorkflow, SuccessRate, AnalyticsSummary } from "./analytics.ts";
+/**
+ * Metadata for when a step starts
+ */
+export type StepStartMetadata = {
+    dependencies: string[];
+    timestamp: number;
+    attemptNumber: number;
+};
+/**
+ * Metadata for when a step completes
+ */
+export type StepCompleteMetadata = {
+    timestamp: number;
+    duration: number;
+    logs?: LogEntry[];
+    attemptNumber: number;
+    output: unknown;
+};
+/**
+ * Detailed information about a workflow including its steps
+ * @deprecated Use WorkflowRegistration from schemas.ts instead
+ */
+export type WorkflowDetails = WorkflowMetadata & {
+    steps: StepDefinition[];
+    stepCount: number;
+};
+/**
+ * Abstract backend interface for persisting workflow execution state
+ *
+ * Implementations can store data in various backends (filesystem, database, cloud storage, etc.)
+ *
+ * This interface supports event sourcing: all state changes are recorded as
+ * immutable events, and current state is computed by replaying events.
+ */
+export declare abstract class Backend {
+    /**
+     * Initialize the backend (e.g., run migrations, create schema)
+     * Must be called before using the backend for any operations.
+     *
+     * For database backends, this runs schema migrations.
+     * For filesystem backends, this is typically a no-op.
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Initialize storage for a new workflow run
+     * Creates necessary directories, tables, or resources
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     */
+    abstract initializeRun(workflowSlug: string, runId: string): Promise<void>;
+    /**
+     * Record that a step has been scheduled for execution
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param metadata - Scheduling metadata
+     */
+    abstract saveStepScheduled(workflowSlug: string, runId: string, stepId: string, metadata: {
+        availableAt: number;
+        reason: "initial" | "retry" | "dependency-satisfied";
+        attemptNumber: number;
+        retryDelayMs?: number;
+    }): Promise<void>;
+    /**
+     * Record that a step has started executing
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param workerId - Worker executing the step
+     * @param metadata - Metadata about the step start (dependencies, timestamp)
+     */
+    abstract saveStepStart(workflowSlug: string, runId: string, stepId: string, workerId: string, metadata: StepStartMetadata): Promise<void>;
+    /**
+     * Record that a step has completed successfully
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param output - The output produced by the step (will be serialized)
+     * @param metadata - Metadata about the completion (timestamp, duration)
+     * @param exportOutput - Whether this step's output should be included in final workflow output (defaults to false)
+     */
+    abstract saveStepComplete(workflowSlug: string, runId: string, stepId: string, output: unknown, metadata: StepCompleteMetadata, exportOutput?: boolean): Promise<void>;
+    /**
+     * Record that a step has failed
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param error - The error that caused the failure
+     * @param metadata - Failure metadata
+     */
+    abstract saveStepFailed(workflowSlug: string, runId: string, stepId: string, error: StepError, metadata: {
+        duration: number;
+        attemptNumber: number;
+        terminal: boolean;
+        nextRetryAt?: number;
+        failureReason: "exhausted-retries" | "worker-crash" | "timeout" | "cancelled" | "execution-error";
+    }): Promise<void>;
+    /**
+     * Atomically record a step failure and schedule its retry
+     *
+     * This combines saveStepFailed + saveStepScheduled in a single atomic operation
+     * to prevent the race condition where only the failure event gets persisted.
+     *
+     * Emits:
+     * 1. StepFailed (terminal: false)
+     * 2. StepRetrying (informational)
+     * 3. StepScheduled (for retry)
+     *
+     * All three events are written atomically - either all succeed or none do.
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param error - The error that caused the failure
+     * @param failureMetadata - Failure metadata (duration, attemptNumber, nextRetryAt)
+     * @param scheduleMetadata - Retry scheduling metadata (availableAt, retryDelayMs)
+     */
+    abstract saveStepFailedAndScheduleRetry(workflowSlug: string, runId: string, stepId: string, error: StepError, failureMetadata: {
+        duration: number;
+        attemptNumber: number;
+        nextRetryAt: number;
+        failureReason: "execution-error" | "timeout";
+    }, scheduleMetadata: {
+        availableAt: number;
+        nextAttemptNumber: number;
+        retryDelayMs: number;
+        maxRetries: number;
+    }): Promise<void>;
+    /**
+     * Record that a step has been skipped
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param metadata - Skip metadata
+     */
+    abstract saveStepSkipped(workflowSlug: string, runId: string, stepId: string, metadata: {
+        skipType: "primary" | "cascade";
+        reason: string;
+        metadata?: Record<string, any>;
+        duration: number;
+        attemptNumber: number;
+        cascadedFrom?: string;
+    }): Promise<void>;
+    /**
+     * Record a heartbeat for a running step
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param workerId - Worker executing the step
+     * @param attemptNumber - Current attempt number
+     */
+    abstract saveStepHeartbeat(workflowSlug: string, runId: string, stepId: string, workerId: string, attemptNumber: number): Promise<void>;
+    /**
+     * Record that a step has been reclaimed from a stale worker
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param metadata - Reclamation metadata
+     */
+    abstract saveStepReclaimed(workflowSlug: string, runId: string, stepId: string, metadata: {
+        originalWorkerId: string;
+        reclaimedBy: string;
+        lastHeartbeat: number;
+        staleThreshold: number;
+        staleDuration: number;
+        attemptNumber: number;
+    }): Promise<void>;
+    /**
+     * Record that the workflow has completed successfully
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param output - The final workflow output (only exported steps)
+     * @param metadata - Metadata about the workflow completion (timestamp, duration, totalSteps)
+     */
+    abstract saveWorkflowComplete(workflowSlug: string, runId: string, output: unknown, metadata: {
+        workflowAttemptNumber: number;
+        timestamp: number;
+        duration: number;
+        totalSteps: number;
+    }): Promise<void>;
+    /**
+     * Save logs for a step
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param logs - Array of log entries
+     * @returns Path to the logs file
+     */
+    abstract saveStepLogs(workflowSlug: string, runId: string, stepId: string, logs: LogEntry[]): Promise<void>;
+    /**
+     * Load logs for a step
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @returns Array of log entries or null if no logs exist
+     */
+    abstract loadStepLogs(workflowSlug: string, runId: string, stepId: string, attemptNumber?: number): Promise<LogEntry[] | null>;
+    /**
+     * Load all step records for a given run
+     * Used for resuming interrupted workflows
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @returns Array of validated step records
+     */
+    abstract loadRun(workflowSlug: string, runId: string): Promise<StepRecord[]>;
+    /**
+     * Check if a run exists in the backend
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @returns true if the run exists, false otherwise
+     */
+    abstract runExists(workflowSlug: string, runId: string): Promise<boolean>;
+    /**
+     * Append an event to the event log
+     *
+     * Events are immutable and append-only. This is the core of event sourcing.
+     * Each event represents a state transition or action that occurred during execution.
+     * Events are routed to the appropriate directory based on their category (workflow vs step).
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param event - The event to append (either step or workflow event)
+     */
+    abstract appendEvent(workflowSlug: string, runId: string, event: Event): Promise<void>;
+    /**
+     * Load events from the event log
+     *
+     * Returns events in chronological order (sorted by timestamp).
+     * Can filter by category and/or stepId.
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param options - Optional filters for category and stepId (unique identifier)
+     * @returns Array of events in chronological order
+     */
+    abstract loadEvents(workflowSlug: string, runId: string, options: {
+        category: "step";
+        stepId?: string;
+    }): Promise<StepEvent[]>;
+    abstract loadEvents(workflowSlug: string, runId: string, options: {
+        category: "workflow";
+    }): Promise<WorkflowEvent[]>;
+    abstract loadEvents(workflowSlug: string, runId: string, options?: {
+        category?: "workflow" | "step";
+        stepId?: string;
+    }): Promise<Event[]>;
+    /**
+     * Get the file path for a step's output file
+     *
+     * Used for file-based step output storage. Returns the path where
+     * the subprocess executor should write the step's output.
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param stepId - Unique step identifier (directory name)
+     * @param attemptNumber - Attempt number (for retries)
+     * @returns Absolute path to the output file
+     */
+    abstract getStepOutputPath(workflowSlug: string, runId: string, stepId: string, attemptNumber: number): string;
+    /**
+     * Record that a workflow has started
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param metadata - Metadata about the workflow start
+     */
+    abstract saveWorkflowStart(workflowSlug: string, runId: string, metadata: {
+        workflowAttemptNumber: number;
+        hasInputSchema: boolean;
+        hasInput: boolean;
+    }): Promise<void>;
+    /**
+     * Record workflow input validation result (success or failure)
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param result - Validation result with schema info, success flag, and optional error
+     */
+    abstract saveWorkflowInputValidation(workflowSlug: string, runId: string, result: {
+        workflowAttemptNumber: number;
+        hasSchema: boolean;
+        success: boolean;
+        error?: StepError;
+        validationErrors?: Array<{
+            path: string;
+            message: string;
+        }>;
+    }): Promise<void>;
+    /**
+     * Record that a workflow has failed
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param error - The error that caused the failure
+     * @param metadata - Metadata about the failure
+     * @param failureReason - Why the workflow failed (step-failed, worker-crash, etc.)
+     */
+    abstract saveWorkflowFailed(workflowSlug: string, runId: string, error: StepError, metadata: {
+        workflowAttemptNumber: number;
+        duration: number;
+        completedSteps: number;
+        failedStep?: string;
+    }, failureReason: "step-failed" | "worker-crash" | "timeout" | "cancelled"): Promise<void>;
+    /**
+     * Record that a workflow has been resumed from a previous run
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param metadata - Metadata about the resume
+     */
+    abstract saveWorkflowResumed(workflowSlug: string, runId: string, metadata: {
+        originalRunId: string;
+        resumedSteps: number;
+        pendingSteps: number;
+    }): Promise<void>;
+    /**
+     * Record that a workflow has been cancelled
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param metadata - Metadata about the cancellation
+     */
+    abstract saveWorkflowCancelled(workflowSlug: string, runId: string, metadata: {
+        workflowAttemptNumber: number;
+        reason?: string;
+        duration: number;
+        completedSteps: number;
+    }): Promise<void>;
+    /**
+     * Record that a workflow retry has been initiated
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @param metadata - Metadata about the retry
+     */
+    abstract saveWorkflowRetryStarted(workflowSlug: string, runId: string, metadata: {
+        workflowAttemptNumber: number;
+        previousAttemptNumber: number;
+        retriedSteps: string[];
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get all failed steps in a workflow run
+     *
+     * @param workflowSlug - Workflow identifier (directory name)
+     * @param runId - Unique identifier for the workflow run
+     * @returns Array of failed step information
+     */
+    abstract getFailedSteps(workflowSlug: string, runId: string): Promise<Array<{
+        stepId: string;
+        error: StepError;
+        attemptNumber: number;
+    }>>;
+    /**
+     * Submit a run to the queue
+     *
+     * Handles idempotency: if a run with the same idempotencyKey already exists,
+     * returns the existing runId instead of creating a new one.
+     *
+     * @param submission - Run submission parameters
+     * @returns Object with runId and isNew flag (false if idempotency key matched)
+     */
+    abstract submitRun(submission: RunSubmission): Promise<{
+        runId: string;
+        isNew: boolean;
+    }>;
+    /**
+     * List all runs matching filters
+     *
+     * EVENTS-AS-QUEUE IMPLEMENTATION:
+     * - Scan workflow directories under baseDir
+     * - For each run, load workflow events and project to RunState
+     * - Filter by status, workflow, tags
+     * - Sort by createdAt (descending)
+     * - Apply limit
+     *
+     * @param options - Optional filters and pagination
+     * @returns Array of run states sorted by createdAt (newest first)
+     */
+    abstract listRuns(options?: {
+        workflowSlug?: string;
+        status?: RunState["status"][];
+        tags?: string[];
+        limit?: number;
+    }): Promise<RunState[]>;
+    /**
+     * Record that a run has been submitted to the queue
+     *
+     * Emits RunSubmitted event.
+     *
+     * @param workflowSlug - Workflow identifier
+     * @param runId - Unique identifier for the run
+     * @param metadata - Submission metadata
+     */
+    abstract saveRunSubmitted(workflowSlug: string, runId: string, metadata: {
+        availableAt: number;
+        priority: number;
+        input?: string;
+        hasInputSchema: boolean;
+        timeout?: number;
+        idempotencyKey?: string;
+        metadata?: Record<string, unknown>;
+        tags?: string[];
+    }): Promise<void>;
+    /**
+     * Cancel a run
+     *
+     * Can cancel runs in pending, claimed, or running status.
+     * Emits WorkflowCancelled event.
+     *
+     * @param runId - The run to cancel
+     * @param reason - Optional cancellation reason
+     */
+    abstract cancelRun(runId: string, reason?: string): Promise<void>;
+    /**
+     * Get the current state of a run
+     *
+     * @param runId - The run to query
+     * @returns The run state, or null if not found
+     */
+    abstract getRun(runId: string): Promise<RunState | null>;
+    /**
+     * List all active workflows (workflows with incomplete runs)
+     *
+     * Used by the scheduler loop to find workflows that need scheduling attention.
+     * A workflow is "active" if it has at least one run that is not in a terminal state
+     * (completed, failed, or cancelled).
+     *
+     * IMPLEMENTATION NOTE:
+     * - Scan workflow directories
+     * - For each workflow, check if it has any runs in non-terminal states
+     * - Return list of workflow slugs
+     *
+     * @returns Array of workflow slugs with active runs
+     */
+    abstract listActiveWorkflows(): Promise<string[]>;
+    /**
+     * List scheduled steps available for claiming
+     *
+     * STEP-LEVEL DISTRIBUTION:
+     * Scans all workflows for steps in "scheduled" status where availableAt <= now.
+     * Returns steps sorted by availableAt (earliest first).
+     *
+     * @param options - Optional filters
+     * @returns Array of step identifiers ready for execution
+     */
+    abstract listScheduledSteps(options?: {
+        availableBefore?: number;
+        workflowSlug?: string;
+        limit?: number;
+    }): Promise<Array<{
+        workflowSlug: string;
+        runId: string;
+        stepId: string;
+    }>>;
+    /**
+     * Check if a step is claimable for execution
+     *
+     * STEP-LEVEL DISTRIBUTION:
+     * - Load step events and project to StepState
+     * - Check if status === "scheduled" && availableAt <= now
+     * - Returns true if step can be claimed, false otherwise
+     *
+     * This is used by workers before emitting StepStarted to ensure atomicity.
+     *
+     * @param workflowSlug - Workflow identifier
+     * @param runId - Run identifier
+     * @param stepId - Unique step identifier (directory name)
+     * @returns true if step is claimable, false otherwise
+     */
+    abstract isStepClaimable(workflowSlug: string, runId: string, stepId: string): Promise<boolean>;
+    /**
+     * Atomically claim a scheduled step for execution.
+     *
+     * Implementations must ensure only one worker can transition a step
+     * from scheduled → running for a given attempt. If the step is no longer
+     * claimable (e.g. already running, completed, or not yet available),
+     * the method returns null.
+     *
+     * @param workflowSlug - Workflow identifier
+     * @param runId - Run identifier
+     * @param stepId - Unique step identifier (directory name)
+     * @param workerId - Worker attempting the claim
+     * @param metadata - Step start metadata (dependencies, timestamp)
+     * @returns Attempt number when claimed, or null if step could not be claimed
+     */
+    abstract claimScheduledStep(workflowSlug: string, runId: string, stepId: string, workerId: string, metadata: StepStartMetadata): Promise<{
+        attemptNumber: number;
+    } | null>;
+    /**
+     * Find steps with stale heartbeats and reclaim them
+     *
+     * STEP-LEVEL DISTRIBUTION:
+     * - Scan all workflows for steps in "running" status
+     * - Check lastHeartbeat timestamp
+     * - If stale (no heartbeat > threshold), emit StepReclaimed and re-schedule
+     *
+     * @param staleThreshold - Milliseconds since last heartbeat before considering stale
+     * @param reclaimedBy - Worker ID performing reclamation
+     * @returns Array of reclaimed step identifiers
+     */
+    abstract reclaimStaleSteps(staleThreshold: number, reclaimedBy: string): Promise<Array<{
+        workflowSlug: string;
+        runId: string;
+        stepId: string;
+    }>>;
+    /**
+     * Register a workflow with the backend
+     *
+     * Stores workflow metadata, input schema (as JSON Schema), and step definitions.
+     * This is called during worker startup after discovering workflows from the filesystem.
+     *
+     * @param registration - Complete workflow registration data
+     */
+    abstract registerWorkflow(registration: WorkflowRegistration): Promise<void>;
+    /**
+     * Get metadata for a specific workflow
+     *
+     * Returns workflow metadata including name, location, and input schema.
+     *
+     * @param slug - Workflow identifier
+     * @returns Workflow metadata, or null if not registered
+     */
+    abstract getWorkflowMetadata(slug: string): Promise<WorkflowMetadata | null>;
+    /**
+     * List all registered workflows
+     *
+     * Returns metadata for all workflows that have been registered with the backend.
+     *
+     * @returns Array of workflow metadata
+     */
+    abstract listWorkflowMetadata(): Promise<WorkflowMetadata[]>;
+    /**
+     * Get step definitions for a workflow
+     *
+     * Returns the step structure (names, dependencies, export flags) for a workflow.
+     *
+     * @param slug - Workflow identifier
+     * @returns Array of step definitions, or empty array if workflow not found
+     */
+    abstract getWorkflowSteps(slug: string): Promise<StepDefinition[]>;
+    /**
+     * List all run IDs for a workflow
+     *
+     * Returns all run IDs that exist for a given workflow.
+     * Used by worker to discover existing runs.
+     *
+     * @param workflowSlug - Workflow identifier
+     * @returns Array of run IDs
+     */
+    abstract listRunIds(workflowSlug: string): Promise<string[]>;
+    /**
+     * Close the backend and clean up resources
+     *
+     * This method should be called when the backend is no longer needed.
+     * For database backends, this closes connection pools.
+     * For filesystem backends, this is typically a no-op.
+     *
+     * After calling close(), the backend should not be used again.
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Get error analysis for workflows and steps
+     *
+     * Analyzes failure patterns, error types, and common error messages.
+     *
+     * @param options - Optional filters for time range, workflow, or step
+     * @returns Error analysis data
+     */
+    abstract getErrorAnalysis(options?: AnalyticsOptions): Promise<ErrorAnalysis>;
+    /**
+     * Get paginated list of errors grouped by fingerprint
+     *
+     * Returns errors grouped by composable fingerprints with aggregated statistics.
+     *
+     * @param options - Filtering and pagination options
+     * @returns Paginated list of error groups and total count
+     */
+    abstract getErrorsList(options?: {
+        timeRange?: {
+            start: number;
+            end: number;
+        };
+        workflowSlug?: string;
+        groupingStrategy?: 'exact' | 'normalized' | 'portable';
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        errors: Array<{
+            fingerprint: string;
+            errorMessage: string;
+            errorName: string;
+            sampleStack: string;
+            count: number;
+            affectedRuns: number;
+            firstSeen: number;
+            lastSeen: number;
+        }>;
+        total: number;
+    }>;
+    /**
+     * Get detailed information about a specific error by fingerprint
+     *
+     * Returns all occurrences of an error matching the given fingerprint.
+     *
+     * @param fingerprint - Composite fingerprint (nameHash:messageHash:stackHash)
+     * @param groupingStrategy - Which stack hash variant to use
+     * @param options - Filtering and pagination options
+     * @returns Error details with occurrences
+     */
+    abstract getErrorDetail(fingerprint: string, groupingStrategy: 'exact' | 'normalized' | 'portable', options?: {
+        timeRange?: {
+            start: number;
+            end: number;
+        };
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        fingerprint: string;
+        errorMessage: string;
+        errorName: string;
+        sampleStack: string;
+        totalCount: number;
+        affectedRuns: number;
+        firstSeen: number;
+        lastSeen: number;
+        occurrences: Array<{
+            workflowSlug: string;
+            runId: string;
+            stepId: string;
+            attemptNumber: number;
+            timestampUs: number;
+        }>;
+        total: number;
+    }>;
+    /**
+     * Get retry analysis metrics
+     *
+     * Analyzes retry patterns, success rates after retries, and retry effectiveness.
+     *
+     * @param options - Optional filters for time range, workflow, or step
+     * @returns Retry analysis data
+     */
+    abstract getRetryAnalysis(options?: AnalyticsOptions): Promise<RetryAnalysis>;
+    /**
+     * Get scheduling latency metrics
+     *
+     * Measures time between step being scheduled and actually starting execution.
+     * High latency indicates worker starvation or queue congestion.
+     *
+     * @param options - Optional filters for time range, workflow, or step
+     * @returns Scheduling latency statistics
+     */
+    abstract getSchedulingLatency(options?: AnalyticsOptions): Promise<SchedulingLatency>;
+    /**
+     * Get step duration metrics
+     *
+     * Analyzes how long steps take to execute.
+     *
+     * @param options - Optional filters for time range, workflow, or step
+     * @returns Step duration statistics
+     */
+    abstract getStepDuration(options?: AnalyticsOptions): Promise<StepDuration>;
+    /**
+     * Get workflow duration metrics
+     *
+     * Analyzes end-to-end workflow execution time (from submission to completion).
+     *
+     * @param options - Optional filters for time range or workflow
+     * @returns Workflow duration statistics
+     */
+    abstract getWorkflowDuration(options?: AnalyticsOptions): Promise<WorkflowDuration>;
+    /**
+     * Get worker stability metrics
+     *
+     * Analyzes worker crashes, reclamations, and stale heartbeats.
+     *
+     * @param options - Optional filters for time range
+     * @returns Worker stability data
+     */
+    abstract getWorkerStability(options?: AnalyticsOptions): Promise<WorkerStability>;
+    /**
+     * Get throughput metrics
+     *
+     * Analyzes how many runs/steps are being completed per unit time.
+     *
+     * @param options - Optional filters for time range or workflow
+     * @returns Throughput data
+     */
+    abstract getThroughput(options?: AnalyticsOptions): Promise<Throughput>;
+    /**
+     * Get current queue depth
+     *
+     * Real-time snapshot of pending/running runs and steps.
+     *
+     * @param options - Optional filter for workflow
+     * @returns Queue depth data
+     */
+    abstract getQueueDepth(options?: Pick<AnalyticsOptions, 'workflowSlug'>): Promise<QueueDepth>;
+    /**
+     * Get queue depth broken down by workflow
+     *
+     * Real-time snapshot showing per-workflow queue statistics.
+     * Useful for identifying which workflows have pending work.
+     *
+     * @returns Array of per-workflow queue depth data
+     */
+    abstract getQueueDepthByWorkflow(): Promise<QueueDepthByWorkflow>;
+    /**
+     * Get success/failure rate metrics
+     *
+     * Analyzes overall health of workflows and steps.
+     *
+     * @param options - Optional filters for time range, workflow, or step
+     * @returns Success rate data
+     */
+    abstract getSuccessRate(options?: AnalyticsOptions): Promise<SuccessRate>;
+    /**
+     * Get comprehensive analytics summary
+     *
+     * Combines all analytics metrics into a single response.
+     * Useful for dashboard views.
+     *
+     * @param options - Optional filters for time range or workflow
+     * @returns Complete analytics summary
+     */
+    abstract getAnalyticsSummary(options?: AnalyticsOptions): Promise<AnalyticsSummary>;
+}
+//# sourceMappingURL=interface.d.ts.map