@classytic/streamline 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1589 @@
+import { _ as WorkflowHandlers, a as SchedulingInfo, c as StepError, d as StepState, f as StepStatus, g as WorkflowEventPayload, h as WorkflowDefinition, i as RunStatus, l as StepHandler, m as WaitingFor, n as InferHandlersContext, o as Step, p as TypedHandlers, r as RecurrencePattern, s as StepContext, t as InferContext, u as StepIds, v as WorkflowRun } from "./types-DG85_LzF.mjs";
+import { n as WorkflowEventName, r as globalEventBus, t as WorkflowEventBus } from "./events-C0sZINZq.mjs";
+import { FilterQuery, Plugin, Repository } from "@classytic/mongokit";
+import mongoose from "mongoose";
+
+//#region src/plugins/tenant-filter.plugin.d.ts
+/**
+ * Tenant filter plugin options
+ */
+interface TenantFilterOptions {
+  /**
+   * Field path for tenant ID in documents
+   * Supports nested fields using dot notation
+   *
+   * @example 'context.tenantId' → filters { 'context.tenantId': 'tenant-123' }
+   * @example 'meta.orgId' → filters { 'meta.orgId': 'org-456' }
+   * @default 'context.tenantId'
+   */
+  tenantField?: string;
+  /**
+   * Static tenant ID for single-tenant deployments
+   * If set, all queries use this tenant ID (no need to pass tenantId param)
+   *
+   * @default undefined (multi-tenant mode - tenantId required per query)
+   */
+  staticTenantId?: string;
+  /**
+   * Strict mode - throws error if tenantId is missing and not bypassed
+   * If false, missing tenantId is silently ignored (not recommended for production)
+   *
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * Enable bypass capability - allows queries to bypass tenant filter
+   * If false, ALL queries must include tenant filter (maximum security)
+   *
+   * @default true (allows bypassTenant: true for admin operations)
+   */
+  allowBypass?: boolean;
+}
+/**
+ * Tenant filter plugin factory
+ *
+ * Creates a plugin that automatically injects tenant filters into all queries.
+ * Prevents cross-tenant data leaks by enforcing tenant isolation at repository level.
+ *
+ * @param options - Plugin configuration options
+ * @returns MongoKit plugin instance
+ *
+ * @example Multi-Tenant with Strict Mode
+ * ```typescript
+ * const plugin = tenantFilterPlugin({
+ *   tenantField: 'context.tenantId',
+ *   strict: true,
+ *   allowBypass: false // No bypasses allowed
+ * });
+ * ```
+ *
+ * @example Single-Tenant with Static ID
+ * ```typescript
+ * const plugin = tenantFilterPlugin({
+ *   tenantField: 'context.tenantId',
+ *   staticTenantId: process.env.ORGANIZATION_ID
+ * });
+ * ```
+ */
+declare function tenantFilterPlugin(options?: TenantFilterOptions): Plugin;
+/**
+ * Helper to create single-tenant repository (syntactic sugar)
+ *
+ * @param tenantId - Static tenant ID for all operations
+ * @param tenantField - Field path for tenant ID (default: 'context.tenantId')
+ * @returns Plugin configuration for single-tenant mode
+ *
+ * @example
+ * ```typescript
+ * import { singleTenantPlugin } from './plugins/tenant-filter.plugin';
+ *
+ * const repo = new Repository(Model, [
+ *   singleTenantPlugin('my-organization-id')
+ * ]);
+ * ```
+ */
+declare function singleTenantPlugin(tenantId: string, tenantField?: string): Plugin;
+//#endregion
+//#region src/storage/run.repository.d.ts
+type LeanWorkflowRun<TContext = unknown> = WorkflowRun<TContext>;
+interface AtomicUpdateOptions {
+  tenantId?: string;
+  bypassTenant?: boolean;
+}
+interface PaginatedResult<T> {
+  docs: T[];
+  page?: number;
+  limit?: number;
+  total?: number;
+  hasMore?: boolean;
+  next?: string;
+}
+interface WorkflowRepositoryConfig {
+  multiTenant?: TenantFilterOptions;
+}
+/**
+ * Repository interface for workflow run storage operations.
+ * Provides CRUD, queries, and atomic updates for workflow runs.
+ */
+interface WorkflowRunRepository {
+  /** Create a new workflow run */
+  create<TContext = unknown>(run: WorkflowRun<TContext>): Promise<WorkflowRun<TContext>>;
+  /** Get a workflow run by ID */
+  getById<TContext = unknown>(id: string): Promise<WorkflowRun<TContext> | null>;
+  /** Get all workflow runs with filtering and pagination */
+  getAll: Repository<WorkflowRun>['getAll'];
+  /** Update a workflow run */
+  update<TContext = unknown>(id: string, data: Partial<WorkflowRun<TContext>>, options?: AtomicUpdateOptions): Promise<WorkflowRun<TContext>>;
+  /** Delete a workflow run */
+  delete: Repository<WorkflowRun>['delete'];
+  /** Atomic update with filter (for concurrent workflow claiming) */
+  updateOne(filter: Record<string, unknown>, update: Record<string, unknown>, options?: AtomicUpdateOptions): Promise<{
+    modifiedCount: number;
+  }>;
+  /** Get all active (running/waiting) workflow runs */
+  getActiveRuns(): Promise<LeanWorkflowRun[]>;
+  /** Get workflow runs by workflow ID */
+  getRunsByWorkflow(workflowId: string, limit?: number): Promise<LeanWorkflowRun[]>;
+  /** Get all waiting workflow runs */
+  getWaitingRuns(): Promise<LeanWorkflowRun[]>;
+  /** Get all running workflow runs */
+  getRunningRuns(): Promise<LeanWorkflowRun[]>;
+  /** Get workflows ready to resume (resumeAt <= now) */
+  getReadyToResume(now: Date, limit?: number): Promise<LeanWorkflowRun[]>;
+  /** Get workflows ready for retry (retryAt <= now) */
+  getReadyForRetry(now: Date, limit?: number): Promise<LeanWorkflowRun[]>;
+  /** Get stale running workflows (no heartbeat in threshold) */
+  getStaleRunningWorkflows(staleThresholdMs: number, limit?: number): Promise<LeanWorkflowRun[]>;
+  /** Get scheduled workflows ready to execute */
+  getScheduledWorkflowsReadyToExecute(now: Date, options?: {
+    page?: number;
+    limit?: number;
+    cursor?: string | null;
+    tenantId?: string;
+  }): Promise<PaginatedResult<LeanWorkflowRun>>;
+  /** Access to underlying MongoKit repository */
+  readonly base: Repository<WorkflowRun>;
+  /** Access to repository hooks */
+  readonly _hooks: Map<string, unknown[]>;
+}
+/**
+ * Create a workflow repository instance.
+ *
+ * @example
+ * // Single-tenant:
+ * const repo = createWorkflowRepository();
+ *
+ * // Multi-tenant:
+ * const repo = createWorkflowRepository({
+ *   multiTenant: { tenantField: 'context.tenantId', strict: true }
+ * });
+ */
+declare function createWorkflowRepository(config?: WorkflowRepositoryConfig): WorkflowRunRepository;
+declare const workflowRunRepository: WorkflowRunRepository;
+//#endregion
+//#region src/execution/smart-scheduler.d.ts
+interface SchedulerStats {
+  totalPolls: number;
+  successfulPolls: number;
+  failedPolls: number;
+  lastPollAt?: Date;
+  avgPollDuration: number;
+  activeWorkflows: number;
+  resumedWorkflows: number;
+  missedResumes: number;
+  isPolling: boolean;
+  pollInterval: number;
+  uptime: number;
+}
+declare class SchedulerMetrics {
+  private stats;
+  private pollDurations;
+  private startTime?;
+  private readonly maxDurationsToTrack;
+  start(pollInterval: number): void;
+  stop(): void;
+  recordPoll(duration: number, success: boolean, workflowsFound: number): void;
+  recordResume(success: boolean): void;
+  getStats(): SchedulerStats;
+  isHealthy(): boolean;
+}
+interface SmartSchedulerConfig {
+  /** Base poll interval (when active) */
+  basePollInterval: number;
+  /** Max poll interval (when load is low) */
+  maxPollInterval: number;
+  /** Min poll interval (when load is high) */
+  minPollInterval: number;
+  /** Max workflows to process per poll cycle (for efficiency at scale) */
+  maxWorkflowsPerPoll: number;
+  /** How long to wait before stopping (no workflows) */
+  idleTimeout: number;
+  /** Circuit breaker: max consecutive failures */
+  maxConsecutiveFailures: number;
+  /** Enable adaptive polling */
+  adaptivePolling: boolean;
+  /** Stale workflow check interval (runs even when scheduler is idle) */
+  staleCheckInterval: number;
+  /** Threshold for stale workflow detection */
+  staleThreshold: number;
+}
+declare class SmartScheduler {
+  private repository;
+  private resumeCallback;
+  private config;
+  private eventBus?;
+  private timers;
+  private pollInterval?;
+  private idleTimer?;
+  private staleCheckTimer?;
+  private isPolling;
+  private isStaleCheckActive;
+  private currentInterval;
+  private consecutiveFailures;
+  private lastWorkflowCount;
+  private metrics;
+  private staleRecoveryCallback?;
+  private retryCallback?;
+  constructor(repository: WorkflowRunRepository, resumeCallback: (runId: string) => Promise<void>, config?: SmartSchedulerConfig, eventBus?: WorkflowEventBus | undefined);
+  private emitError;
+  /**
+   * Set callback for recovering stale 'running' workflows
+   * Separate from resume because stale recovery requires different atomic claim logic
+   */
+  setStaleRecoveryCallback(callback: (runId: string, thresholdMs: number) => Promise<unknown>): void;
+  /**
+   * Set callback for retrying failed steps
+   * Separate from resume because retries need execute() (re-run step), not resumeStep() (mark done with payload)
+   */
+  setRetryCallback(callback: (runId: string) => Promise<unknown>): void;
+  /**
+   * Intelligent start: Only starts if workflows exist
+   * Checks for both waiting workflows AND running workflows that might need stale recovery
+   */
+  startIfNeeded(): Promise<boolean>;
+  /**
+   * Force start polling immediately
+   */
+  start(): void;
+  /**
+   * Stop polling
+   */
+  stop(): void;
+  /**
+   * Schedule a workflow to resume at specific time
+   * Handles both short delays (setTimeout) and long delays (MongoDB polling)
+   */
+  scheduleResume(runId: string, resumeAt: Date): void;
+  /**
+   * Cancel scheduled resume
+   */
+  cancelSchedule(runId: string): void;
+  /**
+   * Get scheduler statistics
+   */
+  getStats(): ReturnType<SchedulerMetrics['getStats']>;
+  /**
+   * Health check
+   */
+  isHealthy(): boolean;
+  /**
+   * Get current polling interval
+   */
+  getCurrentInterval(): number;
+  private startPolling;
+  private stopPolling;
+  /**
+   * Start background stale workflow check
+   * Runs independently of main polling loop to ensure crashed workflows are always recovered
+   */
+  private startStaleCheck;
+  /**
+   * Stop background stale workflow check
+   * Guarantees no further checks will be scheduled, even if one is currently running
+   */
+  private stopStaleCheck;
+  /**
+   * Background check for stale workflows (runs even when scheduler is idle)
+   * If stale workflows found, start the main polling loop
+   */
+  private checkForStaleWorkflows;
+  private schedulePoll;
+  private poll;
+  private resumeWorkflow;
+  private hasWaitingWorkflows;
+  /**
+   * Check if there are any active workflows that need scheduler attention
+   * Checks for waiting workflows (resume/retry), scheduled workflows, OR stale running workflows
+   * Note: Healthy running workflows don't need the scheduler
+   */
+  private hasActiveWorkflows;
+  private adjustInterval;
+  private resetIdleTimer;
+}
+//#endregion
+//#region src/storage/cache.d.ts
+/** Cache health status for monitoring and alerting */
+type CacheHealthStatus = 'healthy' | 'warning' | 'critical';
+/**
+ * O(1) LRU cache using Map's insertion-order iteration
+ *
+ * Map maintains insertion order, so we use delete+set to move items to the end.
+ * - set/get/delete: O(1)
+ * - eviction: O(1) - just delete first key
+ * - Only caches active workflows (running/waiting)
+ */
+declare class WorkflowCache {
+  private readonly maxSize;
+  private cache;
+  constructor(maxSize?: number);
+  set<TContext>(run: WorkflowRun<TContext>): void;
+  get<TContext = unknown>(runId: string): WorkflowRun<TContext> | null;
+  delete(runId: string): void;
+  clear(): void;
+  getActive<TContext = unknown>(): WorkflowRun<TContext>[];
+  size(): number;
+  getStats(): {
+    size: number;
+    maxSize: number;
+    utilizationPercent: number;
+  };
+  /**
+   * Check if cache is approaching capacity.
+   * Useful for monitoring and proactive scaling.
+   *
+   * @param threshold - Utilization ratio (0-1), default 0.8 (80%)
+   */
+  isNearCapacity(threshold?: number): boolean;
+  /**
+   * Get cache health status for monitoring dashboards.
+   * Returns status and human-readable message.
+   */
+  getHealth(): {
+    status: CacheHealthStatus;
+    message: string;
+    utilizationPercent: number;
+  };
+  private isActive;
+}
+//#endregion
+//#region src/core/container.d.ts
+/**
+ * Container holding all shared dependencies for a workflow engine instance.
+ *
+ * @example
+ * ```typescript
+ * // Use default container (creates new instances)
+ * const container = createContainer();
+ *
+ * // Use in workflow
+ * const workflow = createWorkflow('my-workflow', {
+ *   steps: { ... },
+ *   container
+ * });
+ * ```
+ */
+interface StreamlineContainer {
+  /** MongoDB repository for workflow runs */
+  repository: WorkflowRunRepository;
+  /** Event bus for workflow lifecycle events */
+  eventBus: WorkflowEventBus;
+  /** In-memory cache for active workflows */
+  cache: WorkflowCache;
+}
+/**
+ * Options for creating a container
+ */
+interface ContainerOptions {
+  /**
+   * Custom repository instance or configuration
+   * - If WorkflowRunRepository: uses the provided instance
+   * - If WorkflowRepositoryConfig: creates a new repository with the config
+   * - If undefined: uses the default singleton repository
+   */
+  repository?: WorkflowRunRepository | WorkflowRepositoryConfig;
+  /**
+   * Custom event bus instance
+   * - If WorkflowEventBus: uses the provided instance
+   * - If 'global': uses the globalEventBus (for telemetry integration)
+   * - If undefined: creates a new isolated event bus
+   */
+  eventBus?: WorkflowEventBus | 'global';
+  /**
+   * Custom cache instance
+   * If undefined: creates a new isolated cache
+   */
+  cache?: WorkflowCache;
+}
+/**
+ * Create a new container with configurable dependencies.
+ *
+ * @param options - Optional configuration for container dependencies
+ * @returns A container with the specified or default dependencies
+ *
+ * @example Default container (isolated instances)
+ * ```typescript
+ * const container = createContainer();
+ * ```
+ *
+ * @example Multi-tenant container
+ * ```typescript
+ * const container = createContainer({
+ *   repository: { multiTenant: { tenantField: 'meta.tenantId', strict: true } }
+ * });
+ * ```
+ *
+ * @example Container with global event bus (for telemetry)
+ * ```typescript
+ * const container = createContainer({ eventBus: 'global' });
+ * ```
+ *
+ * @example Fully custom container
+ * ```typescript
+ * const container = createContainer({
+ *   repository: myCustomRepo,
+ *   eventBus: myCustomEventBus,
+ *   cache: myCustomCache
+ * });
+ * ```
+ */
+declare function createContainer(options?: ContainerOptions): StreamlineContainer;
+/**
+ * Type guard to check if an object is a valid StreamlineContainer
+ */
+declare function isStreamlineContainer(obj: unknown): obj is StreamlineContainer;
+//#endregion
+//#region src/execution/engine.d.ts
+/**
+ * Registry mapping runId to the engine managing that run.
+ * Enables resumeHook() to find the correct engine for resuming.
+ */
+declare class HookRegistry {
+  private engines;
+  private cleanupInterval;
+  register(runId: string, engine: WorkflowEngine<unknown>): void;
+  unregister(runId: string): void;
+  getEngine(runId: string): WorkflowEngine<unknown> | undefined;
+  private cleanup;
+  shutdown(): void;
+}
+/** Global hook registry instance */
+declare const hookRegistry: HookRegistry;
+interface WorkflowEngineOptions {
+  /** Auto-execute workflow after start (default: true) */
+  autoExecute?: boolean;
+  /** Custom scheduler configuration */
+  scheduler?: Partial<SmartSchedulerConfig>;
+}
+/**
+ * Core workflow execution engine.
+ *
+ * Manages workflow lifecycle: start, execute, pause, resume, cancel.
+ * Handles waiting states, retries, and crash recovery automatically.
+ *
+ * @typeParam TContext - Type of workflow context
+ *
+ * @example
+ * ```typescript
+ * const engine = new WorkflowEngine(definition, handlers, container);
+ * const run = await engine.start({ orderId: '123' });
+ * ```
+ */
+declare class WorkflowEngine<TContext = Record<string, unknown>> {
+  readonly handlers: WorkflowHandlers<TContext>;
+  private executor;
+  private scheduler;
+  private registry;
+  private options;
+  private eventListeners;
+  /** Exposed for hook registry and external access */
+  readonly container: StreamlineContainer;
+  constructor(definition: WorkflowDefinition<TContext>, handlers: WorkflowHandlers<TContext>, container: StreamlineContainer, options?: WorkflowEngineOptions);
+  /** Get the workflow definition */
+  get definition(): WorkflowDefinition<TContext>;
+  /**
+   * Start a new workflow run.
+   *
+   * @param input - Input data for the workflow
+   * @param meta - Optional metadata (userId, tags, etc.)
+   * @returns The created workflow run
+   */
+  start(input: unknown, meta?: Record<string, unknown>): Promise<WorkflowRun<TContext>>;
+  /**
+   * Get a workflow run by ID.
+   * Returns from cache if available, otherwise fetches from database.
+   *
+   * @param runId - Workflow run ID
+   * @returns The workflow run or null if not found
+   */
+  get(runId: string): Promise<WorkflowRun<TContext> | null>;
+  /**
+   * Execute a workflow run to completion.
+   *
+   * Runs steps sequentially until:
+   * - All steps complete (status: 'done')
+   * - A step fails after retries (status: 'failed')
+   * - A step waits for external input (status: 'waiting')
+   * - The workflow is cancelled (status: 'cancelled')
+   *
+   * @param runId - Workflow run ID to execute
+   * @returns The updated workflow run
+   */
+  execute(runId: string): Promise<WorkflowRun<TContext>>;
+  private getOrThrow;
+  private shouldContinueExecution;
+  private executeNextStep;
+  private checkNoProgress;
+  /**
+   * Handle different waiting states (event, retry, timer, human input)
+   * @returns true if execution should continue, false to break
+   */
+  private handleWaitingState;
+  private findCurrentStep;
+  /**
+   * Handle data corruption scenario (missing step state)
+   */
+  private failCorruption;
+  /**
+   * Register event listener for event-based waits
+   * IMPORTANT: Paused workflows will NOT be resumed by events until explicitly resumed by user
+   */
+  private handleEventWait;
+  /**
+   * Handle retry backoff wait with inline execution for short delays
+   * @returns true if workflow should continue execution immediately
+   */
+  private handleRetryWait;
+  /**
+   * Handle timer-based wait (sleep) with inline execution for short delays
+   * @returns true if workflow should continue execution immediately
+   */
+  private handleTimerWait;
+  /**
+   * Resume a paused or waiting workflow.
+   *
+   * For waiting workflows:
+   * - If waiting for human input: payload is passed as the step output
+   * - If waiting for timer/retry: continues execution from current step
+   *
+   * @param runId - Workflow run ID to resume
+   * @param payload - Data to pass to the waiting step (becomes step output)
+   * @returns The updated workflow run
+   * @throws {InvalidStateError} If workflow is not in waiting/running state
+   */
+  resume(runId: string, payload?: unknown): Promise<WorkflowRun<TContext>>;
+  private resumeWaitingWorkflow;
+  /**
+   * Recover a stale 'running' workflow (crashed mid-execution)
+   * Uses atomic claim to prevent multiple servers from recovering the same workflow
+   */
+  recoverStale(runId: string, staleThresholdMs: number): Promise<WorkflowRun<TContext> | null>;
+  /**
+   * Execute a retry for a workflow that failed and is waiting for backoff timer
+   * Uses atomic claim to prevent multiple servers from retrying the same workflow
+   */
+  executeRetry(runId: string): Promise<WorkflowRun<TContext> | null>;
+  /**
+   * Rewind a workflow to a previous step.
+   * Resets all steps from target step onwards to pending state.
+   *
+   * @param runId - Workflow run ID
+   * @param stepId - Step ID to rewind to
+   * @returns The rewound workflow run
+   */
+  rewindTo(runId: string, stepId: string): Promise<WorkflowRun<TContext>>;
+  /**
+   * Cancel a running workflow.
+   * Cleans up all resources and marks workflow as cancelled.
+   *
+   * @param runId - Workflow run ID to cancel
+   * @returns The cancelled workflow run
+   */
+  cancel(runId: string): Promise<WorkflowRun<TContext>>;
+  /**
+   * Pause a workflow run.
+   *
+   * Sets the `paused` flag to prevent the scheduler from processing this workflow.
+   * Paused workflows can be resumed later with `resume()`.
+   *
+   * @param runId - Workflow run ID to pause
+   * @returns The paused workflow run
+   */
+  pause(runId: string): Promise<WorkflowRun<TContext>>;
+  /**
+   * Configure engine options (scheduler settings, etc.)
+   */
+  configure(options: {
+    scheduler?: Partial<SmartSchedulerConfig>;
+  }): void;
+  shutdown(): void;
+  /**
+   * Get scheduler statistics for monitoring
+   */
+  getSchedulerStats(): ReturnType<SmartScheduler['getStats']>;
+  /**
+   * Check if scheduler is healthy
+   */
+  isSchedulerHealthy(): boolean;
+}
+//#endregion
+//#region src/workflow/define.d.ts
+interface WorkflowConfig<TContext, TInput = unknown> {
+  steps: Record<string, StepHandler<unknown, TContext>>;
+  context?: (input: TInput) => TContext;
+  version?: string;
+  defaults?: {
+    retries?: number;
+    timeout?: number;
+  };
+  autoExecute?: boolean;
+  /** Optional custom container for dependency injection */
+  container?: StreamlineContainer;
+}
+/** Options for waitFor method */
+interface WaitForOptions {
+  /** Poll interval in ms (default: 1000) */
+  pollInterval?: number;
+  /** Maximum time to wait in ms (default: no timeout) */
+  timeout?: number;
+}
+interface Workflow<TContext, TInput = unknown> {
+  start: (input: TInput, meta?: Record<string, unknown>) => Promise<WorkflowRun<TContext>>;
+  get: (runId: string) => Promise<WorkflowRun<TContext> | null>;
+  execute: (runId: string) => Promise<WorkflowRun<TContext>>;
+  resume: (runId: string, payload?: unknown) => Promise<WorkflowRun<TContext>>;
+  cancel: (runId: string) => Promise<WorkflowRun<TContext>>;
+  pause: (runId: string) => Promise<WorkflowRun<TContext>>;
+  rewindTo: (runId: string, stepId: string) => Promise<WorkflowRun<TContext>>;
+  /**
+   * Wait for a workflow to complete (reach a terminal state).
+   * Polls the workflow status until it's done, failed, or cancelled.
+   *
+   * @param runId - Workflow run ID to wait for
+   * @param options - Poll interval and timeout settings
+   * @returns The completed workflow run
+   * @throws {Error} If timeout is exceeded or workflow not found
+   *
+   * @example
+   * ```typescript
+   * const run = await workflow.start({ data: 'test' });
+   * const completed = await workflow.waitFor(run._id);
+   * console.log(completed.status); // 'done' | 'failed' | 'cancelled'
+   * ```
+   */
+  waitFor: (runId: string, options?: WaitForOptions) => Promise<WorkflowRun<TContext>>;
+  shutdown: () => void;
+  definition: WorkflowDefinition<TContext>;
+  engine: WorkflowEngine<TContext>;
+  /** The container used by this workflow (for testing or custom integrations) */
+  container: StreamlineContainer;
+}
+/**
+ * Create a workflow with inline step handlers
+ *
+ * @example
+ * ```typescript
+ * const orderProcess = createWorkflow('order-process', {
+ *   steps: {
+ *     validate: async (ctx) => validateOrder(ctx.input),
+ *     charge: async (ctx) => chargeCard(ctx.getOutput('validate')),
+ *     fulfill: async (ctx) => shipOrder(ctx.getOutput('charge')),
+ *     notify: async (ctx) => sendConfirmation(ctx.context.email),
+ *   },
+ *   context: (input) => ({ orderId: input.id, email: input.email }),
+ * });
+ *
+ * await orderProcess.start({ id: '123', email: 'user@example.com' });
+ * ```
+ *
+ * @example Custom container for testing
+ * ```typescript
+ * const container = createContainer();
+ * const workflow = createWorkflow('test-workflow', {
+ *   steps: { ... },
+ *   container
+ * });
+ * ```
+ */
+declare function createWorkflow<TContext = Record<string, unknown>, TInput = unknown>(id: string, config: WorkflowConfig<TContext, TInput>): Workflow<TContext, TInput>;
+//#endregion
+//#region src/core/status.d.ts
+declare const STEP_STATUS_VALUES: StepStatus[];
+declare const RUN_STATUS_VALUES: RunStatus[];
+declare function isStepStatus(value: unknown): value is StepStatus;
+declare function isRunStatus(value: unknown): value is RunStatus;
+declare function deriveRunStatus<TContext>(run: WorkflowRun<TContext>): RunStatus;
+declare function isValidStepTransition(from: StepStatus, to: StepStatus): boolean;
+declare function isValidRunTransition(from: RunStatus, to: RunStatus): boolean;
+/**
+ * Check if a workflow status represents a terminal (final) state
+ */
+declare function isTerminalState(status: RunStatus): boolean;
+//#endregion
+//#region src/features/hooks.d.ts
+interface HookOptions {
+  /** Custom token (default: auto-generated with crypto-random suffix) */
+  token?: string;
+}
+interface HookResult {
+  /** Token to use for resuming (includes secure random component) */
+  token: string;
+  /** URL path for webhook (if using webhook manager) */
+  path: string;
+}
+/**
+ * Create a hook that pauses workflow until external input.
+ * The token includes a crypto-random suffix for security.
+ *
+ * IMPORTANT: Pass the returned token to ctx.wait() to enable token validation:
+ * ```typescript
+ * const hook = createHook(ctx, 'approval');
+ * return ctx.wait(hook.token, { hookToken: hook.token }); // Token stored for validation
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In step handler
+ * async function waitForApproval(ctx) {
+ *   const hook = createHook(ctx, 'waiting-for-approval');
+ *   console.log('Resume with token:', hook.token);
+ *   return ctx.wait(hook.token, { hookToken: hook.token }); // Token validated on resume
+ * }
+ *
+ * // From API route
+ * await resumeHook('token-123', { approved: true });
+ * ```
+ */
+declare function createHook(ctx: StepContext, reason: string, options?: HookOptions): HookResult;
+/**
+ * Resume a paused workflow by hook token.
+ *
+ * Security: If the workflow was paused with a hookToken in waitingFor.data,
+ * this function validates the token before resuming.
+ *
+ * Multi-worker support: Falls back to DB lookup if engine not in local registry.
+ *
+ * @example
+ * ```typescript
+ * // API route handler
+ * app.post('/hooks/:token', async (req, res) => {
+ *   const result = await resumeHook(req.params.token, req.body);
+ *   res.json({ success: true, runId: result.runId, status: result.run.status });
+ * });
+ * ```
+ */
+declare function resumeHook(token: string, payload: unknown): Promise<{
+  runId: string;
+  run: WorkflowRun;
+}>;
+/**
+ * Generate a deterministic token for idempotent hooks
+ *
+ * @example
+ * ```typescript
+ * // Slack bot - same channel always gets same token
+ * const token = hookToken('slack', channelId);
+ * const hook = createHook(ctx, 'slack-message', { token });
+ * ```
+ */
+declare function hookToken(...parts: string[]): string;
+//#endregion
+//#region src/execution/context.d.ts
+declare class WaitSignal extends Error {
+  type: 'human' | 'webhook' | 'timer' | 'event';
+  reason: string;
+  data?: unknown | undefined;
+  constructor(type: 'human' | 'webhook' | 'timer' | 'event', reason: string, data?: unknown | undefined);
+}
+//#endregion
+//#region src/storage/run.model.d.ts
+/**
+ * MULTI-TENANCY & SCHEDULED WORKFLOWS - COMPOSITE INDEXES
+ *
+ * For multi-tenant scheduled workflows, add composite indexes with tenantId FIRST.
+ * MongoDB can only use indexes if the query matches the prefix pattern.
+ *
+ * Example: Multi-tenant scheduled workflow polling
+ * ```typescript
+ * import { WorkflowRunModel } from '@classytic/streamline';
+ *
+ * // Add composite index: tenantId first, then scheduling fields
+ * WorkflowRunModel.collection.createIndex({
+ *   'context.tenantId': 1,
+ *   status: 1,
+ *   'scheduling.executionTime': 1,
+ *   paused: 1
+ * });
+ *
+ * // This query will use the index efficiently:
+ * const scheduledWorkflows = await WorkflowRunModel.find({
+ *   'context.tenantId': 'tenant123',
+ *   status: 'draft',
+ *   'scheduling.executionTime': { $lte: new Date() },
+ *   paused: { $ne: true }
+ * }).sort({ 'scheduling.executionTime': 1 }).limit(100);
+ * ```
+ *
+ * Example: List workflows by tenant and time
+ * ```typescript
+ * WorkflowRunModel.collection.createIndex({
+ *   'context.tenantId': 1,
+ *   workflowId: 1,
+ *   createdAt: -1
+ * });
+ * ```
+ *
+ * IMPORTANT: Put tenantId FIRST in all multi-tenant indexes for query efficiency.
+ */
+/**
+ * MULTI-TENANCY & CUSTOM INDEXES
+ *
+ * The engine is unopinionated about multi-tenancy. Add indexes for YOUR needs:
+ *
+ * Option 1: Add tenantId to metadata and index it
+ * ```typescript
+ * import { WorkflowRunModel } from '@classytic/streamline';
+ *
+ * // Add custom index for tenant-scoped queries
+ * WorkflowRunModel.collection.createIndex({ 'meta.tenantId': 1, status: 1 });
+ * WorkflowRunModel.collection.createIndex({ 'meta.orgId': 1, createdAt: -1 });
+ * ```
+ *
+ * Option 2: Extend the schema (before first use)
+ * ```typescript
+ * import { WorkflowRunModel } from '@classytic/streamline';
+ *
+ * WorkflowRunModel.schema.add({
+ *   tenantId: { type: String, index: true }
+ * });
+ * WorkflowRunModel.schema.index({ tenantId: 1, status: 1 });
+ * ```
+ *
+ * Then query: engine.get(runId) and filter by tenantId in your app layer
+ */
+/**
+ * Export WorkflowRunModel with hot-reload safety
+ *
+ * The pattern checks if the model already exists before creating a new one.
+ * This prevents "OverwriteModelError" in development with hot module replacement.
+ */
+declare let WorkflowRunModel: mongoose.Model<WorkflowRun>;
+//#endregion
+//#region src/storage/query-builder.d.ts
+declare const RUN_STATUS: {
+  readonly DRAFT: "draft";
+  readonly RUNNING: "running";
+  readonly WAITING: "waiting";
+  readonly DONE: "done";
+  readonly FAILED: "failed";
+  readonly CANCELLED: "cancelled";
+};
+declare const STEP_STATUS: {
+  readonly PENDING: "pending";
+  readonly RUNNING: "running";
+  readonly WAITING: "waiting";
+  readonly DONE: "done";
+  readonly FAILED: "failed";
+  readonly SKIPPED: "skipped";
+};
+declare class WorkflowQueryBuilder {
+  private query;
+  static create(): WorkflowQueryBuilder;
+  withStatus(status: RunStatus | RunStatus[]): this;
+  notPaused(): this;
+  isPaused(): this;
+  withWorkflowId(workflowId: string): this;
+  withRunId(runId: string): this;
+  withUserId(userId: string): this;
+  withTags(tags: string | string[]): this;
+  withStepReady(stepStatus: StepStatus, field: string, beforeTime: Date): this;
+  withRetryReady(now?: Date): this;
+  withTimerReady(now?: Date): this;
+  withStaleHeartbeat(thresholdMs: number): this;
+  withScheduledBefore(time: Date): this;
+  withScheduledAfter(time: Date): this;
+  createdBefore(date: Date): this;
+  createdAfter(date: Date): this;
+  where(conditions: Record<string, unknown>): this;
+  build(): FilterQuery;
+}
+declare const CommonQueries: {
+  active: () => FilterQuery;
+  readyForRetry: (now?: Date) => FilterQuery;
+  readyToResume: (now?: Date) => FilterQuery;
+  staleRunning: (thresholdMs: number) => FilterQuery;
+  scheduledReady: (now?: Date) => FilterQuery;
+  byUser: (userId: string, status?: RunStatus | RunStatus[]) => FilterQuery;
+  failed: () => FilterQuery;
+  completed: () => FilterQuery;
+};
+//#endregion
+//#region src/storage/definition.model.d.ts
+interface WorkflowDefinitionDoc {
+  _id: string;
+  workflowId: string;
+  name: string;
+  description?: string;
+  version: string;
+  versionMajor: number;
+  versionMinor: number;
+  versionPatch: number;
+  steps: Array<{
+    id: string;
+    name: string;
+    retries?: number;
+    timeout?: number;
+    condition?: string;
+  }>;
+  defaults?: {
+    retries?: number;
+    timeout?: number;
+  };
+  createdBy?: string;
+  updatedBy?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  isActive: boolean;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+/**
+ * MULTI-TENANCY & CUSTOM INDEXES
+ *
+ * This model is intentionally unopinionated about multi-tenancy.
+ * Different apps have different needs (tenantId, orgId, workspaceId, etc.)
+ *
+ * To add custom indexes for your app:
+ *
+ * import { WorkflowDefinitionModel } from '@classytic/streamline';
+ *
+ * // Add your custom indexes
+ * WorkflowDefinitionModel.collection.createIndex({ tenantId: 1, isActive: 1 });
+ * WorkflowDefinitionModel.collection.createIndex({ orgId: 1, createdAt: -1 });
+ *
+ * OR extend the schema:
+ *
+ * import { WorkflowDefinitionModel } from '@classytic/streamline';
+ * WorkflowDefinitionModel.schema.add({ tenantId: String });
+ * WorkflowDefinitionModel.schema.index({ tenantId: 1, isActive: 1 });
+ */
+/**
+ * Export WorkflowDefinitionModel with hot-reload safety
+ *
+ * The pattern checks if the model already exists before creating a new one.
+ * This prevents "OverwriteModelError" in development with hot module replacement.
+ */
+declare let WorkflowDefinitionModel: mongoose.Model<WorkflowDefinitionDoc>;
+/**
+ * Repository for WorkflowDefinition
+ * Optional: Use if you want to store workflows in MongoDB
+ */
+declare const workflowDefinitionRepository: {
+  /**
+   * Create a new workflow definition (or version)
+   */
+  create(definition: Partial<WorkflowDefinitionDoc>): Promise<WorkflowDefinitionDoc>;
+  /**
+   * Get latest active version of a workflow
+   */
+  getLatestVersion(workflowId: string): Promise<WorkflowDefinitionDoc | null>;
+  /**
+   * Get specific version of a workflow
+   */
+  getByVersion(workflowId: string, version: string): Promise<WorkflowDefinitionDoc | null>;
+  /**
+   * Get all active workflow definitions (latest versions only)
+   */
+  getActiveDefinitions(): Promise<WorkflowDefinitionDoc[]>;
+  /**
+   * Get all versions of a specific workflow
+   */
+  getVersionHistory(workflowId: string): Promise<WorkflowDefinitionDoc[]>;
+  /**
+   * Update a specific workflow version (rare - usually create new version)
+   */
+  update(workflowId: string, version: string, updates: Partial<WorkflowDefinitionDoc>): Promise<WorkflowDefinitionDoc | null>;
+  /**
+   * Deactivate a specific version (or all versions if version not provided)
+   */
+  deactivate(workflowId: string, version?: string): Promise<void>;
+  /**
+   * Deactivate all old versions (keep only latest)
+   */
+  deactivateOldVersions(workflowId: string, keepVersion: string): Promise<void>;
+};
+//#endregion
+//#region src/utils/visualization.d.ts
+interface StepTimeline {
+  id: string;
+  status: StepState['status'];
+  duration: number | null;
+  startedAt?: Date;
+  endedAt?: Date;
+}
+interface WorkflowProgress {
+  completed: number;
+  total: number;
+  percentage: number;
+}
+interface StepUIState extends StepState {
+  isCurrentStep: boolean;
+  isPastStep: boolean;
+  isFutureStep: boolean;
+  canRewindTo: boolean;
+}
+declare function getStepTimeline(run: WorkflowRun): StepTimeline[];
+declare function getWorkflowProgress(run: WorkflowRun): WorkflowProgress;
+declare function getStepUIStates(run: WorkflowRun): StepUIState[];
+declare function getWaitingInfo(run: WorkflowRun): {
+  stepId: string;
+  type: "human" | "webhook" | "timer" | "event";
+  reason: string;
+  resumeAt: Date | undefined;
+  eventName: string | undefined;
+  data: unknown;
+} | null;
+declare function canRewindTo(run: WorkflowRun, stepId: string): boolean;
+declare function getExecutionPath(run: WorkflowRun): string[];
+//#endregion
+//#region src/config/constants.d.ts
+/**
+ * Computed values derived from base constants.
+ * Useful for monitoring, alerting, and capacity planning.
+ */
+declare const COMPUTED: {
+  /** Cache utilization threshold for warnings (80% of max) */readonly CACHE_WARNING_THRESHOLD: number; /** Cache utilization threshold for critical alerts (95% of max) */
+  readonly CACHE_CRITICAL_THRESHOLD: number; /** JavaScript setTimeout max safe delay (2^31-1 ms = ~24.8 days) */
+  readonly MAX_TIMEOUT_SAFE_MS: 2147483647; /** Retry delay sequence preview (for documentation/debugging) */
+  readonly RETRY_DELAY_SEQUENCE_MS: number[];
+};
+//#endregion
+//#region src/scheduling/scheduling.service.d.ts
+/**
+ * Paginated result type for scheduled workflows
+ */
+interface ScheduledWorkflowsResult<TContext = unknown> {
+  docs: WorkflowRun<TContext>[];
+  page?: number;
+  limit?: number;
+  total?: number;
+  hasMore?: boolean;
+  next?: string;
+}
+/**
+ * Options for scheduling a workflow
+ */
+interface ScheduleWorkflowOptions {
+  /**
+   * Local date/time to execute (in user's timezone, NOT UTC)
+   *
+   * Format: ISO string without timezone - "YYYY-MM-DDTHH:mm:ss"
+   *
+   * @example
+   * ```typescript
+   * scheduledFor: '2024-03-10T09:00:00' // 9:00 AM local time
+   * ```
+   *
+   * This represents the LOCAL time in the target timezone.
+   * The timezone parameter determines which timezone this represents.
+   * Accepts both string and Date (Date will be converted to ISO string using local components).
+   */
+  scheduledFor: string | Date;
+  /** IANA timezone name (e.g., "America/New_York", "Europe/London") */
+  timezone: string;
+  /** Input data for workflow execution */
+  input: unknown;
+  /** Optional recurrence pattern for repeating workflows */
+  recurrence?: RecurrencePattern;
+  /** Tenant ID for multi-tenant deployments */
+  tenantId?: string;
+  /** User ID who scheduled the workflow */
+  userId?: string;
+  /** Tags for categorization/filtering */
+  tags?: string[];
+  /** Additional metadata */
+  meta?: Record<string, unknown>;
+}
+/**
+ * Options for querying scheduled workflows
+ */
+interface GetScheduledWorkflowsOptions {
+  /** Page number for offset pagination */
+  page?: number;
+  /** Number of results per page */
+  limit?: number;
+  /** Cursor for keyset pagination (more efficient at scale) */
+  cursor?: string | null;
+  /** Filter by tenant ID */
+  tenantId?: string;
+  /** Filter by specific time range */
+  executionTimeRange?: {
+    from: Date;
+    to: Date;
+  };
+  /** Filter by recurrence pattern */
+  recurring?: boolean;
+}
+/**
+ * Scheduling Service configuration
+ */
+interface SchedulingServiceConfig {
+  /** Multi-tenant configuration (optional) - shorthand for container.repository config */
+  multiTenant?: TenantFilterOptions;
+  /** Auto-execute workflows when ready (default: true) */
+  autoExecute?: boolean;
+  /**
+   * Custom container or container options
+   * If provided, multiTenant option is ignored (use container.repository instead)
+   */
+  container?: StreamlineContainer | ContainerOptions;
+}
+/**
+ * SchedulingService - High-level API for timezone-aware workflow scheduling
+ *
+ * Combines WorkflowEngine, TimezoneHandler, and Repository for easy scheduling.
+ * Handles all the complexity of timezone conversion, DST transitions, and scheduling.
+ *
+ * IMPORTANT: Uses a unified container for both scheduling and execution to ensure
+ * consistent multi-tenant isolation and proper hook registration.
+ *
+ * @typeParam TContext - Workflow context type
+ */
+declare class SchedulingService<TContext = Record<string, unknown>> {
+  private readonly engine;
+  private readonly workflow;
+  private readonly timezoneHandler;
+  /** Exposed for testing and advanced use cases */
+  readonly container: StreamlineContainer;
+  constructor(workflow: WorkflowDefinition<TContext>, handlers: WorkflowHandlers<TContext>, config?: SchedulingServiceConfig);
+  /** Get the repository (uses container's repository) */
+  private get repository();
+  /**
+   * Convert Date to ISO string format (YYYY-MM-DDTHH:mm:ss)
+   * Uses local components to preserve the "naive" datetime interpretation
+   */
+  private convertDateToISOString;
+  /**
+   * Schedule a workflow for future execution at a specific timezone
+   *
+   * @param options - Scheduling options with timezone information
+   * @returns Created workflow run with scheduling metadata
+   * @throws {Error} If timezone is invalid or scheduling fails
+   *
+   * @example
+   * ```typescript
+   * const run = await service.schedule({
+   *   scheduledFor: '2024-06-15T14:30:00',
+   *   timezone: 'Europe/London',
+   *   input: { userId: '123', action: 'send-reminder' }
+   * });
+   *
+   * // Check if DST transition affected scheduling
+   * if (run.scheduling?.isDSTTransition) {
+   *   console.warn('DST Note:', run.scheduling.dstNote);
+   * }
+   * ```
+   */
+  schedule(options: ScheduleWorkflowOptions): Promise<WorkflowRun<TContext>>;
+  /**
+   * Reschedule an existing workflow to a new time
+   *
+   * @param runId - Workflow run ID to reschedule
+   * @param newScheduledFor - New local date/time as ISO string (format: "YYYY-MM-DDTHH:mm:ss")
+   * @param newTimezone - Optional new timezone (if changing timezone)
+   * @returns Updated workflow run
+   * @throws {Error} If workflow not found or already executed
+   *
+   * @example Reschedule to different time (same timezone)
+   * ```typescript
+   * await service.reschedule(runId, '2024-06-16T15:00:00');
+   * ```
+   *
+   * @example Reschedule to different time AND timezone
+   * ```typescript
+   * await service.reschedule(
+   *   runId,
+   *   '2024-06-16T10:00:00',
+   *   'America/New_York'
+   * );
+   * ```
+   */
+  reschedule(runId: string, newScheduledFor: string | Date, newTimezone?: string): Promise<WorkflowRun<TContext>>;
+  /**
+   * Cancel a scheduled workflow
+   *
+   * @param runId - Workflow run ID to cancel
+   * @returns Cancelled workflow run
+   * @throws {Error} If workflow not found or already executed
+   *
+   * @example
+   * ```typescript
+   * await service.cancelScheduled(runId);
+   * ```
+   */
+  cancelScheduled(runId: string): Promise<WorkflowRun<TContext>>;
+  /**
+   * Get scheduled workflows (with pagination)
+   *
+   * Supports both offset (page-based) and keyset (cursor-based) pagination.
+   * Use keyset pagination for large datasets (>10k workflows) for better performance.
+   *
+   * @param options - Query and pagination options
+   * @returns Paginated results with scheduled workflows
+   *
+   * @example Offset Pagination (Simple)
+   * ```typescript
+   * const result = await service.getScheduled({
+   *   page: 1,
+   *   limit: 50,
+   *   tenantId: 'client-123'
+   * });
+   *
+   * console.log(result.data); // Array of workflows
+   * console.log(result.hasNextPage); // true if more pages exist
+   * ```
+   *
+   * @example Keyset Pagination (Efficient for large datasets)
+   * ```typescript
+   * // First page
+   * const result = await service.getScheduled({
+   *   cursor: null,
+   *   limit: 1000
+   * });
+   *
+   * // Next page
+   * const nextResult = await service.getScheduled({
+   *   cursor: result.nextCursor,
+   *   limit: 1000
+   * });
+   * ```
+   *
+   * @example Filter by execution time range
+   * ```typescript
+   * const result = await service.getScheduled({
+   *   executionTimeRange: {
+   *     from: new Date('2024-06-01'),
+   *     to: new Date('2024-06-30')
+   *   },
+   *   limit: 100
+   * });
+   * ```
+   */
+  getScheduled(options?: GetScheduledWorkflowsOptions): Promise<ScheduledWorkflowsResult<TContext>>;
+  /**
+   * Get workflow run by ID
+   *
+   * @param runId - Workflow run ID
+   * @returns Workflow run or null if not found
+   */
+  get(runId: string): Promise<WorkflowRun<TContext> | null>;
+  /**
+   * Execute a scheduled workflow immediately (bypass schedule)
+   *
+   * @param runId - Workflow run ID to execute
+   * @returns Executed workflow run
+   * @throws {Error} If workflow not found or not in draft status
+   *
+   * @example
+   * ```typescript
+   * // Execute a scheduled workflow now instead of waiting for execution time
+   * const run = await service.executeNow(runId);
+   * ```
+   */
+  executeNow(runId: string): Promise<WorkflowRun<TContext>>;
+}
+//#endregion
+//#region src/scheduling/timezone-handler.d.ts
+/**
+ * Result of timezone calculation including DST transition metadata
+ */
+interface TimezoneCalculationResult {
+  /** UTC execution time for scheduler to use */
+  executionTime: Date;
+  /** Local time in user's timezone (for display) */
+  localTimeDisplay: string;
+  /** Whether this time falls during a DST transition */
+  isDSTTransition: boolean;
+  /** Human-readable note about DST adjustment (if any) */
+  dstNote?: string;
+}
+/**
+ * TimezoneHandler - Industry-standard timezone conversion with DST edge case handling
+ *
+ * Handles two critical DST edge cases:
+ * 1. Spring Forward (non-existent time): When clocks jump forward, e.g., 2:30 AM doesn't exist
+ * 2. Fall Back (ambiguous time): When clocks fall back, e.g., 1:30 AM occurs twice
+ *
+ * Design Philosophy:
+ * - Store both intent (timezone + local time) AND execution time (UTC)
+ * - Gracefully handle invalid times by adjusting forward
+ * - Warn users about ambiguous times during fall back
+ * - Use IANA timezone database (not abbreviations like "EST")
+ *
+ * @example
+ * ```typescript
+ * const handler = new TimezoneHandler();
+ *
+ * // Schedule for 9:00 AM New York time
+ * const result = handler.calculateExecutionTime(
+ *   '2024-03-10T09:00:00',
+ *   'America/New_York'
+ * );
+ *
+ * console.log(result.executionTime); // UTC time for scheduler
+ * console.log(result.isDSTTransition); // false (9 AM is safe)
+ * ```
+ */
+declare class TimezoneHandler {
+  /**
+   * Calculate UTC execution time from user's local timezone intent
+   *
+   * @param scheduledFor - Local date/time as ISO string WITHOUT timezone (naive datetime)
+   *                       Format: "YYYY-MM-DDTHH:mm:ss" (e.g., "2024-03-10T09:00:00")
+   *
+   *                       This represents the LOCAL time in the target timezone.
+   *                       Do NOT include timezone offset (Z, +00:00, etc.)
+   *
+   * @param timezone - IANA timezone name (e.g., "America/New_York", "Europe/London")
+   * @returns Calculation result with execution time and DST metadata
+   *
+   * @throws {Error} If timezone is invalid or scheduledFor format is invalid
+   *
+   * @example Basic Usage
+   * ```typescript
+   * // Schedule for 9:00 AM New York time
+   * const result = handler.calculateExecutionTime(
+   *   '2024-03-10T09:00:00',
+   *   'America/New_York'
+   * );
+   * console.log(result.executionTime); // UTC Date object for scheduler
+   * console.log(result.localTimeDisplay); // "2024-03-10 09:00:00 EDT"
+   * ```
+   *
+   * @example Spring Forward Edge Case (non-existent time)
+   * ```typescript
+   * const result = handler.calculateExecutionTime(
+   *   '2024-03-10T02:30:00', // 2:30 AM doesn't exist (DST springs forward)
+   *   'America/New_York'
+   * );
+   * // Result: Adjusted to 3:30 AM, isDSTTransition=true, dstNote explains adjustment
+   * ```
+   *
+   * @example Fall Back Edge Case (ambiguous time)
+   * ```typescript
+   * const result = handler.calculateExecutionTime(
+   *   '2024-11-03T01:30:00', // 1:30 AM occurs twice (DST falls back)
+   *   'America/New_York'
+   * );
+   * // Result: Uses first occurrence (DST), isDSTTransition=true, dstNote warns of ambiguity
+   * ```
+   */
+  calculateExecutionTime(scheduledFor: Date | string, timezone: string): TimezoneCalculationResult;
+  /**
+   * Validate if a timezone is recognized by IANA database
+   *
+   * @param timezone - Timezone string to validate
+   * @returns true if valid, false otherwise
+   *
+   * @example
+   * ```typescript
+   * handler.isValidTimezone('America/New_York'); // true
+   * handler.isValidTimezone('EST'); // false (use IANA names)
+   * handler.isValidTimezone('Invalid/Zone'); // false
+   * ```
+   */
+  isValidTimezone(timezone: string): boolean;
+  /**
+   * Get current offset for a timezone (useful for debugging)
+   *
+   * @param timezone - IANA timezone name
+   * @returns Offset in minutes from UTC (e.g., -300 for EST)
+   *
+   * @example
+   * ```typescript
+   * handler.getCurrentOffset('America/New_York'); // -300 (EST) or -240 (EDT)
+   * ```
+   */
+  getCurrentOffset(timezone: string): number;
+  /**
+   * Check if a timezone is currently in DST
+   *
+   * @param timezone - IANA timezone name
+   * @returns true if currently observing DST, false otherwise
+   *
+   * @example
+   * ```typescript
+   * handler.isInDST('America/New_York'); // true in summer, false in winter
+   * ```
+   */
+  isInDST(timezone: string): boolean;
+}
+/**
+ * Singleton instance for convenience
+ * Use this for most cases unless you need custom configuration
+ */
+declare const timezoneHandler: TimezoneHandler;
+//#endregion
+//#region src/features/parallel.d.ts
+/**
+ * Parallel Execution Utilities
+ *
+ * Provides utilities for executing multiple async operations in parallel
+ * with support for different modes, concurrency limits, and timeouts.
+ *
+ * @example
+ * ```typescript
+ * // Execute all tasks in parallel
+ * const results = await executeParallel([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3),
+ * ]);
+ *
+ * // With concurrency limit
+ * const results = await executeParallel(tasks, { concurrency: 2 });
+ *
+ * // With allSettled mode (never throws)
+ * const results = await executeParallel(tasks, { mode: 'allSettled' });
+ * ```
+ */
+interface ExecuteParallelOptions {
+  /**
+   * Execution mode:
+   * - 'all': Wait for all tasks to complete (throws if any fails)
+   * - 'race': Complete when first task completes
+   * - 'any': Complete when first task succeeds
+   * - 'allSettled': Wait for all tasks, return success/failure for each
+   *
+   * @default 'all'
+   */
+  mode?: 'all' | 'race' | 'any' | 'allSettled';
+  /**
+   * Maximum number of tasks to run concurrently
+   * @default Infinity
+   */
+  concurrency?: number;
+  /**
+   * Maximum time in milliseconds for each task
+   * @default undefined (no timeout)
+   */
+  timeout?: number;
+}
+/**
+ * Execute multiple async tasks in parallel with configurable mode,
+ * concurrency limits, and timeouts.
+ *
+ * @param tasks - Array of async task functions to execute
+ * @param options - Execution options (mode, concurrency, timeout)
+ * @returns Array of results (exact type depends on mode)
+ *
+ * @example Basic parallel execution
+ * ```typescript
+ * const results = await executeParallel([
+ *   () => fetch('/api/users'),
+ *   () => fetch('/api/posts'),
+ *   () => fetch('/api/comments'),
+ * ]);
+ * ```
+ *
+ * @example With concurrency limit
+ * ```typescript
+ * // Only 2 requests at a time
+ * const results = await executeParallel(urlTasks, { concurrency: 2 });
+ * ```
+ *
+ * @example With allSettled mode (never throws)
+ * ```typescript
+ * const results = await executeParallel(tasks, { mode: 'allSettled' });
+ * for (const result of results) {
+ *   if (result.success) {
+ *     console.log('Success:', result.value);
+ *   } else {
+ *     console.log('Failed:', result.reason);
+ *   }
+ * }
+ * ```
+ */
+declare function executeParallel<T>(tasks: Array<() => Promise<T>>, options?: ExecuteParallelOptions): Promise<T[] | Array<{
+  success: boolean;
+  value?: T;
+  reason?: unknown;
+}>>;
+//#endregion
+//#region src/features/conditional.d.ts
+interface ConditionalStep extends Step {
+  condition?: (context: unknown, run: WorkflowRun<unknown>) => boolean | Promise<boolean>;
+  skipIf?: (context: unknown) => boolean | Promise<boolean>;
+  runIf?: (context: unknown) => boolean | Promise<boolean>;
+}
+declare function isConditionalStep(step: Step): step is ConditionalStep;
+declare function shouldSkipStep<TContext>(step: ConditionalStep, context: TContext, run: WorkflowRun<TContext>): Promise<boolean>;
+declare function createCondition<TContext>(predicate: (context: TContext) => boolean): (context: TContext) => boolean;
+declare const conditions: {
+  hasValue: <TContext>(key: keyof TContext) => (context: TContext) => boolean;
+  equals: <TContext>(key: keyof TContext, value: TContext[keyof TContext]) => (context: TContext) => boolean;
+  notEquals: <TContext>(key: keyof TContext, value: TContext[keyof TContext]) => (context: TContext) => boolean;
+  greaterThan: <TContext>(key: keyof TContext, value: number) => (context: TContext) => boolean;
+  lessThan: <TContext>(key: keyof TContext, value: number) => (context: TContext) => boolean;
+  in: <TContext>(key: keyof TContext, values: readonly TContext[keyof TContext][]) => (context: TContext) => boolean;
+  and: <TContext>(...predicates: Array<(context: TContext) => boolean>) => (context: TContext) => boolean;
+  or: <TContext>(...predicates: Array<(context: TContext) => boolean>) => (context: TContext) => boolean;
+  not: <TContext>(predicate: (context: TContext) => boolean) => (context: TContext) => boolean;
+  custom: <TContext>(predicate: (context: TContext) => boolean) => (context: TContext) => boolean;
+};
+//#endregion
+//#region src/utils/errors.d.ts
+/**
+ * Custom error classes with rich context for better debugging
+ */
+/**
+ * Standardized error codes for programmatic error handling.
+ * Use these codes to handle specific error conditions in your application.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await workflow.resume(runId);
+ * } catch (err) {
+ *   if (err.code === ErrorCode.WORKFLOW_NOT_FOUND) {
+ *     // Handle missing workflow
+ *   }
+ * }
+ * ```
+ */
+declare const ErrorCode: {
+  readonly WORKFLOW_NOT_FOUND: "WORKFLOW_NOT_FOUND";
+  readonly WORKFLOW_ALREADY_COMPLETED: "WORKFLOW_ALREADY_COMPLETED";
+  readonly WORKFLOW_CANCELLED: "WORKFLOW_CANCELLED";
+  readonly STEP_NOT_FOUND: "STEP_NOT_FOUND";
+  readonly STEP_TIMEOUT: "STEP_TIMEOUT";
+  readonly STEP_FAILED: "STEP_FAILED";
+  readonly INVALID_STATE: "INVALID_STATE";
+  readonly INVALID_TRANSITION: "INVALID_TRANSITION";
+  readonly DATA_CORRUPTION: "DATA_CORRUPTION";
+  readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+  readonly MAX_RETRIES_EXCEEDED: "MAX_RETRIES_EXCEEDED";
+  readonly EXECUTION_ABORTED: "EXECUTION_ABORTED";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class WorkflowError extends Error {
+  readonly context: {
+    runId?: string;
+    workflowId?: string;
+    stepId?: string;
+    [key: string]: unknown;
+  };
+  readonly code: ErrorCode;
+  constructor(message: string, code: ErrorCode, context: {
+    runId?: string;
+    workflowId?: string;
+    stepId?: string;
+    [key: string]: unknown;
+  });
+  toString(): string;
+}
+declare class StepNotFoundError extends WorkflowError {
+  constructor(stepId: string, workflowId: string, availableSteps: string[]);
+}
+declare class WorkflowNotFoundError extends WorkflowError {
+  constructor(runId: string);
+}
+declare class InvalidStateError extends WorkflowError {
+  constructor(action: string, currentState: string, expectedStates: string[], context: {
+    runId?: string;
+    stepId?: string;
+  });
+}
+declare class StepTimeoutError extends WorkflowError {
+  constructor(stepId: string, timeoutMs: number, runId?: string);
+}
+declare class DataCorruptionError extends WorkflowError {
+  constructor(reason: string, context: {
+    runId: string;
+    [key: string]: unknown;
+  });
+}
+declare class MaxRetriesExceededError extends WorkflowError {
+  constructor(stepId: string, attempts: number, runId?: string);
+}
+//#endregion
+export { COMPUTED, type CacheHealthStatus, CommonQueries, type ConditionalStep, type ContainerOptions, DataCorruptionError, ErrorCode, type ErrorCode as ErrorCodeType, type ExecuteParallelOptions, type GetScheduledWorkflowsOptions, InferContext, InferHandlersContext, InvalidStateError, MaxRetriesExceededError, RUN_STATUS, RUN_STATUS_VALUES, RecurrencePattern, RunStatus, STEP_STATUS, STEP_STATUS_VALUES, type ScheduleWorkflowOptions, type SchedulerStats, SchedulingInfo, SchedulingService, type SchedulingServiceConfig, type SmartSchedulerConfig, Step, type StepContext, StepError, StepHandler, StepIds, StepNotFoundError, StepState, StepStatus, type StepTimeline, StepTimeoutError, type StepUIState, type StreamlineContainer, type TenantFilterOptions, type TimezoneCalculationResult, TimezoneHandler, TypedHandlers, WaitSignal, WaitingFor, WorkflowCache, WorkflowDefinition, type WorkflowDefinitionDoc, WorkflowDefinitionModel, WorkflowEngine, type WorkflowEngineOptions, WorkflowError, WorkflowEventBus, type WorkflowEventName, WorkflowEventPayload, WorkflowHandlers, WorkflowNotFoundError, type WorkflowProgress, WorkflowQueryBuilder, type WorkflowRepositoryConfig, type WorkflowRun, WorkflowRunModel, type WorkflowRunRepository, canRewindTo, conditions, createCondition, createContainer, createHook, createWorkflow, createWorkflowRepository, deriveRunStatus, executeParallel, getExecutionPath, getStepTimeline, getStepUIStates, getWaitingInfo, getWorkflowProgress, globalEventBus, hookRegistry, hookToken, isConditionalStep, isRunStatus, isStepStatus, isStreamlineContainer, isTerminalState, isValidRunTransition, isValidStepTransition, resumeHook, shouldSkipStep, singleTenantPlugin, tenantFilterPlugin, timezoneHandler, workflowDefinitionRepository, workflowRunRepository };