@uploadista/core 0.2.0 → 1.0.0-beta.2

package/dist/middleware-BmRmwme_.d.mts

@@ -0,0 +1,4129 @@
+import { n as UploadistaError } from "./uploadista-error-LtiZn-R_.mjs";
+import { Context, Effect, Layer, Stream } from "effect";
+import z$1, { z } from "zod";
+
+//#region src/types/circuit-breaker-store.d.ts
+/**
+ * Circuit breaker state values.
+ */
+type CircuitBreakerStateValue = "closed" | "open" | "half-open";
+/**
+ * Persisted circuit breaker state data.
+ *
+ * This represents the full state of a circuit breaker that needs to be
+ * stored and shared across instances.
+ */
+interface CircuitBreakerStateData {
+  /** Current circuit state */
+  state: CircuitBreakerStateValue;
+  /** Number of failures in current window */
+  failureCount: number;
+  /** Timestamp of last state transition */
+  lastStateChange: number;
+  /** Number of successful requests in half-open state */
+  halfOpenSuccesses: number;
+  /** Timestamp when the current failure window started */
+  windowStart: number;
+  /** Configuration snapshot for consistency */
+  config: {
+    failureThreshold: number;
+    resetTimeout: number;
+    halfOpenRequests: number;
+    windowDuration: number;
+  };
+}
+/**
+ * Statistics about a circuit breaker.
+ */
+interface CircuitBreakerStats {
+  nodeType: string;
+  state: CircuitBreakerStateValue;
+  failureCount: number;
+  halfOpenSuccesses: number;
+  timeSinceLastStateChange: number;
+  timeUntilHalfOpen?: number;
+}
+/**
+ * Interface for circuit breaker state storage.
+ *
+ * Implementations should handle distributed state for circuit breakers,
+ * allowing multiple instances to share circuit state. The interface is
+ * designed to work with eventually consistent stores - perfect consistency
+ * is not required for circuit breaker functionality.
+ *
+ * @example
+ * ```typescript
+ * // Using the store
+ * const store: CircuitBreakerStore = yield* CircuitBreakerStoreService;
+ *
+ * // Record a failure
+ * const newCount = yield* store.incrementFailures("describe-image", 60000);
+ * if (newCount >= 5) {
+ *   yield* store.setState("describe-image", {
+ *     state: "open",
+ *     failureCount: newCount,
+ *     lastStateChange: Date.now(),
+ *     // ...
+ *   });
+ * }
+ * ```
+ */
+interface CircuitBreakerStore {
+  /**
+   * Gets the current state data for a circuit breaker.
+   *
+   * @param nodeType - The node type identifier
+   * @returns The state data or null if no state exists
+   */
+  readonly getState: (nodeType: string) => Effect.Effect<CircuitBreakerStateData | null, UploadistaError>;
+  /**
+   * Sets the complete state for a circuit breaker.
+   *
+   * @param nodeType - The node type identifier
+   * @param state - The new state data
+   */
+  readonly setState: (nodeType: string, state: CircuitBreakerStateData) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Increments the failure count and returns the new count.
+   *
+   * This operation should be atomic where possible. For stores that don't
+   * support atomic increment, a read-modify-write is acceptable as circuit
+   * breakers tolerate eventual consistency.
+   *
+   * The implementation should also handle window expiry - if the window
+   * has expired, reset the count before incrementing.
+   *
+   * @param nodeType - The node type identifier
+   * @param windowDuration - Duration of the sliding window in milliseconds
+   * @returns The new failure count after incrementing
+   */
+  readonly incrementFailures: (nodeType: string, windowDuration: number) => Effect.Effect<number, UploadistaError>;
+  /**
+   * Resets the failure count to zero.
+   *
+   * Called when circuit closes or on successful requests.
+   *
+   * @param nodeType - The node type identifier
+   */
+  readonly resetFailures: (nodeType: string) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Increments the half-open success count.
+   *
+   * @param nodeType - The node type identifier
+   * @returns The new half-open success count
+   */
+  readonly incrementHalfOpenSuccesses: (nodeType: string) => Effect.Effect<number, UploadistaError>;
+  /**
+   * Gets statistics for all tracked circuit breakers.
+   *
+   * @returns Map of node type to stats
+   */
+  readonly getAllStats: () => Effect.Effect<Map<string, CircuitBreakerStats>, UploadistaError>;
+  /**
+   * Deletes circuit breaker state for a node type.
+   *
+   * @param nodeType - The node type identifier
+   */
+  readonly delete: (nodeType: string) => Effect.Effect<void, UploadistaError>;
+}
+declare const CircuitBreakerStoreService_base: Context.TagClass<CircuitBreakerStoreService, "CircuitBreakerStoreService", CircuitBreakerStore>;
+/**
+ * Effect-TS context tag for the CircuitBreakerStore service.
+ *
+ * Use this to inject a circuit breaker store into your Effect programs.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cbStore = yield* CircuitBreakerStoreService;
+ *   const state = yield* cbStore.getState("my-node-type");
+ *   // ...
+ * });
+ *
+ * // Provide the implementation
+ * const result = yield* program.pipe(
+ *   Effect.provide(kvCircuitBreakerStoreLayer)
+ * );
+ * ```
+ */
+declare class CircuitBreakerStoreService extends CircuitBreakerStoreService_base {}
+/**
+ * Creates a default initial state for a circuit breaker.
+ *
+ * @param config - Circuit breaker configuration
+ * @returns Initial state data with closed circuit
+ */
+declare function createInitialCircuitBreakerState(config: {
+  failureThreshold: number;
+  resetTimeout: number;
+  halfOpenRequests: number;
+  windowDuration: number;
+}): CircuitBreakerStateData;
+//#endregion
+//#region src/flow/types/dead-letter-item.d.ts
+/**
+ * Dead Letter Queue item types and definitions.
+ *
+ * A DeadLetterItem represents a failed flow job that has been captured
+ * for later retry, debugging, or manual intervention.
+ *
+ * @module flow/types/dead-letter-item
+ * @see {@link DeadLetterQueueService} for DLQ operations
+ */
+/**
+ * Status of a Dead Letter Queue item.
+ *
+ * Item lifecycle: pending → retrying → (pending | exhausted | resolved)
+ *
+ * - `pending`: Awaiting retry (either scheduled or manual)
+ * - `retrying`: Currently being retried
+ * - `exhausted`: Max retries reached, requires manual intervention
+ * - `resolved`: Successfully retried or manually resolved
+ */
+type DeadLetterItemStatus = "pending" | "retrying" | "exhausted" | "resolved";
+/**
+ * Error details captured when a flow job fails.
+ *
+ * Contains comprehensive error information for debugging and retry decisions.
+ *
+ * @property code - Error code (e.g., "FLOW_NODE_ERROR", "VALIDATION_ERROR")
+ * @property message - Human-readable error message
+ * @property nodeId - ID of the node that failed (if applicable)
+ * @property stack - Stack trace (included in development mode)
+ */
+interface DeadLetterError {
+  /** Error code for categorization and retry filtering */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Node that failed (if applicable) */
+  nodeId?: string;
+  /** Stack trace (in dev mode only) */
+  stack?: string;
+}
+/**
+ * Record of a single retry attempt.
+ *
+ * @property attemptedAt - When the retry was attempted
+ * @property error - Error message if the retry failed
+ * @property durationMs - How long the retry took
+ */
+interface DeadLetterRetryAttempt {
+  /** When the retry was attempted */
+  attemptedAt: Date;
+  /** Error message if the retry failed */
+  error: string;
+  /** Duration of the retry attempt in milliseconds */
+  durationMs: number;
+}
+/**
+ * Represents a failed flow job captured in the Dead Letter Queue.
+ *
+ * Contains all information needed to debug, retry, or manually resolve
+ * a failed flow execution.
+ *
+ * @property id - Unique DLQ item identifier
+ * @property jobId - Original flow job ID that failed
+ * @property flowId - Flow definition that was being executed
+ * @property storageId - Target storage for the flow
+ * @property clientId - Client who initiated the job
+ * @property error - Comprehensive error details
+ * @property inputs - Original inputs passed to the flow
+ * @property nodeResults - Partial results from nodes that completed before failure
+ * @property failedAtNodeId - Node where execution failed (if applicable)
+ * @property retryCount - Number of retry attempts made
+ * @property maxRetries - Maximum retries allowed from retry policy
+ * @property nextRetryAt - Scheduled time for next automatic retry
+ * @property retryHistory - History of all retry attempts
+ * @property createdAt - When the item was added to DLQ
+ * @property updatedAt - When the item was last modified
+ * @property expiresAt - TTL for automatic cleanup
+ * @property status - Current status of the DLQ item
+ *
+ * @example
+ * ```typescript
+ * const dlqItem: DeadLetterItem = {
+ *   id: "dlq_abc123",
+ *   jobId: "job_xyz789",
+ *   flowId: "image-resize-pipeline",
+ *   storageId: "s3-production",
+ *   clientId: "client_456",
+ *   error: {
+ *     code: "FLOW_NODE_ERROR",
+ *     message: "External service timeout",
+ *     nodeId: "resize-node"
+ *   },
+ *   inputs: { input: { uploadId: "upload_123" } },
+ *   nodeResults: { "input-node": { file: {...} } },
+ *   failedAtNodeId: "resize-node",
+ *   retryCount: 2,
+ *   maxRetries: 3,
+ *   nextRetryAt: new Date("2024-01-15T10:35:00Z"),
+ *   retryHistory: [
+ *     { attemptedAt: new Date("2024-01-15T10:30:00Z"), error: "Timeout", durationMs: 5000 },
+ *     { attemptedAt: new Date("2024-01-15T10:32:00Z"), error: "Timeout", durationMs: 5000 }
+ *   ],
+ *   createdAt: new Date("2024-01-15T10:30:00Z"),
+ *   updatedAt: new Date("2024-01-15T10:32:00Z"),
+ *   expiresAt: new Date("2024-01-22T10:30:00Z"),
+ *   status: "pending"
+ * };
+ * ```
+ */
+interface DeadLetterItem {
+  /** Unique DLQ item identifier */
+  id: string;
+  /** Original flow job ID that failed */
+  jobId: string;
+  /** Flow definition ID that was being executed */
+  flowId: string;
+  /** Target storage for the flow */
+  storageId: string;
+  /** Client who initiated the job (null for anonymous) */
+  clientId: string | null;
+  /** Comprehensive error details */
+  error: DeadLetterError;
+  /** Original inputs passed to the flow */
+  inputs: Record<string, unknown>;
+  /** Partial results from nodes that completed before failure */
+  nodeResults: Record<string, unknown>;
+  /** Node where execution failed (if applicable) */
+  failedAtNodeId?: string;
+  /** Number of retry attempts made */
+  retryCount: number;
+  /** Maximum retries allowed from retry policy */
+  maxRetries: number;
+  /** Scheduled time for next automatic retry */
+  nextRetryAt?: Date;
+  /** History of all retry attempts */
+  retryHistory: DeadLetterRetryAttempt[];
+  /** When the item was added to DLQ */
+  createdAt: Date;
+  /** When the item was last modified */
+  updatedAt: Date;
+  /** TTL for automatic cleanup */
+  expiresAt?: Date;
+  /** Current status of the DLQ item */
+  status: DeadLetterItemStatus;
+}
+/**
+ * Statistics about the Dead Letter Queue.
+ *
+ * Provides aggregate information for monitoring and alerting.
+ *
+ * @property totalItems - Total number of items in the DLQ
+ * @property byStatus - Count of items by status
+ * @property byFlow - Count of items by flow ID
+ * @property oldestItem - Timestamp of the oldest item
+ * @property averageRetryCount - Average number of retries across all items
+ */
+interface DeadLetterQueueStats {
+  /** Total number of items in the DLQ */
+  totalItems: number;
+  /** Count of items by status */
+  byStatus: Record<DeadLetterItemStatus, number>;
+  /** Count of items by flow ID */
+  byFlow: Record<string, number>;
+  /** Timestamp of the oldest item */
+  oldestItem?: Date;
+  /** Average number of retries across all items */
+  averageRetryCount: number;
+}
+/**
+ * Options for listing DLQ items.
+ *
+ * @property status - Filter by status
+ * @property flowId - Filter by flow ID
+ * @property clientId - Filter by client ID
+ * @property limit - Maximum items to return (default: 50)
+ * @property offset - Number of items to skip (default: 0)
+ */
+interface DeadLetterListOptions {
+  /** Filter by status */
+  status?: DeadLetterItemStatus;
+  /** Filter by flow ID */
+  flowId?: string;
+  /** Filter by client ID */
+  clientId?: string;
+  /** Maximum items to return (default: 50) */
+  limit?: number;
+  /** Number of items to skip for pagination (default: 0) */
+  offset?: number;
+}
+/**
+ * Result of a batch retry operation.
+ *
+ * @property retried - Number of items that were retried
+ * @property succeeded - Number of retries that succeeded
+ * @property failed - Number of retries that failed
+ */
+interface DeadLetterRetryAllResult {
+  /** Number of items that were retried */
+  retried: number;
+  /** Number of retries that succeeded */
+  succeeded: number;
+  /** Number of retries that failed */
+  failed: number;
+}
+/**
+ * Result of a cleanup operation.
+ *
+ * @property deleted - Number of items that were deleted
+ */
+interface DeadLetterCleanupResult {
+  /** Number of items that were deleted */
+  deleted: number;
+}
+/**
+ * Options for cleanup operation.
+ *
+ * @property olderThan - Delete items older than this date
+ * @property status - Only delete items with this status
+ */
+interface DeadLetterCleanupOptions {
+  /** Delete items older than this date */
+  olderThan?: Date;
+  /** Only delete items with this status */
+  status?: "exhausted" | "resolved";
+}
+/**
+ * Result of processing scheduled retries.
+ *
+ * @property processed - Total items processed
+ * @property succeeded - Number that succeeded
+ * @property failed - Number that failed
+ */
+interface DeadLetterProcessResult {
+  /** Total items processed */
+  processed: number;
+  /** Number of successful retries */
+  succeeded: number;
+  /** Number of failed retries */
+  failed: number;
+}
+//#endregion
+//#region src/types/upload-file.d.ts
+/**
+ * Zod schema for validating UploadFile objects.
+ *
+ * This schema defines the structure and validation rules for upload file metadata.
+ * Use this schema to parse and validate UploadFile data from external sources.
+ *
+ * @see {@link UploadFile} for the TypeScript type
+ */
+/**
+ * Zod schema for trace context used in distributed tracing.
+ */
+declare const traceContextSchema: z.ZodObject<{
+  traceId: z.ZodString;
+  spanId: z.ZodString;
+  traceFlags: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * JSON value type that allows any JSON-serializable data.
+ * Used for metadata values which can be primitives, arrays, or nested objects.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * JSON value schema that allows any JSON-serializable data.
+ * This is used for metadata values which can be primitives, arrays, or objects.
+ */
+declare const jsonValueSchema: z.ZodType<JsonValue>;
+declare const uploadFileSchema: z.ZodObject<{
+  id: z.ZodString;
+  size: z.ZodOptional<z.ZodNumber>;
+  offset: z.ZodNumber;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+  creationDate: z.ZodOptional<z.ZodString>;
+  url: z.ZodOptional<z.ZodString>;
+  sizeIsDeferred: z.ZodOptional<z.ZodBoolean>;
+  checksum: z.ZodOptional<z.ZodString>;
+  checksumAlgorithm: z.ZodOptional<z.ZodString>;
+  storage: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    uploadId: z.ZodOptional<z.ZodString>;
+    bucket: z.ZodOptional<z.ZodString>;
+    parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      partNumber: z.ZodNumber;
+      etag: z.ZodString;
+      size: z.ZodNumber;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+  traceContext: z.ZodOptional<z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    traceFlags: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Represents an uploaded file with its metadata and storage information.
+ *
+ * This is the core data structure that tracks file uploads throughout their lifecycle.
+ * It contains all metadata needed to resume uploads, track progress, and locate files
+ * in storage backends.
+ *
+ * @property id - Unique identifier for this upload
+ * @property offset - Current byte offset (how many bytes have been uploaded)
+ * @property storage - Storage backend information
+ * @property storage.id - Storage backend identifier (e.g., "s3-production")
+ * @property storage.type - Storage backend type (e.g., "s3", "azure", "gcs")
+ * @property storage.path - Optional path prefix within the storage backend
+ * @property storage.uploadId - Optional backend-specific upload ID (e.g., S3 multipart upload ID)
+ * @property storage.bucket - Optional bucket or container name
+ * @property storage.parts - Optional array of uploaded parts (used by data stores that need to track parts locally, like R2)
+ * @property flow - Optional flow processing information (when file is part of a flow)
+ * @property flow.flowId - ID of the flow processing this file
+ * @property flow.nodeId - ID of the flow node that created this file
+ * @property flow.jobId - ID of the flow job execution
+ * @property size - Total file size in bytes (undefined if deferred)
+ * @property metadata - Custom key-value metadata attached to the file
+ * @property creationDate - ISO 8601 timestamp when upload was created
+ * @property url - Optional public URL to access the file
+ * @property sizeIsDeferred - True if file size is not known at upload start
+ * @property checksum - Optional file checksum/hash value
+ * @property checksumAlgorithm - Algorithm used for checksum (e.g., "md5", "sha256")
+ *
+ * @example
+ * ```typescript
+ * // Create an UploadFile for a new upload
+ * const uploadFile: UploadFile = {
+ *   id: "upload_abc123",
+ *   offset: 0,
+ *   size: 1024000,
+ *   storage: {
+ *     id: "s3-production",
+ *     type: "s3",
+ *     bucket: "my-uploads",
+ *     path: "files/"
+ *   },
+ *   metadata: {
+ *     fileName: "image.jpg",
+ *     contentType: "image/jpeg",
+ *     userId: "user_123"
+ *   },
+ *   creationDate: new Date().toISOString(),
+ *   checksum: "5d41402abc4b2a76b9719d911017c592",
+ *   checksumAlgorithm: "md5"
+ * };
+ *
+ * // UploadFile with flow processing
+ * const flowFile: UploadFile = {
+ *   id: "upload_xyz789",
+ *   offset: 0,
+ *   size: 2048000,
+ *   storage: {
+ *     id: "s3-temp",
+ *     type: "s3",
+ *     bucket: "temp-processing"
+ *   },
+ *   flow: {
+ *     flowId: "flow_resize_optimize",
+ *     nodeId: "input_1",
+ *     jobId: "job_456"
+ *   }
+ * };
+ *
+ * // Resume an interrupted upload
+ * const resumingFile: UploadFile = {
+ *   id: "upload_resume",
+ *   offset: 524288, // Already uploaded 512KB
+ *   size: 1024000,
+ *   storage: {
+ *     id: "s3-production",
+ *     type: "s3",
+ *     uploadId: "multipart_xyz" // S3 multipart upload ID
+ *   }
+ * };
+ * ```
+ */
+/**
+ * Trace context for distributed tracing.
+ * Allows upload operations to be linked under a single trace.
+ */
+type UploadFileTraceContext = {
+  /** 128-bit trace identifier (32 hex characters) */traceId: string; /** 64-bit span identifier (16 hex characters) */
+  spanId: string; /** Trace flags (1 = sampled) */
+  traceFlags: number;
+};
+type UploadFile = {
+  id: string;
+  offset: number;
+  storage: {
+    id: string;
+    type: string;
+    path?: string | undefined;
+    uploadId?: string | undefined;
+    bucket?: string | undefined;
+    parts?: Array<{
+      partNumber: number;
+      etag: string;
+      size: number;
+    }> | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+  size?: number | undefined;
+  metadata?: Record<string, JsonValue> | undefined;
+  creationDate?: string | undefined;
+  url?: string | undefined;
+  sizeIsDeferred?: boolean | undefined;
+  checksum?: string | undefined;
+  checksumAlgorithm?: string | undefined;
+  /**
+   * OpenTelemetry trace context for distributed tracing.
+   * When set, subsequent upload operations (chunks, validation) will be
+   * linked as children of this trace context.
+   */
+  traceContext?: UploadFileTraceContext | undefined;
+};
+//#endregion
+//#region src/flow/node.d.ts
+/**
+ * Defines the type of node in a flow, determining its role in the processing pipeline.
+ */
+declare enum NodeType {
+  /** Entry point for data into the flow */
+  input = "input",
+  /** Transforms data during flow execution */
+  process = "process",
+  /** Routes data based on conditions */
+  conditional = "conditional",
+  /** Splits data to multiple outputs */
+  multiplex = "multiplex",
+  /** Combines multiple inputs into one output */
+  merge = "merge"
+}
+/**
+ * Fields that can be evaluated in conditional node conditions.
+ * These fields are typically found in file metadata.
+ */
+type ConditionField = "mimeType" | "size" | "width" | "height" | "extension";
+/**
+ * Operators available for comparing values in conditional node conditions.
+ */
+type ConditionOperator = "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "startsWith";
+/**
+ * Value used in conditional node comparisons.
+ * Can be either a string or number depending on the field being evaluated.
+ */
+type ConditionValue = string | number;
+/**
+ * Creates a flow node with automatic input/output validation and retry logic.
+ *
+ * Flow nodes are the building blocks of processing pipelines. Each node:
+ * - Validates its input against a Zod schema
+ * - Executes its processing logic
+ * - Validates its output against a Zod schema
+ * - Can optionally retry on failure with exponential backoff
+ *
+ * @template Input - The expected input type for this node
+ * @template Output - The output type produced by this node
+ *
+ * @param config - Node configuration
+ * @param config.id - Unique identifier for this node in the flow
+ * @param config.name - Human-readable name for the node
+ * @param config.description - Description of what this node does
+ * @param config.type - The type of node (input, process, conditional, multiplex, merge)
+ * @param config.inputSchema - Zod schema for validating input data
+ * @param config.outputSchema - Zod schema for validating output data
+ * @param config.run - The processing function to execute for this node
+ * @param config.condition - Optional condition for conditional nodes to determine if they should execute
+ * @param config.multiInput - If true, node receives all inputs as a record instead of a single input
+ * @param config.multiOutput - If true, node can output to multiple targets
+ * @param config.pausable - If true, node can pause execution and wait for additional data
+ * @param config.retry - Optional retry configuration for handling transient failures
+ * @param config.retry.maxRetries - Maximum number of retry attempts (default: 0)
+ * @param config.retry.retryDelay - Base delay in milliseconds between retries (default: 1000)
+ * @param config.retry.exponentialBackoff - Whether to use exponential backoff for retries (default: true)
+ * @param config.inputTypeId - Optional input type ID from inputTypeRegistry (e.g., "streaming-input-v1"). Used for input nodes to describe external interface.
+ * @param config.outputTypeId - Optional output type ID from outputTypeRegistry (e.g., "storage-output-v1"). Used for result type tagging.
+ * @param config.keepOutput - If true, preserves this node's output even if it has outgoing edges (default: false). Useful for flows where intermediate results need to be kept (e.g., preserving the original file when also running OCR on it).
+ * @param config.circuitBreaker - Optional circuit breaker configuration for resilience. Overrides flow-level circuit breaker defaults for this node.
+ * @param config.nodeTypeId - Stable node type identifier for circuit breaker configuration. Used to share circuit breaker state across nodes of the same type and for nodeTypeOverrides. Example: "describe-image", "remove-background", "scan-virus"
+ *
+ * @returns An Effect that succeeds with the created FlowNode
+ *
+ * @example
+ * ```typescript
+ * const resizeNode = createFlowNode({
+ *   id: "resize-1",
+ *   name: "Resize Image",
+ *   description: "Resizes images to 800x600",
+ *   type: NodeType.process,
+ *   inputSchema: z.object({
+ *     stream: z.instanceof(Uint8Array),
+ *     metadata: z.object({ width: z.number(), height: z.number() })
+ *   }),
+ *   outputSchema: z.object({
+ *     stream: z.instanceof(Uint8Array),
+ *     metadata: z.object({ width: z.literal(800), height: z.literal(600) })
+ *   }),
+ *   run: ({ data }) => Effect.gen(function* () {
+ *     const resized = yield* resizeImage(data.stream, 800, 600);
+ *     return {
+ *       type: "complete",
+ *       data: { stream: resized, metadata: { width: 800, height: 600 } }
+ *     };
+ *   }),
+ *   retry: {
+ *     maxRetries: 3,
+ *     retryDelay: 1000,
+ *     exponentialBackoff: true
+ *   }
+ * });
+ * ```
+ */
+declare function createFlowNode<Input, Output, TType extends NodeType = NodeType>({
+  id,
+  name,
+  description,
+  type,
+  inputSchema,
+  outputSchema,
+  run,
+  condition,
+  multiInput,
+  multiOutput,
+  pausable,
+  retry,
+  inputTypeId,
+  outputTypeId,
+  keepOutput,
+  circuitBreaker,
+  nodeTypeId
+}: {
+  id: string;
+  name: string;
+  description: string;
+  type: TType;
+  inputSchema: z.ZodSchema<Input>;
+  outputSchema: z.ZodSchema<Output>;
+  run: (args: {
+    data: Input;
+    jobId: string;
+    storageId: string;
+    flowId: string;
+    clientId: string | null;
+  }) => Effect.Effect<NodeExecutionResult<Output>, UploadistaError>;
+  condition?: {
+    field: ConditionField;
+    operator: ConditionOperator;
+    value: ConditionValue;
+  };
+  multiInput?: boolean;
+  multiOutput?: boolean;
+  pausable?: boolean;
+  retry?: {
+    maxRetries?: number;
+    retryDelay?: number;
+    exponentialBackoff?: boolean;
+  }; /** Input type ID from inputTypeRegistry - for input nodes describing external interface */
+  inputTypeId?: string; /** Output type ID from outputTypeRegistry - for result type tagging */
+  outputTypeId?: string;
+  keepOutput?: boolean; /** Circuit breaker configuration for resilience (overrides flow defaults) */
+  circuitBreaker?: FlowCircuitBreakerConfig;
+  /**
+   * Stable node type identifier for circuit breaker configuration.
+   * Used to share circuit breaker state across nodes of the same type and for nodeTypeOverrides.
+   * Example: "describe-image", "remove-background", "scan-virus"
+   */
+  nodeTypeId?: string;
+}): Effect.Effect<FlowNode<Input, Output, UploadistaError> & {
+  type: TType;
+}, UploadistaError>;
+/**
+ * Extracts serializable node metadata from a FlowNode instance.
+ *
+ * This function is useful for serializing flow configurations or
+ * transmitting node information over the network without including
+ * the executable run function or schemas.
+ *
+ * @param node - The flow node to extract data from
+ * @returns A plain object containing the node's metadata (id, name, description, type, inputTypeId, outputTypeId)
+ */
+declare const getNodeData: (node: FlowNode<any, any, UploadistaError>) => FlowNodeData;
+//#endregion
+//#region src/flow/event.d.ts
+/**
+ * Enumeration of all possible flow and node execution event types.
+ *
+ * Events follow a lifecycle pattern:
+ * - Job level: JobStart → ... → JobEnd
+ * - Flow level: FlowStart → ... → (FlowEnd | FlowError)
+ * - Node level: NodeStart → ... → (NodeEnd | NodePause | NodeError)
+ *
+ * @example
+ * ```typescript
+ * // Listen for flow completion
+ * if (event.eventType === EventType.FlowEnd) {
+ *   console.log("Flow completed:", event.result);
+ * }
+ * ```
+ */
+declare enum EventType {
+  /** Emitted when a job starts execution */
+  JobStart = "job-start",
+  /** Emitted when a job completes (success or failure) */
+  JobEnd = "job-end",
+  /** Emitted when a flow begins execution */
+  FlowStart = "flow-start",
+  /** Emitted when a flow completes successfully */
+  FlowEnd = "flow-end",
+  /** Emitted when a flow encounters an error */
+  FlowError = "flow-error",
+  /** Emitted when a flow is paused by user request */
+  FlowPause = "flow-pause",
+  /** Emitted when a flow is cancelled by user request */
+  FlowCancel = "flow-cancel",
+  /** Emitted when a node starts processing */
+  NodeStart = "node-start",
+  /** Emitted when a node completes successfully */
+  NodeEnd = "node-end",
+  /** Emitted when a node pauses (waiting for additional data) */
+  NodePause = "node-pause",
+  /** Emitted when a paused node resumes execution */
+  NodeResume = "node-resume",
+  /** Emitted when a node encounters an error */
+  NodeError = "node-error",
+  /** Emitted for streaming node data (e.g., progress updates) */
+  NodeStream = "node-stream",
+  /** Emitted for node response data */
+  NodeResponse = "node-response",
+  /** Emitted when a job is added to the Dead Letter Queue */
+  DlqItemAdded = "dlq-item-added",
+  /** Emitted when a DLQ retry attempt starts */
+  DlqRetryStart = "dlq-retry-start",
+  /** Emitted when a DLQ retry succeeds */
+  DlqRetrySuccess = "dlq-retry-success",
+  /** Emitted when a DLQ retry fails */
+  DlqRetryFailed = "dlq-retry-failed",
+  /** Emitted when a DLQ item is exhausted (max retries reached) */
+  DlqItemExhausted = "dlq-item-exhausted",
+  /** Emitted when a DLQ item is resolved */
+  DlqItemResolved = "dlq-item-resolved"
+}
+/**
+ * Event emitted when a job starts execution.
+ */
+type FlowEventJobStart = {
+  jobId: string;
+  eventType: EventType.JobStart;
+};
+/**
+ * Event emitted when a job completes (either successfully or with failure).
+ */
+type FlowEventJobEnd = {
+  jobId: string;
+  eventType: EventType.JobEnd;
+};
+/**
+ * Event emitted when a flow begins execution.
+ * This is the first event after JobStart in the execution lifecycle.
+ */
+type FlowEventFlowStart = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowStart;
+};
+/**
+ * Event emitted when a flow completes successfully.
+ *
+ * @property outputs - Array of typed outputs from all output nodes in the flow
+ * @property result - Legacy field for backward compatibility (deprecated, use outputs instead)
+ *
+ * @remarks
+ * The `outputs` field contains an array of TypedOutput objects, each with:
+ * - nodeId: The specific node that produced the output
+ * - nodeType: The registered type ID (e.g., "storage-output-v1")
+ * - data: The actual output data
+ * - timestamp: When the output was produced
+ *
+ * @example
+ * ```typescript
+ * // Handle flow completion with typed outputs
+ * if (event.eventType === EventType.FlowEnd && event.outputs) {
+ *   for (const output of event.outputs) {
+ *     console.log(`${output.nodeId} (${output.nodeType}):`, output.data);
+ *   }
+ * }
+ * ```
+ */
+type FlowEventFlowEnd = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowEnd;
+  outputs?: TypedOutput[];
+  result?: unknown;
+};
+/**
+ * Event emitted when a flow encounters an unrecoverable error.
+ *
+ * @property error - Error message describing what went wrong
+ */
+type FlowEventFlowError = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowError;
+  error: string;
+};
+/**
+ * Event emitted when a flow is paused by user request.
+ *
+ * Unlike NodePause which occurs when a node needs more data,
+ * this event is triggered by an explicit user action to pause the flow.
+ */
+type FlowEventFlowPause = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowPause;
+  pausedAt?: string;
+};
+/**
+ * Event emitted when a flow is cancelled by user request.
+ *
+ * Cancelled flows will clean up intermediate files and stop execution.
+ */
+type FlowEventFlowCancel = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowCancel;
+};
+/**
+ * Event emitted when a node begins processing.
+ *
+ * @property nodeName - Human-readable node name
+ * @property nodeType - Type of node (input, transform, conditional, output, etc.)
+ */
+type FlowEventNodeStart = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeStart;
+  nodeName: string;
+  nodeType: NodeType;
+};
+/**
+ * Event emitted when a node fails after all retry attempts.
+ *
+ * @property error - Error message from the failed execution
+ * @property retryCount - Number of retry attempts made before giving up
+ */
+type FlowEventNodeError = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  nodeName: string;
+  eventType: EventType.NodeError;
+  error: string;
+  retryCount?: number;
+};
+/**
+ * Event emitted when a node completes successfully.
+ *
+ * @property result - The typed output data produced by the node
+ *
+ * @remarks
+ * For output nodes, the result will be a TypedOutput containing type information.
+ * For other nodes, it may be untyped (nodeType will be undefined).
+ */
+type FlowEventNodeEnd = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeEnd;
+  nodeName: string;
+  result?: TypedOutput | unknown;
+};
+/**
+ * Event emitted when a node pauses execution, waiting for additional data.
+ *
+ * This typically occurs with input nodes that need more chunks or nodes
+ * waiting for external services.
+ *
+ * @property partialData - Any partial result available before pausing
+ */
+type FlowEventNodePause = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodePause;
+  nodeName: string;
+  partialData?: unknown;
+};
+/**
+ * Event emitted when a paused node resumes execution.
+ *
+ * This occurs after providing the additional data needed by a paused node.
+ */
+type FlowEventNodeResume = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeResume;
+  nodeName: string;
+  nodeType: NodeType;
+};
+/**
+ * Event emitted for node-specific response data.
+ *
+ * Used for streaming intermediate results or progress updates.
+ */
+type FlowEventNodeResponse = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeResponse;
+  nodeName: string;
+  data: unknown;
+};
+/**
+ * Event emitted when a job is added to the Dead Letter Queue.
+ */
+type FlowEventDlqItemAdded = {
+  eventType: EventType.DlqItemAdded;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  errorCode: string;
+  errorMessage: string;
+  retryCount: number;
+  maxRetries: number;
+};
+/**
+ * Event emitted when a DLQ retry attempt starts.
+ */
+type FlowEventDlqRetryStart = {
+  eventType: EventType.DlqRetryStart;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  attemptNumber: number;
+};
+/**
+ * Event emitted when a DLQ retry succeeds.
+ */
+type FlowEventDlqRetrySuccess = {
+  eventType: EventType.DlqRetrySuccess;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  attemptNumber: number;
+  durationMs: number;
+};
+/**
+ * Event emitted when a DLQ retry fails.
+ */
+type FlowEventDlqRetryFailed = {
+  eventType: EventType.DlqRetryFailed;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  attemptNumber: number;
+  error: string;
+  durationMs: number;
+  nextRetryAt?: string;
+};
+/**
+ * Event emitted when a DLQ item is exhausted (max retries reached).
+ */
+type FlowEventDlqItemExhausted = {
+  eventType: EventType.DlqItemExhausted;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  totalAttempts: number;
+};
+/**
+ * Event emitted when a DLQ item is resolved.
+ */
+type FlowEventDlqItemResolved = {
+  eventType: EventType.DlqItemResolved;
+  dlqItemId: string;
+  jobId: string;
+  flowId: string;
+  resolvedBy: "retry" | "manual";
+};
+/**
+ * Union of all DLQ-related events.
+ */
+type DlqEvent = FlowEventDlqItemAdded | FlowEventDlqRetryStart | FlowEventDlqRetrySuccess | FlowEventDlqRetryFailed | FlowEventDlqItemExhausted | FlowEventDlqItemResolved;
+/**
+ * Union of all possible flow execution events.
+ *
+ * This discriminated union allows type-safe event handling based on eventType.
+ *
+ * @example
+ * ```typescript
+ * function handleFlowEvent(event: FlowEvent) {
+ *   switch (event.eventType) {
+ *     case EventType.FlowStart:
+ *       console.log("Flow started:", event.flowId);
+ *       break;
+ *     case EventType.NodeEnd:
+ *       console.log("Node completed:", event.nodeName, event.result);
+ *       break;
+ *     case EventType.FlowError:
+ *       console.error("Flow failed:", event.error);
+ *       break;
+ *     case EventType.FlowCancel:
+ *       console.log("Flow cancelled:", event.flowId);
+ *       break;
+ *     case EventType.DlqItemAdded:
+ *       console.log("Job added to DLQ:", event.dlqItemId);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+type FlowEvent = FlowEventJobStart | FlowEventJobEnd | FlowEventFlowStart | FlowEventFlowEnd | FlowEventFlowError | FlowEventFlowPause | FlowEventFlowCancel | FlowEventNodeStart | FlowEventNodeEnd | FlowEventNodePause | FlowEventNodeResume | FlowEventNodeError | DlqEvent;
+//#endregion
+//#region src/flow/types/retry-policy.d.ts
+/**
+ * Retry policy types for the Dead Letter Queue.
+ *
+ * Defines configurable retry strategies including immediate, fixed delay,
+ * and exponential backoff with jitter.
+ *
+ * @module flow/types/retry-policy
+ * @see {@link DeadLetterQueueService} for DLQ operations
+ */
+/**
+ * Immediate retry strategy - retry as soon as possible.
+ *
+ * Use for errors that are likely transient and may succeed on immediate retry.
+ */
+interface ImmediateBackoff {
+  type: "immediate";
+}
+/**
+ * Fixed delay retry strategy - wait a fixed duration between retries.
+ *
+ * @property delayMs - Milliseconds to wait between retries
+ *
+ * @example
+ * ```typescript
+ * const fixedBackoff: FixedBackoff = {
+ *   type: "fixed",
+ *   delayMs: 5000 // Wait 5 seconds between retries
+ * };
+ * ```
+ */
+interface FixedBackoff {
+  type: "fixed";
+  /** Milliseconds to wait between retries */
+  delayMs: number;
+}
+/**
+ * Exponential backoff retry strategy - progressively longer delays.
+ *
+ * Delay = min(initialDelayMs * (multiplier ^ retryCount), maxDelayMs)
+ * With optional jitter to prevent thundering herd.
+ *
+ * @property initialDelayMs - Starting delay in milliseconds (e.g., 1000)
+ * @property maxDelayMs - Maximum delay cap in milliseconds (e.g., 300000)
+ * @property multiplier - Multiplication factor per retry (e.g., 2)
+ * @property jitter - Add randomness to prevent thundering herd
+ *
+ * @example
+ * ```typescript
+ * const exponentialBackoff: ExponentialBackoff = {
+ *   type: "exponential",
+ *   initialDelayMs: 1000,   // Start with 1 second
+ *   maxDelayMs: 300000,     // Cap at 5 minutes
+ *   multiplier: 2,          // Double each time
+ *   jitter: true            // Add randomness
+ * };
+ * // Delays: ~1s, ~2s, ~4s, ~8s, ..., capped at ~5min
+ * ```
+ */
+interface ExponentialBackoff {
+  type: "exponential";
+  /** Starting delay in milliseconds */
+  initialDelayMs: number;
+  /** Maximum delay cap in milliseconds */
+  maxDelayMs: number;
+  /** Multiplication factor per retry (e.g., 2 for doubling) */
+  multiplier: number;
+  /** Add randomness to prevent thundering herd */
+  jitter: boolean;
+}
+/**
+ * Union type for all backoff strategies.
+ */
+type BackoffStrategy = ImmediateBackoff | FixedBackoff | ExponentialBackoff;
+/**
+ * Configuration for automatic retry behavior.
+ *
+ * Defines how failed jobs should be retried, including backoff strategy,
+ * max attempts, and error filtering.
+ *
+ * @property enabled - Whether automatic retry is enabled (default: true)
+ * @property maxRetries - Maximum retry attempts (default: 3)
+ * @property backoff - Backoff strategy configuration
+ * @property retryableErrors - Only retry these error codes (default: all)
+ * @property nonRetryableErrors - Never retry these error codes
+ * @property ttlMs - Auto-delete items after this time (default: 7 days)
+ *
+ * @example
+ * ```typescript
+ * // Conservative retry policy for external APIs
+ * const apiRetryPolicy: RetryPolicy = {
+ *   enabled: true,
+ *   maxRetries: 5,
+ *   backoff: {
+ *     type: "exponential",
+ *     initialDelayMs: 1000,
+ *     maxDelayMs: 60000,
+ *     multiplier: 2,
+ *     jitter: true
+ *   },
+ *   nonRetryableErrors: ["VALIDATION_ERROR", "AUTH_ERROR"],
+ *   ttlMs: 604800000 // 7 days
+ * };
+ *
+ * // Aggressive retry for transient failures
+ * const transientRetryPolicy: RetryPolicy = {
+ *   enabled: true,
+ *   maxRetries: 3,
+ *   backoff: { type: "immediate" },
+ *   retryableErrors: ["NETWORK_ERROR", "TIMEOUT_ERROR"]
+ * };
+ *
+ * // No automatic retry, manual intervention only
+ * const manualPolicy: RetryPolicy = {
+ *   enabled: false,
+ *   maxRetries: 0,
+ *   backoff: { type: "immediate" }
+ * };
+ * ```
+ */
+interface RetryPolicy {
+  /** Whether automatic retry is enabled (default: true) */
+  enabled: boolean;
+  /** Maximum retry attempts (default: 3) */
+  maxRetries: number;
+  /** Backoff strategy configuration */
+  backoff: BackoffStrategy;
+  /** Only retry these error codes. If undefined, retry all errors. */
+  retryableErrors?: string[];
+  /** Never retry these error codes. Takes precedence over retryableErrors. */
+  nonRetryableErrors?: string[];
+  /** Auto-delete items after this time in milliseconds (default: 7 days) */
+  ttlMs?: number;
+}
+/**
+ * Default retry policy values.
+ */
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Calculates the next retry delay based on the backoff strategy.
+ *
+ * @param backoff - The backoff strategy configuration
+ * @param retryCount - Current retry attempt number (0-based)
+ * @returns Delay in milliseconds before the next retry
+ *
+ * @example
+ * ```typescript
+ * const delay = calculateBackoffDelay(
+ *   { type: "exponential", initialDelayMs: 1000, maxDelayMs: 60000, multiplier: 2, jitter: true },
+ *   2 // Third attempt
+ * );
+ * // Returns approximately 4000ms (1000 * 2^2) with jitter
+ * ```
+ */
+declare function calculateBackoffDelay(backoff: BackoffStrategy, retryCount: number): number;
+/**
+ * Determines if an error should be retried based on the retry policy.
+ *
+ * @param errorCode - The error code to check
+ * @param policy - The retry policy configuration
+ * @returns true if the error should be retried
+ *
+ * @example
+ * ```typescript
+ * const policy: RetryPolicy = {
+ *   enabled: true,
+ *   maxRetries: 3,
+ *   backoff: { type: "immediate" },
+ *   nonRetryableErrors: ["VALIDATION_ERROR"]
+ * };
+ *
+ * isErrorRetryable("NETWORK_ERROR", policy); // true
+ * isErrorRetryable("VALIDATION_ERROR", policy); // false
+ * ```
+ */
+declare function isErrorRetryable(errorCode: string, policy: RetryPolicy): boolean;
+/**
+ * Calculates the expiration date for a DLQ item.
+ *
+ * @param createdAt - When the item was created
+ * @param ttlMs - Time to live in milliseconds
+ * @returns The expiration date, or undefined if no TTL
+ */
+declare function calculateExpirationDate(createdAt: Date, ttlMs?: number): Date | undefined;
+//#endregion
+//#region src/flow/types/flow-types.d.ts
+/**
+ * Type mapping for node input/output schemas.
+ * Used for type-safe node connections in typed flows.
+ */
+type NodeTypeMap = Record<string, {
+  input: unknown;
+  output: unknown;
+}>;
+/**
+ * Minimal node data without execution logic.
+ * Used for serialization and UI display.
+ *
+ * @property id - Unique node identifier
+ * @property name - Human-readable node name
+ * @property description - Explanation of what the node does
+ * @property type - Node category (input, transform, conditional, output, etc.)
+ * @property inputTypeId - Optional input type ID from inputTypeRegistry (for input nodes)
+ * @property outputTypeId - Optional output type ID from outputTypeRegistry (for result typing)
+ * @property keepOutput - If true, preserves this node's output even if it has outgoing edges (default: false)
+ */
+type FlowNodeData = {
+  id: string;
+  name: string;
+  description: string;
+  type: NodeType; /** Input type ID from inputTypeRegistry - describes how external clients interact with this node */
+  inputTypeId?: string; /** Output type ID from outputTypeRegistry - describes the data shape this node produces */
+  outputTypeId?: string;
+  keepOutput?: boolean;
+  /**
+   * Stable node type identifier for circuit breaker configuration.
+   * Used to share circuit breaker state across nodes of the same type and for nodeTypeOverrides.
+   * Example: "describe-image", "remove-background", "scan-virus"
+   */
+  nodeTypeId?: string;
+};
+/**
+ * All built-in node type identifiers.
+ * Used to exclude these from custom types for proper discriminated union narrowing.
+ */
+type BuiltInNodeType = "storage-output-v1" | "streaming-input-v1";
+/**
+ * Built-in typed outputs with automatic TypeScript narrowing.
+ *
+ * These outputs use discriminated unions to enable automatic type narrowing
+ * in switch statements without requiring type guards.
+ *
+ * @remarks
+ * Built-in types automatically narrow when using switch statements:
+ * ```typescript
+ * switch (output.nodeType) {
+ *   case 'storage-output-v1':
+ *     output.data.url // ✅ TypeScript knows data is UploadFile
+ *     break;
+ * }
+ * ```
+ */
+type BuiltInTypedOutput = {
+  nodeType: "storage-output-v1";
+  data: UploadFile;
+  nodeId: string;
+  timestamp: string;
+} | {
+  nodeType: "streaming-input-v1";
+  data: UploadFile;
+  nodeId: string;
+  timestamp: string;
+};
+/**
+ * Custom typed output for user-defined node types.
+ *
+ * Custom outputs require type guards for type narrowing:
+ * ```typescript
+ * if (isThumbnailOutput(output)) {
+ *   output.data.width // ✅ Type guard narrows data to ThumbnailOutput
+ * }
+ * ```
+ *
+ * @template T - The TypeScript type of the output data
+ */
+type CustomTypedOutput<T = unknown> = {
+  nodeType?: string;
+  data: T;
+  nodeId: string;
+  timestamp: string;
+};
+/**
+ * Typed output structure from a flow node.
+ *
+ * This is a discriminated union that provides automatic type narrowing for
+ * built-in types while maintaining extensibility for custom types.
+ *
+ * @template T - The TypeScript type of the output data (for custom outputs)
+ *
+ * @property nodeId - Node instance ID that produced this output
+ * @property nodeType - Type ID from the registry (e.g., "storage-output-v1")
+ * @property data - The actual output data from the node
+ * @property timestamp - ISO 8601 timestamp when the result was produced
+ *
+ * @remarks
+ * **Built-in types (automatic narrowing):**
+ * - `storage-output-v1` - Storage node output (UploadFile)
+ *
+ * Use switch statements for automatic narrowing:
+ * ```typescript
+ * for (const output of state.flowOutputs) {
+ *   switch (output.nodeType) {
+ *     case 'storage-output-v1':
+ *       // ✅ output.data is automatically UploadFile
+ *       console.log(output.data.url);
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * **Custom types (require type guards):**
+ * ```typescript
+ * import { isThumbnailOutput } from './type-guards';
+ *
+ * if (isThumbnailOutput(output)) {
+ *   // ✅ Type guard narrows output.data to ThumbnailOutput
+ *   console.log(output.data.width);
+ * }
+ * ```
+ *
+ * **Untyped nodes (backward compatible):**
+ * ```typescript
+ * const untypedOutput: TypedOutput = {
+ *   nodeId: "custom-node-1",
+ *   data: { custom: "data" },
+ *   timestamp: "2024-01-15T10:30:00Z"
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Storage output result (built-in, automatic narrowing)
+ * const output: TypedOutput = {
+ *   nodeId: "storage-1",
+ *   nodeType: "storage-output-v1",
+ *   data: {
+ *     id: "file-123",
+ *     url: "https://cdn.example.com/file.jpg",
+ *     size: 1024000,
+ *     // ... rest of UploadFile
+ *   },
+ *   timestamp: "2024-01-15T10:30:00Z"
+ * };
+ *
+ * // Custom output (requires type guard)
+ * const thumbnailOutput: TypedOutput<ThumbnailOutput> = {
+ *   nodeId: "thumbnail-1",
+ *   nodeType: "thumbnail-output-v1",
+ *   data: {
+ *     url: "https://cdn.example.com/thumb.jpg",
+ *     width: 200,
+ *     height: 200,
+ *     format: "webp",
+ *   },
+ *   timestamp: "2024-01-15T10:30:00Z"
+ * };
+ * ```
+ */
+type TypedOutput<T = unknown> = BuiltInTypedOutput | CustomTypedOutput<T>;
+/**
+ * Helper type to extract a specific built-in output by nodeType.
+ *
+ * This enables type-safe narrowing when you know the nodeType:
+ * ```typescript
+ * if (output.nodeType === "storage-output-v1") {
+ *   const narrowed = output as NarrowTypedOutput<"storage-output-v1">;
+ *   narrowed.data.url; // ✅ TypeScript knows data is UploadFile
+ * }
+ * ```
+ */
+type NarrowTypedOutput<NodeType extends BuiltInNodeType> = Extract<BuiltInTypedOutput, {
+  nodeType: NodeType;
+}>;
+/**
+ * Type guard function signature for narrowing TypedOutput.
+ *
+ * @template NodeType - The built-in node type to narrow to
+ */
+type TypedOutputGuard<NodeType extends BuiltInNodeType> = (output: TypedOutput) => output is NarrowTypedOutput<NodeType>;
+/**
+ * Creates a type-safe type guard for a built-in node type.
+ *
+ * @example
+ * ```typescript
+ * const isStorageV1 = createOutputGuard("storage-output-v1");
+ *
+ * for (const output of outputs) {
+ *   if (isStorageV1(output)) {
+ *     output.data.url; // ✅ TypeScript knows data is UploadFile
+ *   }
+ * }
+ * ```
+ */
+declare const createOutputGuard: <NodeType extends BuiltInNodeType>(nodeType: NodeType) => TypedOutputGuard<NodeType>;
+/**
+ * Pre-built type guard for storage-output-v1.
+ */
+declare const isStorageOutputV1: TypedOutputGuard<"storage-output-v1">;
+/**
+ * Pre-built type guard for streaming-input-v1.
+ */
+declare const isStreamingInputV1: TypedOutputGuard<"streaming-input-v1">;
+/**
+ * Result of a node execution - either complete or waiting for more data.
+ *
+ * @template TOutput - Type of the node's output data
+ *
+ * @remarks
+ * Nodes can return "waiting" to pause flow execution when they need additional
+ * data (e.g., chunked uploads, external service responses). The flow can be
+ * resumed later with the missing data.
+ *
+ * Results now include optional type information (`nodeType` and `nodeId`) to
+ * enable type-safe result consumption. These fields are automatically added
+ * by the node execution wrapper when a node is created with an `outputTypeId`.
+ *
+ * @example
+ * ```typescript
+ * // Node completes immediately with type information
+ * return completeNodeExecution({ processedData });
+ * // Result will be wrapped with: { type: "complete", data, nodeType, nodeId }
+ *
+ * // Node waits for more chunks
+ * if (needsMoreData) {
+ *   return waitingNodeExecution({ receivedChunks: 3, totalChunks: 10 });
+ * }
+ * ```
+ */
+type NodeExecutionResult<TOutput> = {
+  type: "complete";
+  data: TOutput;
+  nodeType?: string;
+  nodeId?: string;
+} | {
+  type: "waiting";
+  partialData?: unknown;
+  nodeType?: string;
+  nodeId?: string;
+};
+/**
+ * Helper function to create a complete node execution result.
+ *
+ * @template TOutput - Type of the output data
+ * @param data - The output data from the node
+ * @returns A complete execution result
+ *
+ * @example
+ * ```typescript
+ * return completeNodeExecution({
+ *   url: uploadedFile.url,
+ *   size: uploadedFile.size
+ * });
+ * ```
+ */
+declare const completeNodeExecution: <TOutput>(data: TOutput) => {
+  type: "complete";
+  data: TOutput;
+};
+/**
+ * Helper function to create a waiting node execution result.
+ *
+ * @param partialData - Optional partial data available so far
+ * @returns A waiting execution result that pauses the flow
+ *
+ * @example
+ * ```typescript
+ * // Wait for more upload chunks
+ * return waitingNodeExecution({
+ *   receivedBytes: currentSize,
+ *   totalBytes: expectedSize
+ * });
+ * ```
+ */
+declare const waitingNodeExecution: (partialData?: unknown) => {
+  type: "waiting";
+  partialData: unknown;
+};
+/**
+ * A flow node represents a single processing step in the DAG.
+ *
+ * Nodes are the building blocks of flows. Each node has typed inputs/outputs,
+ * execution logic, and optional features like conditions, retries, and pausing.
+ *
+ * @template TInput - Type of data the node accepts
+ * @template TOutput - Type of data the node produces
+ * @template TError - Type of errors the node can throw
+ *
+ * @property inputSchema - Zod schema for validating input data
+ * @property outputSchema - Zod schema for validating output data
+ * @property run - Effect-based execution function
+ * @property condition - Optional conditional execution rule
+ * @property multiInput - Whether node accepts multiple inputs (default: false)
+ * @property multiOutput - Whether node produces multiple outputs (default: false)
+ * @property pausable - Whether node can pause execution (default: false)
+ * @property retry - Optional retry configuration
+ *
+ * @remarks
+ * - Nodes use Effect for composable error handling and dependency injection
+ * - Input/output schemas ensure type safety at runtime
+ * - Conditions are evaluated before execution
+ * - Retry logic supports exponential backoff
+ * - Pausable nodes can halt flow execution and resume later
+ *
+ * @example
+ * ```typescript
+ * const resizeNode: FlowNode<InputFile, UploadFile> = {
+ *   id: "resize",
+ *   name: "Resize Image",
+ *   description: "Resize image to specified dimensions",
+ *   type: NodeType.transform,
+ *   inputSchema: inputFileSchema,
+ *   outputSchema: uploadFileSchema,
+ *   run: ({ data, storageId }) => Effect.gen(function* () {
+ *     const resized = yield* resizeImage(data, { width: 1920, height: 1080 });
+ *     return completeNodeExecution(resized);
+ *   }),
+ *   retry: {
+ *     maxRetries: 3,
+ *     retryDelay: 1000,
+ *     exponentialBackoff: true
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link NodeExecutionResult} for return type options
+ * @see {@link FlowCondition} for conditional execution
+ */
+type FlowNode<TInput = unknown, TOutput = unknown, TError = UploadistaError> = FlowNodeData & {
+  inputSchema: z.ZodSchema<TInput>;
+  outputSchema: z.ZodSchema<TOutput>;
+  run: (args: {
+    data: TInput;
+    jobId: string;
+    storageId: string;
+    flowId: string;
+    inputs?: Record<string, unknown>;
+    clientId: string | null;
+  }) => Effect.Effect<NodeExecutionResult<TOutput>, TError>;
+  condition?: {
+    field: string;
+    operator: string;
+    value: unknown;
+  };
+  multiInput?: boolean;
+  multiOutput?: boolean;
+  pausable?: boolean;
+  retry?: {
+    maxRetries?: number;
+    retryDelay?: number;
+    exponentialBackoff?: boolean;
+  }; /** Circuit breaker configuration for this node (overrides flow defaults) */
+  circuitBreaker?: FlowCircuitBreakerConfig;
+};
+/**
+ * Represents a directed edge connecting two nodes in the flow graph.
+ *
+ * Edges define the data flow direction and can specify ports for multi-input/output nodes.
+ *
+ * @property source - ID of the source node
+ * @property target - ID of the target node
+ * @property sourcePort - Optional output port name for multi-output nodes
+ * @property targetPort - Optional input port name for multi-input nodes
+ *
+ * @remarks
+ * - Edges must not create cycles (DAG constraint)
+ * - Source node's output type should be compatible with target node's input type
+ * - Ports allow routing specific outputs to specific inputs
+ *
+ * @example
+ * ```typescript
+ * // Simple edge
+ * const edge: FlowEdge = {
+ *   source: "resize-node",
+ *   target: "optimize-node"
+ * };
+ *
+ * // Edge with ports (for multiplex nodes)
+ * const multiplexEdge: FlowEdge = {
+ *   source: "multiplex-node",
+ *   target: "output-node",
+ *   sourcePort: "image",
+ *   targetPort: "primary"
+ * };
+ * ```
+ */
+type FlowEdge = {
+  source: string;
+  target: string;
+  sourcePort?: string;
+  targetPort?: string;
+};
+/**
+ * Function type for checking schema compatibility between nodes.
+ *
+ * @param from - Source node's output schema
+ * @param to - Target node's input schema
+ * @returns true if schemas are compatible
+ *
+ * @remarks
+ * Custom type checkers can implement more sophisticated compatibility rules
+ * than the default checker.
+ *
+ * @see {@link FlowTypeValidator} for the default implementation
+ */
+type TypeCompatibilityChecker = (from: z.ZodSchema<any>, to: z.ZodSchema<any>) => boolean;
+/**
+ * Interface for validating node connections and schema compatibility.
+ *
+ * @remarks
+ * Validators ensure that connected nodes have compatible types,
+ * preventing runtime type errors in flow execution.
+ *
+ * @see {@link FlowTypeValidator} for the implementation
+ */
+type NodeConnectionValidator = {
+  validateConnection: (sourceNode: FlowNode<any, any>, targetNode: FlowNode<any, any>, edge: FlowEdge) => boolean;
+  getCompatibleTypes: (sourceSchema: z.ZodSchema<any>, targetSchema: z.ZodSchema<any>) => boolean;
+};
+/**
+ * Fallback behavior when circuit is open.
+ *
+ * - `fail`: Fail immediately with CIRCUIT_BREAKER_OPEN error (default)
+ * - `skip`: Skip node, pass input through as output
+ * - `default`: Return a configured default value
+ */
+type FlowCircuitBreakerFallback = {
+  type: "fail";
+} | {
+  type: "skip";
+  passThrough: true;
+} | {
+  type: "default";
+  value: unknown;
+};
+/**
+ * Configuration for a circuit breaker on a flow or node.
+ *
+ * @property enabled - Whether circuit breaker is active (default: false for backward compatibility)
+ * @property failureThreshold - Number of failures within window to trip circuit (default: 5)
+ * @property resetTimeout - Milliseconds to wait in open state before half-open (default: 30000)
+ * @property halfOpenRequests - Number of successful requests in half-open to close (default: 3)
+ * @property windowDuration - Sliding window duration in milliseconds (default: 60000)
+ * @property fallback - Behavior when circuit is open
+ *
+ * @example
+ * ```typescript
+ * const config: FlowCircuitBreakerConfig = {
+ *   enabled: true,
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ *   halfOpenRequests: 3,
+ *   windowDuration: 60000,
+ *   fallback: { type: "fail" }
+ * };
+ * ```
+ */
+interface FlowCircuitBreakerConfig {
+  /** Whether circuit breaker is active (default: false) */
+  enabled?: boolean;
+  /** Number of failures within window to trip circuit (default: 5) */
+  failureThreshold?: number;
+  /** Milliseconds to wait in open state before half-open (default: 30000) */
+  resetTimeout?: number;
+  /** Number of successful requests in half-open to close (default: 3) */
+  halfOpenRequests?: number;
+  /** Sliding window duration in milliseconds (default: 60000) */
+  windowDuration?: number;
+  /** Behavior when circuit is open */
+  fallback?: FlowCircuitBreakerFallback;
+}
+/**
+ * Configuration for Dead Letter Queue on a flow.
+ *
+ * When enabled, failed flow jobs are captured in the DLQ for later retry,
+ * debugging, or manual intervention.
+ *
+ * @property enabled - Whether DLQ is enabled for this flow (default: true when service is provided)
+ * @property retryPolicy - Retry policy configuration for automatic retries
+ *
+ * @example
+ * ```typescript
+ * // Enable DLQ with custom retry policy
+ * const flowConfig = {
+ *   flowId: "image-pipeline",
+ *   deadLetterQueue: {
+ *     enabled: true,
+ *     retryPolicy: {
+ *       enabled: true,
+ *       maxRetries: 5,
+ *       backoff: {
+ *         type: "exponential",
+ *         initialDelayMs: 1000,
+ *         maxDelayMs: 60000,
+ *         multiplier: 2,
+ *         jitter: true
+ *       },
+ *       nonRetryableErrors: ["VALIDATION_ERROR"]
+ *     }
+ *   }
+ * };
+ *
+ * // Disable DLQ for best-effort flows
+ * const bestEffortFlow = {
+ *   flowId: "analytics-pipeline",
+ *   deadLetterQueue: {
+ *     enabled: false
+ *   }
+ * };
+ * ```
+ */
+interface FlowDeadLetterQueueConfig {
+  /** Whether DLQ is enabled for this flow (default: true when service is provided) */
+  enabled?: boolean;
+  /** Retry policy configuration for automatic retries */
+  retryPolicy?: RetryPolicy;
+}
+/**
+ * Configuration object for creating a new flow.
+ *
+ * FlowConfig defines all aspects of a flow including its nodes, connections,
+ * schemas, and optional features like event handlers and parallel execution.
+ *
+ * @template TFlowInputSchema - Zod schema for flow inputs
+ * @template TFlowOutputSchema - Zod schema for flow outputs
+ * @template TNodeError - Union of possible errors from node Effects
+ * @template TNodeRequirements - Union of requirements from node Effects
+ *
+ * @property flowId - Unique identifier for the flow
+ * @property name - Human-readable flow name
+ * @property nodes - Array of nodes (can be plain nodes or Effects resolving to nodes)
+ * @property edges - Array of edges connecting the nodes
+ * @property inputSchema - Zod schema for validating flow inputs
+ * @property outputSchema - Zod schema for validating flow outputs
+ * @property typeChecker - Optional custom type compatibility checker
+ * @property onEvent - Optional event handler for monitoring execution
+ * @property parallelExecution - Optional parallel execution configuration
+ *
+ * @remarks
+ * - Nodes can be provided as plain objects or Effect-wrapped for lazy initialization
+ * - Event handlers receive all flow and node events
+ * - Parallel execution is experimental and disabled by default
+ * - Type checker allows custom schema compatibility rules
+ *
+ * @example
+ * ```typescript
+ * const config: FlowConfig<
+ *   z.ZodObject<{ file: z.ZodType<File> }>,
+ *   z.ZodType<UploadFile>,
+ *   never,
+ *   never
+ * > = {
+ *   flowId: "image-upload",
+ *   name: "Image Upload Pipeline",
+ *   nodes: [inputNode, resizeNode, optimizeNode, storageNode],
+ *   edges: [
+ *     { source: "input", target: "resize" },
+ *     { source: "resize", target: "optimize" },
+ *     { source: "optimize", target: "storage" }
+ *   ],
+ *   inputSchema: z.object({ file: z.instanceof(File) }),
+ *   outputSchema: uploadFileSchema,
+ *   onEvent: (event) => Effect.gen(function* () {
+ *     yield* logEvent(event);
+ *     return { eventId: event.jobId };
+ *   })
+ * };
+ * ```
+ *
+ * @see {@link createFlowWithSchema} for creating flows from config
+ * @see {@link FlowNode} for node specifications
+ * @see {@link FlowEdge} for edge specifications
+ */
+type FlowConfig<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TNodeError = never, TNodeRequirements = never> = {
+  flowId: string;
+  name: string;
+  nodes: Array<FlowNode<any, any, UploadistaError> | Effect.Effect<FlowNode<any, any, UploadistaError>, TNodeError, TNodeRequirements>>;
+  edges: FlowEdge[];
+  inputSchema: TFlowInputSchema;
+  outputSchema: TFlowOutputSchema;
+  typeChecker?: TypeCompatibilityChecker;
+  onEvent?: (event: FlowEvent) => Effect.Effect<{
+    eventId: string | null;
+  }, UploadistaError>;
+  checkJobStatus?: (jobId: string) => Effect.Effect<"running" | "paused" | "cancelled", UploadistaError>;
+  parallelExecution?: {
+    enabled?: boolean;
+    maxConcurrency?: number;
+  };
+  /**
+   * Circuit breaker configuration for the flow.
+   *
+   * When enabled, the circuit breaker monitors node execution failures and
+   * automatically prevents requests to failing services, protecting against
+   * cascade failures.
+   *
+   * @example
+   * ```typescript
+   * circuitBreaker: {
+   *   defaults: {
+   *     enabled: true,
+   *     failureThreshold: 5,
+   *     resetTimeout: 30000
+   *   },
+   *   nodeTypeOverrides: {
+   *     "virus-scan": { failureThreshold: 3 }
+   *   }
+   * }
+   * ```
+   */
+  circuitBreaker?: {
+    /** Default circuit breaker config for all nodes */defaults?: FlowCircuitBreakerConfig; /** Override circuit breaker config per node type */
+    nodeTypeOverrides?: Record<string, FlowCircuitBreakerConfig>;
+  };
+  /**
+   * Dead Letter Queue configuration for the flow.
+   *
+   * When enabled, failed jobs are captured in the DLQ for later retry,
+   * debugging, or manual intervention.
+   *
+   * @example
+   * ```typescript
+   * deadLetterQueue: {
+   *   enabled: true,
+   *   retryPolicy: {
+   *     enabled: true,
+   *     maxRetries: 5,
+   *     backoff: {
+   *       type: "exponential",
+   *       initialDelayMs: 1000,
+   *       maxDelayMs: 60000,
+   *       multiplier: 2,
+   *       jitter: true
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  deadLetterQueue?: FlowDeadLetterQueueConfig;
+  hooks?: {
+    /**
+     * Called when a sink node (terminal node with no outgoing edges) produces an output.
+     * This hook runs after auto-persistence for UploadFile outputs.
+     *
+     * Use this hook to perform additional post-processing such as:
+     * - Saving output metadata to a database
+     * - Tracking outputs in external systems
+     * - Adding custom metadata to outputs
+     * - Triggering downstream workflows
+     *
+     * The hook receives the output and context, and can optionally modify
+     * and return the output (e.g., adding metadata fields).
+     *
+     * **Important**: The hook must not have any service requirements (Effect requirements must be `never`).
+     * All necessary services should be captured in the closure when defining the hook.
+     *
+     * @param context - Output context including the output data, node ID, flow ID, etc.
+     * @returns Effect or Promise that resolves to the (optionally modified) output
+     *
+     * @example
+     * ```typescript
+     * // Using Effect
+     * hooks: {
+     *   onNodeOutput: ({ output, nodeId, flowId }) =>
+     *     Effect.gen(function* () {
+     *       // Save to database
+     *       yield* Effect.promise(() => db.save(output));
+     *       // Return output with additional metadata
+     *       return { ...output, metadata: { ...output.metadata, tracked: true } };
+     *     })
+     * }
+     *
+     * // Using Promise (simpler for most users)
+     * hooks: {
+     *   onNodeOutput: async ({ output, nodeId, flowId }) => {
+     *     // Save to database
+     *     await db.save(output);
+     *     // Return output with additional metadata
+     *     return { ...output, metadata: { ...output.metadata, tracked: true } };
+     *   }
+     * }
+     * ```
+     */
+    onNodeOutput?: <TOutput>(context: {
+      output: TOutput;
+      nodeId: string;
+      flowId: string;
+      jobId: string;
+      storageId: string;
+      clientId: string | null;
+    }) => Effect.Effect<TOutput, UploadistaError, never> | Promise<TOutput>;
+  };
+};
+/**
+ * Context provided to file naming functions and templates.
+ *
+ * Contains all relevant information about the current file, node, and flow
+ * execution that can be used to generate dynamic file names.
+ *
+ * @property baseName - Filename without extension (e.g., "photo" from "photo.jpg")
+ * @property extension - File extension without dot (e.g., "jpg")
+ * @property fileName - Full original filename (e.g., "photo.jpg")
+ * @property nodeType - Type of processing node (e.g., "resize", "optimize")
+ * @property nodeId - Specific node instance ID
+ * @property flowId - Flow identifier
+ * @property jobId - Execution job ID
+ * @property timestamp - ISO 8601 timestamp of processing
+ * @property width - Output width (image/video nodes only)
+ * @property height - Output height (image/video nodes only)
+ * @property format - Output format (e.g., "webp", "mp4")
+ * @property quality - Quality setting (e.g., 80)
+ *
+ * @example
+ * ```typescript
+ * // Available in templates as {{variable}}
+ * const pattern = "{{baseName}}-{{width}}x{{height}}.{{extension}}";
+ * // Result: "photo-800x600.jpg"
+ * ```
+ */
+type NamingContext = {
+  /** Filename without extension */baseName: string; /** File extension without dot */
+  extension: string; /** Full original filename */
+  fileName: string; /** Type of processing node */
+  nodeType: string; /** Specific node instance ID */
+  nodeId: string; /** Flow identifier */
+  flowId: string; /** Execution job ID */
+  jobId: string; /** ISO 8601 timestamp of processing */
+  timestamp: string; /** Output width (image/video nodes) */
+  width?: number; /** Output height (image/video nodes) */
+  height?: number; /** Output format */
+  format?: string; /** Quality setting */
+  quality?: number; /** Page number (document nodes) */
+  pageNumber?: number; /** Additional custom variables */
+  [key: string]: string | number | undefined;
+};
+/**
+ * Function type for custom file naming logic.
+ *
+ * @param file - The UploadFile being processed
+ * @param context - Naming context with all available variables
+ * @returns The new filename (including extension)
+ *
+ * @example
+ * ```typescript
+ * const customRename: FileNamingFunction = (file, ctx) =>
+ *   `${ctx.flowId}-${ctx.baseName}-${ctx.timestamp}.${ctx.extension}`;
+ * ```
+ */
+type FileNamingFunction = (file: UploadFile, context: NamingContext) => string;
+/**
+ * Function type for generating auto-naming suffixes.
+ *
+ * Each node type can define its own auto suffix generator that creates
+ * a descriptive suffix based on the processing parameters.
+ *
+ * @param context - Naming context with all available variables
+ * @returns The suffix to append (without leading dash)
+ *
+ * @example
+ * ```typescript
+ * // Resize node auto suffix
+ * const resizeAutoSuffix: AutoNamingSuffixGenerator = (ctx) =>
+ *   `${ctx.width}x${ctx.height}`;
+ * // Result: "photo-800x600.jpg"
+ *
+ * // Optimize node auto suffix
+ * const optimizeAutoSuffix: AutoNamingSuffixGenerator = (ctx) =>
+ *   ctx.format ?? 'optimized';
+ * // Result: "photo-webp.webp"
+ * ```
+ */
+type AutoNamingSuffixGenerator = (context: NamingContext) => string;
+/**
+ * Configuration for file naming behavior on a node.
+ *
+ * Supports three modes:
+ * - `undefined` or no config: Preserve original filename (backward compatible)
+ * - `mode: 'auto'`: Generate smart suffix based on node type
+ * - `mode: 'custom'`: Use template pattern or rename function
+ *
+ * @property mode - Naming mode: 'auto' for smart suffixes, 'custom' for templates/functions
+ * @property pattern - Mustache-style template string (for custom mode)
+ * @property rename - Custom function for full control (for custom mode, SDK only)
+ * @property autoSuffix - Generator function for auto mode suffix
+ *
+ * @example
+ * ```typescript
+ * // Auto mode with smart suffix
+ * const autoNaming: FileNamingConfig = {
+ *   mode: 'auto',
+ *   autoSuffix: (ctx) => `${ctx.width}x${ctx.height}`
+ * };
+ *
+ * // Custom mode with template
+ * const templateNaming: FileNamingConfig = {
+ *   mode: 'custom',
+ *   pattern: '{{baseName}}-{{nodeType}}.{{extension}}'
+ * };
+ *
+ * // Custom mode with function
+ * const functionNaming: FileNamingConfig = {
+ *   mode: 'custom',
+ *   rename: (file, ctx) => `processed-${ctx.fileName}`
+ * };
+ * ```
+ */
+type FileNamingConfig = {
+  /** Naming mode: 'auto' for smart suffixes, 'custom' for templates/functions */mode: "auto" | "custom"; /** Mustache-style template string (for custom mode) */
+  pattern?: string; /** Custom function for full control (for custom mode, SDK only) */
+  rename?: FileNamingFunction; /** Generator function for auto mode suffix */
+  autoSuffix?: AutoNamingSuffixGenerator;
+};
+//#endregion
+//#region src/flow/types/flow-job.d.ts
+/**
+ * Status of an individual node within a flow job.
+ *
+ * Node tasks follow this lifecycle:
+ * started → pending → running → (completed | paused | failed)
+ */
+type FlowJobTaskStatus = "started" | "pending" | "running" | "completed" | "paused" | "failed";
+/**
+ * Represents a single node's execution within a flow job.
+ *
+ * Tasks track individual node execution, storing results, errors, and retry information.
+ * They allow monitoring of which nodes have completed and accessing intermediate results.
+ *
+ * @property nodeId - Unique identifier of the node this task represents
+ * @property status - Current execution status of the node
+ * @property result - Node execution result data (can be partial data if paused, or complete data if finished)
+ * @property error - Error message if the node failed
+ * @property retryCount - Number of retry attempts made before success or final failure
+ * @property createdAt - When the task was created
+ * @property updatedAt - When the task was last updated
+ *
+ * @remarks
+ * The result field can contain:
+ * - Partial/intermediate data when status is "paused" (unknown type)
+ * - Complete data when status is "completed" (could be TypedOutput for output nodes)
+ * - undefined when status is "pending", "running", "started", or "failed"
+ *
+ * For type-safe access to final outputs, use FlowJob.result instead, which contains
+ * the array of TypedOutput from all output nodes.
+ */
+type FlowJobTask = {
+  nodeId: string;
+  status: FlowJobTaskStatus;
+  result?: unknown;
+  error?: string;
+  retryCount?: number;
+  createdAt: Date;
+  updatedAt: Date;
+};
+/**
+ * Represents a flow execution job with full state tracking.
+ *
+ * Jobs are created when a flow is executed and track the entire execution lifecycle.
+ * They store node results, handle paused states, and manage cleanup of intermediate files.
+ *
+ * @property id - Unique job identifier (UUID)
+ * @property flowId - The flow being executed
+ * @property storageId - Storage location for file outputs
+ * @property clientId - Client that initiated the job (for authorization)
+ * @property status - Overall job status
+ * @property createdAt - When the job was created
+ * @property updatedAt - When the job was last updated
+ * @property tasks - Array of node execution tasks
+ * @property error - Error message if the job failed
+ * @property endedAt - When the job completed or failed
+ * @property result - Array of typed outputs from all output nodes (only set when completed)
+ * @property pausedAt - Node ID where execution is paused (if applicable)
+ * @property executionState - State needed to resume a paused flow
+ * @property intermediateFiles - File IDs to cleanup after completion
+ *
+ * @remarks
+ * - Jobs can be paused at nodes that return `{ type: "waiting" }`
+ * - Paused jobs store execution state and can be resumed with new data
+ * - Intermediate files from non-output nodes are automatically cleaned up
+ * - Tasks are updated as nodes progress through their lifecycle
+ * - The result field now contains an array of TypedOutput for all output nodes
+ *
+ * @example
+ * ```typescript
+ * // Create and monitor a job
+ * const job = yield* flowServer.runFlow({
+ *   flowId: "image-pipeline",
+ *   storageId: "storage-1",
+ *   inputs: { input: myFile }
+ * });
+ *
+ * // Poll for status
+ * const status = yield* flowServer.getJobStatus(job.id);
+ * if (status.status === "completed") {
+ *   // Access typed outputs
+ *   console.log("Outputs:", status.result);
+ *   for (const output of status.result || []) {
+ *     console.log(`${output.nodeId} (${output.nodeType}):`, output.data);
+ *   }
+ * } else if (status.status === "paused") {
+ *   // Resume with additional data
+ *   yield* flowServer.resumeFlow({
+ *     jobId: job.id,
+ *     nodeId: status.pausedAt,
+ *     newData: additionalChunk
+ *   });
+ * }
+ * ```
+ */
+/**
+ * Trace context for distributed tracing.
+ * Allows flow operations to be linked under a single trace.
+ */
+type FlowJobTraceContext = {
+  /** 128-bit trace identifier (32 hex characters) */traceId: string; /** 64-bit span identifier (16 hex characters) */
+  spanId: string; /** Trace flags (1 = sampled) */
+  traceFlags: number;
+};
+type FlowJob = {
+  id: string;
+  flowId: string;
+  storageId: string;
+  clientId: string | null;
+  status: FlowJobStatus;
+  createdAt: Date;
+  updatedAt: Date;
+  tasks: FlowJobTask[];
+  error?: string;
+  endedAt?: Date;
+  result?: TypedOutput[];
+  pausedAt?: string;
+  executionState?: {
+    executionOrder: string[];
+    currentIndex: number;
+    inputs: Record<string, unknown>;
+  };
+  intermediateFiles?: string[];
+  /**
+   * Active upload IDs for in-progress multipart uploads.
+   * These are tracked separately from intermediateFiles because they may not
+   * be complete yet. When a flow is cancelled during upload phase, these
+   * uploads need to be aborted to clean up the multipart upload in storage.
+   */
+  activeUploads?: string[];
+  /**
+   * OpenTelemetry trace context for distributed tracing.
+   * When set, all flow operations (node executions, uploads) will be
+   * linked as children of this trace context. Enables end-to-end tracing
+   * of flow executions in observability tools like Grafana Tempo.
+   */
+  traceContext?: FlowJobTraceContext;
+};
+/**
+ * Overall status of a flow job.
+ *
+ * Job lifecycle: started → running → (completed | failed | cancelled)
+ * Or with pauses: started → running → paused → running → (completed | failed | cancelled)
+ * User actions: running → paused (via pauseFlow) or running → cancelled (via cancelFlow)
+ */
+type FlowJobStatus = "pending" | "running" | "completed" | "failed" | "started" | "paused" | "cancelled";
+//#endregion
+//#region src/flow/types/flow-queue-item.d.ts
+/**
+ * Flow Queue item types and configuration.
+ *
+ * A FlowQueueItem represents a queued flow execution request, tracking its
+ * lifecycle from pending → running → completed | failed.
+ *
+ * @module flow/types/flow-queue-item
+ * @see {@link FlowQueueService} for queue operations
+ */
+/**
+ * Status of a flow queue item.
+ *
+ * Item lifecycle: pending → running → completed | failed
+ *
+ * - `pending`: Waiting for a concurrency slot to become available
+ * - `running`: Currently being executed by the flow engine
+ * - `completed`: Flow execution finished successfully
+ * - `failed`: Flow execution ended with an error
+ */
+type FlowQueueItemStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Represents a single queued flow execution request.
+ *
+ * FlowQueueItems are created when a caller enqueues a flow for execution.
+ * The worker loop picks up pending items, transitions them to running, and
+ * dispatches them to FlowEngine. On completion or failure the item is updated.
+ *
+ * @property id - Unique queue item identifier (UUID)
+ * @property flowId - The flow definition to execute
+ * @property storageId - Target storage for flow outputs
+ * @property input - Original input payload passed to the flow
+ * @property clientId - Client who initiated the request (null for anonymous)
+ * @property status - Current lifecycle status of the queue item
+ * @property dlqItemId - Set when this item is a DLQ retry; links back to the DLQ item
+ * @property enqueuedAt - When the item was added to the queue
+ * @property startedAt - When the worker started executing this item
+ * @property completedAt - When execution finished (success or failure)
+ * @property error - Error message recorded if status is "failed"
+ *
+ * @example
+ * ```typescript
+ * const item: FlowQueueItem = {
+ *   id: "q_abc123",
+ *   flowId: "image-resize-pipeline",
+ *   storageId: "s3-production",
+ *   input: { input: { uploadId: "upload_xyz" } },
+ *   clientId: "client_456",
+ *   status: "pending",
+ *   enqueuedAt: new Date(),
+ * };
+ * ```
+ */
+interface FlowQueueItem {
+  /** Unique queue item identifier (UUID) */
+  id: string;
+  /** The flow definition to execute */
+  flowId: string;
+  /** Target storage for flow outputs */
+  storageId: string;
+  /** Original input payload passed to the flow */
+  input: unknown;
+  /** Client who initiated the request (null for anonymous) */
+  clientId: string | null;
+  /** Current lifecycle status */
+  status: FlowQueueItemStatus;
+  /** Set when this is a DLQ retry; references the DLQ item for result correlation */
+  dlqItemId?: string;
+  /** When the item was added to the queue */
+  enqueuedAt: Date;
+  /** When the worker began executing this item */
+  startedAt?: Date;
+  /** When execution finished (success or failure) */
+  completedAt?: Date;
+  /** Error message if status is "failed" */
+  error?: string;
+}
+/**
+ * Aggregate statistics about the flow queue.
+ *
+ * Provides counts by status and concurrency information for monitoring.
+ *
+ * @property pending - Number of items waiting for a concurrency slot
+ * @property running - Number of items currently being executed
+ * @property completed - Number of items that finished successfully
+ * @property failed - Number of items that ended with an error
+ * @property maxConcurrency - Configured maximum simultaneous executions
+ * @property currentConcurrency - Number of items currently running
+ */
+interface FlowQueueStats {
+  /** Number of items waiting for a concurrency slot */
+  pending: number;
+  /** Number of items currently being executed */
+  running: number;
+  /** Number of items that finished successfully */
+  completed: number;
+  /** Number of items that ended with an error */
+  failed: number;
+  /** Configured maximum simultaneous executions */
+  maxConcurrency: number;
+  /** Number of items currently running */
+  currentConcurrency: number;
+}
+/**
+ * Configuration options for the FlowQueueService.
+ *
+ * All fields are optional; defaults are applied via DEFAULT_QUEUE_CONFIG.
+ *
+ * @property maxConcurrency - Maximum number of simultaneously running flows (default: 4)
+ * @property dlqRetryIntervalMs - How often the DLQ retry loop fires in milliseconds (default: 30_000)
+ * @property dlqRetryBatchSize - Maximum DLQ items processed per retry loop tick (default: 10)
+ *
+ * @example
+ * ```typescript
+ * const config: FlowQueueConfig = {
+ *   maxConcurrency: 8,
+ *   dlqRetryIntervalMs: 60_000, // check every 60 seconds
+ *   dlqRetryBatchSize: 5,
+ * };
+ * ```
+ */
+interface FlowQueueConfig {
+  /**
+   * Maximum number of simultaneously running flows.
+   * Flows beyond this limit remain pending until a slot opens.
+   * @default 4
+   */
+  maxConcurrency?: number;
+  /**
+   * Interval in milliseconds between DLQ retry loop ticks.
+   * Only relevant when DeadLetterQueueService is present.
+   * @default 30_000
+   */
+  dlqRetryIntervalMs?: number;
+  /**
+   * Maximum number of DLQ items to re-enqueue per retry loop tick.
+   * @default 10
+   */
+  dlqRetryBatchSize?: number;
+}
+/**
+ * Default configuration values for FlowQueueService.
+ *
+ * Applied when specific config fields are omitted.
+ */
+declare const DEFAULT_QUEUE_CONFIG: Required<FlowQueueConfig>;
+//#endregion
+//#region src/types/kv-store.d.ts
+/**
+ * Base key-value store interface for raw string storage.
+ *
+ * This is the low-level interface that storage adapters implement.
+ * It stores raw string values without type safety or serialization.
+ *
+ * @property get - Retrieves a value by key, returns null if not found
+ * @property set - Stores a value with the given key
+ * @property delete - Removes a value by key
+ * @property list - Optional operation to list all keys with a given prefix
+ *
+ * @example
+ * ```typescript
+ * // Implement a BaseKvStore with Redis
+ * const redisKvStore: BaseKvStore = {
+ *   get: (key) => Effect.tryPromise({
+ *     try: () => redis.get(key),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   set: (key, value) => Effect.tryPromise({
+ *     try: () => redis.set(key, value),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   delete: (key) => Effect.tryPromise({
+ *     try: () => redis.del(key),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   list: (prefix) => Effect.tryPromise({
+ *     try: () => redis.keys(`${prefix}*`),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   })
+ * };
+ * ```
+ */
+interface BaseKvStore {
+  readonly get: (key: string) => Effect.Effect<string | null, UploadistaError>;
+  readonly set: (key: string, value: string) => Effect.Effect<void, UploadistaError>;
+  readonly delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly list?: (keyPrefix: string) => Effect.Effect<Array<string>, UploadistaError>;
+}
+/**
+ * Type-safe key-value store interface with automatic serialization.
+ *
+ * This wraps a BaseKvStore and handles JSON serialization/deserialization
+ * for a specific data type, providing type safety and eliminating the need
+ * for manual JSON.stringify/parse calls.
+ *
+ * @template TData - The type of data stored in this KV store
+ *
+ * @property get - Retrieves and deserializes a value, fails if not found
+ * @property set - Serializes and stores a value
+ * @property delete - Removes a value by key
+ * @property list - Optional operation to list all keys (without prefix)
+ *
+ * @example
+ * ```typescript
+ * // Use a typed KV store
+ * const uploadStore: KvStore<UploadFile> = new TypedKvStore(
+ *   baseStore,
+ *   "uploads:",
+ *   jsonSerializer.serialize,
+ *   jsonSerializer.deserialize
+ * );
+ *
+ * // Store and retrieve typed data
+ * const program = Effect.gen(function* () {
+ *   const file: UploadFile = {
+ *     id: "file123",
+ *     offset: 0,
+ *     storage: { id: "s3", type: "s3" }
+ *   };
+ *
+ *   // Automatic serialization
+ *   yield* uploadStore.set("file123", file);
+ *
+ *   // Automatic deserialization with type safety
+ *   const retrieved = yield* uploadStore.get("file123");
+ *   console.log(retrieved.offset); // TypeScript knows this is a number
+ * });
+ * ```
+ */
+type KvStore<TData> = {
+  readonly get: (key: string) => Effect.Effect<TData, UploadistaError>;
+  readonly set: (key: string, value: TData) => Effect.Effect<void, UploadistaError>;
+  readonly delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly list?: () => Effect.Effect<Array<string>, UploadistaError>;
+};
+/**
+ * Typed wrapper class that adds serialization to a BaseKvStore.
+ *
+ * This class implements the KvStore interface by wrapping a BaseKvStore
+ * and handling serialization/deserialization for a specific type. It also
+ * adds a key prefix to isolate different data types in the same store.
+ *
+ * @template TData - The type of data to store
+ *
+ * @example
+ * ```typescript
+ * // Create a typed store for UploadFile
+ * const uploadFileStore = new TypedKvStore<UploadFile>(
+ *   baseKvStore,
+ *   "uploadista:upload-file:", // All keys will be prefixed
+ *   (data) => JSON.stringify(data),
+ *   (str) => JSON.parse(str) as UploadFile
+ * );
+ *
+ * // Use the store
+ * const effect = Effect.gen(function* () {
+ *   const file: UploadFile = { ... };
+ *   yield* uploadFileStore.set("abc123", file);
+ *   // Internally stores at key "uploadista:upload-file:abc123"
+ *
+ *   const retrieved = yield* uploadFileStore.get("abc123");
+ *   return retrieved;
+ * });
+ *
+ * // Custom serialization for binary data
+ * const binaryStore = new TypedKvStore<Uint8Array>(
+ *   baseKvStore,
+ *   "binary:",
+ *   (data) => btoa(String.fromCharCode(...data)), // Base64 encode
+ *   (str) => Uint8Array.from(atob(str), c => c.charCodeAt(0)) // Base64 decode
+ * );
+ * ```
+ */
+declare class TypedKvStore<TData> implements KvStore<TData> {
+  private baseStore;
+  private keyPrefix;
+  private serialize;
+  private deserialize;
+  constructor(baseStore: BaseKvStore, keyPrefix: string, serialize: (data: TData) => string, deserialize: (str: string) => TData);
+  get: (key: string) => Effect.Effect<TData, UploadistaError>;
+  set: (key: string, value: TData) => Effect.Effect<void, UploadistaError>;
+  delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  list: () => Effect.Effect<Array<string>, UploadistaError>;
+}
+/**
+ * Default JSON serialization helpers.
+ *
+ * These functions provide standard JSON serialization for use with TypedKvStore.
+ * They work with any JSON-serializable type.
+ *
+ * @example
+ * ```typescript
+ * const store = new TypedKvStore<MyType>(
+ *   baseStore,
+ *   "mydata:",
+ *   jsonSerializer.serialize,
+ *   jsonSerializer.deserialize
+ * );
+ * ```
+ */
+declare const jsonSerializer: {
+  serialize: <T>(data: T) => string;
+  deserialize: <T>(str: string) => T;
+};
+declare const BaseKvStoreService_base: Context.TagClass<BaseKvStoreService, "BaseKvStore", BaseKvStore>;
+/**
+ * Effect-TS context tag for the base untyped KV store.
+ *
+ * This is the low-level store that storage adapter implementations provide.
+ * Most application code should use typed stores like UploadFileKVStore instead.
+ *
+ * @example
+ * ```typescript
+ * // Provide a base store implementation
+ * const baseStoreLayer = Layer.succeed(BaseKvStoreService, redisKvStore);
+ *
+ * // Use in an Effect
+ * const effect = Effect.gen(function* () {
+ *   const baseStore = yield* BaseKvStoreService;
+ *   yield* baseStore.set("raw-key", "raw-value");
+ * });
+ * ```
+ */
+declare class BaseKvStoreService extends BaseKvStoreService_base {}
+declare const UploadFileKVStore_base: Context.TagClass<UploadFileKVStore, "UploadFileKVStore", KvStore<UploadFile>>;
+/**
+ * Effect-TS context tag for the UploadFile typed KV store.
+ *
+ * This provides type-safe storage for UploadFile metadata. It's the primary
+ * way to store and retrieve upload metadata in the system.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *
+ *   // Store upload metadata
+ *   const file: UploadFile = {
+ *     id: "upload123",
+ *     offset: 0,
+ *     storage: { id: "s3", type: "s3" }
+ *   };
+ *   yield* kvStore.set("upload123", file);
+ *
+ *   // Retrieve with type safety
+ *   const retrieved = yield* kvStore.get("upload123");
+ *   return retrieved;
+ * });
+ * ```
+ */
+declare class UploadFileKVStore extends UploadFileKVStore_base {}
+/**
+ * Effect Layer that creates the UploadFileKVStore from a BaseKvStore.
+ *
+ * This layer automatically wires up JSON serialization for UploadFile objects
+ * with the "uploadista:upload-file:" key prefix.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *   // Use the store...
+ * }).pipe(
+ *   Effect.provide(uploadFileKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const uploadFileKvStore: Layer.Layer<UploadFileKVStore, never, BaseKvStoreService>;
+declare const FlowJobKVStore_base: Context.TagClass<FlowJobKVStore, "FlowJobKVStore", KvStore<FlowJob>>;
+/**
+ * Effect-TS context tag for the FlowJob typed KV store.
+ *
+ * This provides type-safe storage for FlowJob metadata, tracking the
+ * execution state of flow processing jobs.
+ *
+ * @example
+ * ```typescript
+ * const flowEffect = Effect.gen(function* () {
+ *   const jobStore = yield* FlowJobKVStore;
+ *
+ *   // Store job state
+ *   const job: FlowJob = {
+ *     id: "job123",
+ *     flowId: "flow_resize",
+ *     status: "running",
+ *     tasks: [],
+ *     createdAt: new Date(),
+ *     updatedAt: new Date()
+ *   };
+ *   yield* jobStore.set("job123", job);
+ *
+ *   // Retrieve and check status
+ *   const retrieved = yield* jobStore.get("job123");
+ *   return retrieved.status;
+ * });
+ * ```
+ */
+declare class FlowJobKVStore extends FlowJobKVStore_base {}
+/**
+ * Effect Layer that creates the FlowJobKVStore from a BaseKvStore.
+ *
+ * This layer automatically wires up JSON serialization for FlowJob objects
+ * with the "uploadista:flow-job:" key prefix.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const jobStore = yield* FlowJobKVStore;
+ *   // Use the store...
+ * }).pipe(
+ *   Effect.provide(flowJobKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const flowJobKvStore: Layer.Layer<FlowJobKVStore, never, BaseKvStoreService>;
+declare const DeadLetterQueueKVStore_base: Context.TagClass<DeadLetterQueueKVStore, "DeadLetterQueueKVStore", KvStore<DeadLetterItem>>;
+/**
+ * Effect-TS context tag for the Dead Letter Queue typed KV store.
+ *
+ * This provides type-safe storage for DeadLetterItem objects, tracking
+ * failed flow jobs for retry, debugging, and manual intervention.
+ *
+ * @example
+ * ```typescript
+ * const dlqEffect = Effect.gen(function* () {
+ *   const dlqStore = yield* DeadLetterQueueKVStore;
+ *
+ *   // Store a DLQ item
+ *   const item: DeadLetterItem = {
+ *     id: "dlq_123",
+ *     jobId: "job_456",
+ *     flowId: "image-pipeline",
+ *     storageId: "s3",
+ *     clientId: "client_789",
+ *     error: { code: "FLOW_NODE_ERROR", message: "Timeout" },
+ *     inputs: { input: { uploadId: "upload_abc" } },
+ *     nodeResults: {},
+ *     retryCount: 0,
+ *     maxRetries: 3,
+ *     retryHistory: [],
+ *     createdAt: new Date(),
+ *     updatedAt: new Date(),
+ *     status: "pending"
+ *   };
+ *   yield* dlqStore.set("dlq_123", item);
+ *
+ *   // Retrieve with type safety
+ *   const retrieved = yield* dlqStore.get("dlq_123");
+ *   return retrieved.status;
+ * });
+ * ```
+ */
+declare class DeadLetterQueueKVStore extends DeadLetterQueueKVStore_base {}
+/**
+ * Effect Layer that creates the DeadLetterQueueKVStore from a BaseKvStore.
+ *
+ * This layer automatically wires up JSON serialization for DeadLetterItem objects
+ * with the "uploadista:dlq:" key prefix.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const dlqStore = yield* DeadLetterQueueKVStore;
+ *   // Use the store...
+ * }).pipe(
+ *   Effect.provide(deadLetterQueueKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const deadLetterQueueKvStore: Layer.Layer<DeadLetterQueueKVStore, never, BaseKvStoreService>;
+declare const FlowQueueKVStore_base: Context.TagClass<FlowQueueKVStore, "FlowQueueKVStore", KvStore<FlowQueueItem>>;
+/**
+ * Effect-TS context tag for the FlowQueueItem typed KV store.
+ */
+declare class FlowQueueKVStore extends FlowQueueKVStore_base {}
+/**
+ * Effect Layer that creates the FlowQueueKVStore from a BaseKvStore.
+ *
+ * Stores queue items as JSON under the "uploadista:queue-item:" prefix.
+ * Used by FlowQueueService.fromKvStore() so the queue can be backed by
+ * any BaseKvStoreService (Redis, filesystem, Cloudflare KV, etc.).
+ */
+declare const flowQueueKvStore: Layer.Layer<FlowQueueKVStore, never, BaseKvStoreService>;
+//#endregion
+//#region src/types/data-store.d.ts
+/**
+ * Options for writing data to a DataStore.
+ *
+ * @property file_id - Unique identifier for the file being written
+ * @property stream - Stream of byte chunks to write to storage
+ * @property offset - Byte offset where writing should begin (for resumable uploads)
+ */
+type DataStoreWriteOptions = {
+  file_id: string;
+  stream: Stream.Stream<Uint8Array, UploadistaError>;
+  offset: number;
+};
+/**
+ * Upload strategy type indicating how chunks are uploaded.
+ *
+ * - `single`: Upload file in a single request (traditional upload)
+ * - `parallel`: Upload file chunks in parallel (for large files)
+ */
+type UploadStrategy = "single" | "parallel";
+/**
+ * Configuration options for streaming file reads.
+ *
+ * Used to control streaming behavior in transform nodes and data stores.
+ *
+ * @property fileSizeThreshold - Files below this size use buffered mode (default: 1MB)
+ * @property chunkSize - Chunk size for streaming reads in bytes (default: 64KB)
+ *
+ * @example
+ * ```typescript
+ * const config: StreamingConfig = {
+ *   fileSizeThreshold: 1_048_576, // 1MB - use buffered for smaller files
+ *   chunkSize: 65_536, // 64KB chunks
+ * };
+ * ```
+ */
+type StreamingConfig = {
+  /** Files below this size use buffered mode (default: 1MB = 1_048_576 bytes) */fileSizeThreshold?: number; /** Chunk size for streaming reads in bytes (default: 64KB = 65_536 bytes) */
+  chunkSize?: number;
+};
+/**
+ * Default streaming configuration values.
+ */
+declare const DEFAULT_STREAMING_CONFIG: Required<StreamingConfig>;
+/**
+ * Default multipart part size for S3/R2 streaming writes.
+ * S3 requires minimum 5MB parts (except for the last part).
+ */
+declare const DEFAULT_MULTIPART_PART_SIZE: number;
+/**
+ * Options for streaming write operations.
+ *
+ * Used when writing file content from a stream with unknown final size.
+ * The store will finalize the upload when the stream completes.
+ *
+ * @property stream - Effect Stream of byte chunks to write
+ * @property contentType - Optional MIME type for the file
+ * @property metadata - Optional metadata to store with the file
+ * @property sizeHint - Optional estimated size for optimization (e.g., multipart part sizing)
+ *
+ * @example
+ * ```typescript
+ * const options: StreamWriteOptions = {
+ *   stream: transformedStream,
+ *   contentType: "image/webp",
+ *   metadata: { originalName: "photo.jpg" },
+ *   sizeHint: 5_000_000, // ~5MB expected
+ * };
+ * ```
+ */
+type StreamWriteOptions = {
+  stream: Stream.Stream<Uint8Array, UploadistaError>;
+  contentType?: string;
+  metadata?: Record<string, string>; /** Optional size hint for optimization (not required) */
+  sizeHint?: number;
+};
+/**
+ * Result of a streaming write operation.
+ *
+ * Contains the final size after the stream completes, along with
+ * storage location information.
+ *
+ * @property id - Unique identifier of the written file
+ * @property size - Final size in bytes after stream completed
+ * @property path - Storage path or key where file was written
+ * @property bucket - Optional bucket/container name (for cloud storage)
+ *
+ * @example
+ * ```typescript
+ * const result = yield* dataStore.writeStream(fileId, options);
+ * console.log(`Wrote ${result.size} bytes to ${result.path}`);
+ * ```
+ */
+type StreamWriteResult = {
+  id: string;
+  size: number;
+  path: string;
+  bucket?: string; /** Public URL for accessing the uploaded file (if available) */
+  url?: string;
+};
+/**
+ * Capabilities and constraints of a DataStore implementation.
+ *
+ * This type describes what features a storage backend supports and what
+ * limitations it has. Use this to determine the optimal upload strategy
+ * and validate client requests.
+ *
+ * @property supportsParallelUploads - Can upload chunks in parallel (e.g., S3 multipart)
+ * @property supportsConcatenation - Can concatenate multiple uploads into one file
+ * @property supportsDeferredLength - Can start upload without knowing final size
+ * @property supportsResumableUploads - Can resume interrupted uploads from last offset
+ * @property supportsTransactionalUploads - Guarantees atomic upload success/failure
+ * @property supportsStreamingRead - Can read file content as a stream instead of buffering
+ * @property maxConcurrentUploads - Maximum parallel upload parts (if parallel supported)
+ * @property minChunkSize - Minimum size in bytes for each chunk (except last)
+ * @property maxChunkSize - Maximum size in bytes for each chunk
+ * @property maxParts - Maximum number of parts in a multipart upload
+ * @property optimalChunkSize - Recommended chunk size for best performance
+ * @property requiresOrderedChunks - Must receive chunks in sequential order
+ * @property requiresMimeTypeValidation - Validates file MIME type matches declaration
+ * @property maxValidationSize - Maximum file size for MIME type validation
+ *
+ * @example
+ * ```typescript
+ * const capabilities = dataStore.getCapabilities();
+ *
+ * if (capabilities.supportsParallelUploads && fileSize > 10_000_000) {
+ *   // Use parallel upload for large files
+ *   const chunkSize = capabilities.optimalChunkSize || 5_242_880; // 5MB default
+ *   uploadInParallel(file, chunkSize);
+ * } else {
+ *   // Use single upload
+ *   uploadAsSingleChunk(file);
+ * }
+ *
+ * // Check for streaming support
+ * if (capabilities.supportsStreamingRead) {
+ *   // Use streaming for memory-efficient processing
+ *   const stream = yield* dataStore.readStream(fileId);
+ * }
+ * ```
+ */
+type DataStoreCapabilities = {
+  supportsParallelUploads: boolean;
+  supportsConcatenation: boolean;
+  supportsDeferredLength: boolean;
+  supportsResumableUploads: boolean;
+  supportsTransactionalUploads: boolean; /** Whether the store supports streaming reads via readStream() */
+  supportsStreamingRead?: boolean; /** Whether the store supports streaming writes via writeStream() with unknown final size */
+  supportsStreamingWrite?: boolean;
+  maxConcurrentUploads?: number;
+  minChunkSize?: number;
+  maxChunkSize?: number;
+  maxParts?: number;
+  optimalChunkSize?: number;
+  requiresOrderedChunks: boolean;
+  requiresMimeTypeValidation?: boolean;
+  maxValidationSize?: number;
+};
+/**
+ * Core interface for all storage backend implementations.
+ *
+ * DataStore abstracts file storage operations across different backends
+ * (S3, Azure Blob, GCS, local filesystem, etc.). All storage adapters
+ * must implement this interface.
+ *
+ * @template TData - The data type stored (typically UploadFile)
+ *
+ * @property bucket - Optional storage bucket or container name
+ * @property path - Optional base path prefix for all stored files
+ * @property create - Creates a new file record in storage
+ * @property remove - Deletes a file from storage
+ * @property read - Reads complete file contents as bytes
+ * @property write - Writes data stream to storage at specified offset
+ * @property deleteExpired - Optional cleanup of expired files
+ * @property getCapabilities - Returns storage backend capabilities
+ * @property validateUploadStrategy - Validates if strategy is supported
+ *
+ * @example
+ * ```typescript
+ * // Implement a custom DataStore
+ * const myDataStore: DataStore<UploadFile> = {
+ *   bucket: "my-uploads",
+ *   path: "files/",
+ *
+ *   create: (file) => Effect.gen(function* () {
+ *     // Store file metadata
+ *     yield* saveMetadata(file);
+ *     return file;
+ *   }),
+ *
+ *   write: ({ file_id, stream, offset }, { onProgress }) => Effect.gen(function* () {
+ *     // Write chunks to storage
+ *     let bytesWritten = offset;
+ *     yield* Stream.runForEach(stream, (chunk) => Effect.sync(() => {
+ *       writeChunk(file_id, chunk, bytesWritten);
+ *       bytesWritten += chunk.byteLength;
+ *       onProgress?.(chunk.byteLength);
+ *     }));
+ *     return bytesWritten;
+ *   }),
+ *
+ *   read: (file_id) => Effect.gen(function* () {
+ *     // Read complete file
+ *     const data = yield* readFromStorage(file_id);
+ *     return data;
+ *   }),
+ *
+ *   remove: (file_id) => Effect.gen(function* () {
+ *     yield* deleteFromStorage(file_id);
+ *   }),
+ *
+ *   getCapabilities: () => ({
+ *     supportsParallelUploads: true,
+ *     supportsConcatenation: false,
+ *     supportsDeferredLength: true,
+ *     supportsResumableUploads: true,
+ *     supportsTransactionalUploads: false,
+ *     maxConcurrentUploads: 10,
+ *     optimalChunkSize: 5_242_880, // 5MB
+ *     requiresOrderedChunks: false,
+ *   }),
+ *
+ *   validateUploadStrategy: (strategy) =>
+ *     Effect.succeed(strategy === "parallel" || strategy === "single"),
+ * };
+ * ```
+ */
+type DataStore<TData = unknown> = {
+  readonly bucket?: string;
+  readonly path?: string;
+  readonly create: (file: TData) => Effect.Effect<TData, UploadistaError>;
+  readonly remove: (file_id: string) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Reads the complete file contents as bytes (buffered mode).
+   * For large files, consider using readStream() if available.
+   */
+  readonly read: (file_id: string) => Effect.Effect<Uint8Array, UploadistaError>;
+  /**
+   * Reads file content as a stream of chunks for memory-efficient processing.
+   * Optional - check getCapabilities().supportsStreamingRead before using.
+   *
+   * @param file_id - The unique identifier of the file to read
+   * @param config - Optional streaming configuration (chunk size)
+   * @returns An Effect that resolves to a Stream of byte chunks
+   *
+   * @example
+   * ```typescript
+   * const capabilities = dataStore.getCapabilities();
+   * if (capabilities.supportsStreamingRead && dataStore.readStream) {
+   *   const stream = yield* dataStore.readStream(fileId, { chunkSize: 65536 });
+   *   // Process stream chunk by chunk
+   * }
+   * ```
+   */
+  readonly readStream?: (file_id: string, config?: StreamingConfig) => Effect.Effect<Stream.Stream<Uint8Array, UploadistaError>, UploadistaError>;
+  readonly write: (options: DataStoreWriteOptions, dependencies: {
+    onProgress?: (chunkSize: number) => void;
+  }) => Effect.Effect<number, UploadistaError>;
+  /**
+   * Writes file content from a stream with unknown final size.
+   * Optional - check getCapabilities().supportsStreamingWrite before using.
+   *
+   * This method is optimized for end-to-end streaming where the output
+   * size isn't known until the stream completes. It uses store-specific
+   * mechanisms like multipart uploads (S3/R2), resumable uploads (GCS),
+   * or block staging (Azure) to efficiently handle streaming data.
+   *
+   * @param fileId - Unique identifier for the file being written
+   * @param options - Stream and optional metadata
+   * @returns StreamWriteResult containing final size after completion
+   *
+   * @example
+   * ```typescript
+   * const capabilities = dataStore.getCapabilities();
+   * if (capabilities.supportsStreamingWrite && dataStore.writeStream) {
+   *   const result = yield* dataStore.writeStream(fileId, {
+   *     stream: transformedStream,
+   *     contentType: "image/webp",
+   *   });
+   *   console.log(`Wrote ${result.size} bytes`);
+   * }
+   * ```
+   */
+  readonly writeStream?: (fileId: string, options: StreamWriteOptions) => Effect.Effect<StreamWriteResult, UploadistaError>;
+  readonly deleteExpired?: () => Effect.Effect<number, UploadistaError>;
+  readonly getCapabilities: () => DataStoreCapabilities;
+  readonly validateUploadStrategy: (strategy: UploadStrategy) => Effect.Effect<boolean, never>;
+};
+declare const UploadFileDataStore_base: Context.TagClass<UploadFileDataStore, "UploadFileDataStore", DataStore<UploadFile>>;
+/**
+ * Effect-TS context tag for UploadFile DataStore.
+ *
+ * Use this tag to access the primary DataStore in an Effect context.
+ * This is the standard storage backend for uploaded files.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const dataStore = yield* UploadFileDataStore;
+ *   const file = yield* dataStore.create(uploadFile);
+ *   return file;
+ * });
+ * ```
+ */
+declare class UploadFileDataStore extends UploadFileDataStore_base {}
+declare const BufferedUploadFileDataStore_base: Context.TagClass<BufferedUploadFileDataStore, "BufferedUploadFileDataStore", DataStore<UploadFile>>;
+/**
+ * Effect-TS context tag for buffered/temporary DataStore.
+ *
+ * This is an optional storage backend used for temporary or intermediate files
+ * during flow processing. Not all implementations provide a buffered store.
+ *
+ * @example
+ * ```typescript
+ * const processEffect = Effect.gen(function* () {
+ *   const bufferedStore = yield* BufferedUploadFileDataStore;
+ *   // Store intermediate processing results
+ *   const tempFile = yield* bufferedStore.create(intermediateFile);
+ *   return tempFile;
+ * });
+ * ```
+ */
+declare class BufferedUploadFileDataStore extends BufferedUploadFileDataStore_base {}
+/**
+ * Service interface for managing multiple DataStore instances.
+ *
+ * This allows routing files to different storage backends based on
+ * storageId (e.g., different S3 buckets, Azure containers, or storage tiers).
+ *
+ * @property getDataStore - Retrieves the appropriate DataStore for a given storage ID
+ * @property bufferedDataStore - Optional temporary storage for intermediate files
+ */
+type UploadFileDataStoresShape = {
+  getDataStore: (storageId: string, clientId: string | null) => Effect.Effect<DataStore<UploadFile>, UploadistaError>;
+  bufferedDataStore: Effect.Effect<DataStore<UploadFile> | undefined, UploadistaError>;
+};
+declare const UploadFileDataStores_base: Context.TagClass<UploadFileDataStores, "UploadFileDataStores", UploadFileDataStoresShape>;
+/**
+ * Effect-TS context tag for the DataStore routing service.
+ *
+ * Provides access to multiple DataStore instances with routing logic.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const dataStores = yield* UploadFileDataStores;
+ *   // Route to specific storage based on storageId
+ *   const dataStore = yield* dataStores.getDataStore("s3-production", clientId);
+ *   const file = yield* dataStore.create(uploadFile);
+ *   return file;
+ * });
+ * ```
+ */
+declare class UploadFileDataStores extends UploadFileDataStores_base {}
+/**
+ * Simplified DataStore configuration for easy setup.
+ *
+ * This type allows flexible configuration:
+ * - Single DataStore instance
+ * - Multiple named stores with routing
+ * - Effect that resolves to a DataStore
+ * - Pre-built Effect Layer
+ *
+ * @example
+ * ```typescript
+ * // Single store
+ * const config: DataStoreConfig = s3DataStore;
+ *
+ * // Multiple stores with routing
+ * const config: DataStoreConfig = {
+ *   stores: {
+ *     "s3-prod": s3ProdStore,
+ *     "s3-dev": s3DevStore,
+ *     "local": localFileStore,
+ *   },
+ *   default: "s3-prod"
+ * };
+ *
+ * // Effect that creates a store
+ * const config: DataStoreConfig = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *   return s3Store(kvStore);
+ * });
+ *
+ * // Pre-built Layer
+ * const config: DataStoreConfig = Layer.succeed(UploadFileDataStores, {...});
+ * ```
+ */
+type DataStoreConfig = DataStore<UploadFile> | Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore> | {
+  stores: Record<string, DataStore<UploadFile> | Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore>>;
+  default?: string;
+} | Layer.Layer<UploadFileDataStores, never, UploadFileKVStore>;
+/**
+ * Type guard to check if a value is a DataStore instance.
+ *
+ * @param config - The value to check
+ * @returns True if the value is a DataStore
+ *
+ * @example
+ * ```typescript
+ * if (isDataStore(config)) {
+ *   const capabilities = config.getCapabilities();
+ * }
+ * ```
+ */
+declare const isDataStore: (config: DataStoreConfig) => config is DataStore<UploadFile>;
+/**
+ * Creates an Effect Layer from simplified DataStoreConfig.
+ *
+ * This function converts any DataStoreConfig format into a proper Effect Layer
+ * that can be provided to the UploadFileDataStores context tag.
+ *
+ * It handles:
+ * - Single DataStore: Wraps in a Layer that always returns that store
+ * - Multiple stores: Creates routing logic with optional default
+ * - Effect<DataStore>: Executes the Effect and wraps the result
+ * - Layer: Returns as-is
+ *
+ * @param config - The DataStore configuration
+ * @returns A Layer that provides UploadFileDataStores service
+ *
+ * @example
+ * ```typescript
+ * // Create from single store
+ * const layer = await createDataStoreLayer(s3DataStore);
+ *
+ * // Create from multiple stores
+ * const layer = await createDataStoreLayer({
+ *   stores: {
+ *     "production": s3Store,
+ *     "development": localStore,
+ *   },
+ *   default: "development"
+ * });
+ *
+ * // Use the layer
+ * const program = Effect.gen(function* () {
+ *   const stores = yield* UploadFileDataStores;
+ *   const store = yield* stores.getDataStore("production", null);
+ *   return store;
+ * }).pipe(Effect.provide(layer));
+ * ```
+ */
+declare const createDataStoreLayer: (config: DataStoreConfig) => Promise<Layer.Layer<UploadFileDataStores, never, UploadFileKVStore>>;
+//#endregion
+//#region src/types/event-broadcaster.d.ts
+/**
+ * Event broadcaster interface for pub/sub messaging across distributed instances.
+ * Used by WebSocketManager to broadcast upload events to all connected instances.
+ */
+interface EventBroadcaster {
+  /**
+   * Publish a message to a channel
+   */
+  readonly publish: (channel: string, message: string) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Subscribe to messages on a channel
+   */
+  readonly subscribe: (channel: string, handler: (message: string) => void) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Unsubscribe from a channel (optional - not all implementations may support)
+   */
+  readonly unsubscribe?: (channel: string) => Effect.Effect<void, UploadistaError>;
+}
+declare const EventBroadcasterService_base: Context.TagClass<EventBroadcasterService, "EventBroadcaster", EventBroadcaster>;
+/**
+ * Context tag for EventBroadcaster service
+ */
+declare class EventBroadcasterService extends EventBroadcasterService_base {}
+//#endregion
+//#region src/types/upload-event.d.ts
+declare enum UploadEventType {
+  UPLOAD_STARTED = "upload-started",
+  UPLOAD_PROGRESS = "upload-progress",
+  UPLOAD_COMPLETE = "upload-complete",
+  UPLOAD_FAILED = "upload-failed",
+  UPLOAD_VALIDATION_SUCCESS = "upload-validation-success",
+  UPLOAD_VALIDATION_FAILED = "upload-validation-failed",
+  UPLOAD_VALIDATION_WARNING = "upload-validation-warning"
+}
+declare const uploadEventSchema: z.ZodUnion<readonly [z.ZodObject<{
+  type: z.ZodUnion<readonly [z.ZodLiteral<UploadEventType.UPLOAD_STARTED>, z.ZodLiteral<UploadEventType.UPLOAD_COMPLETE>]>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+    creationDate: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    sizeIsDeferred: z.ZodOptional<z.ZodBoolean>;
+    checksum: z.ZodOptional<z.ZodString>;
+    checksumAlgorithm: z.ZodOptional<z.ZodString>;
+    storage: z.ZodObject<{
+      id: z.ZodString;
+      type: z.ZodString;
+      path: z.ZodOptional<z.ZodString>;
+      uploadId: z.ZodOptional<z.ZodString>;
+      bucket: z.ZodOptional<z.ZodString>;
+      parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        partNumber: z.ZodNumber;
+        etag: z.ZodString;
+        size: z.ZodNumber;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    flow: z.ZodOptional<z.ZodObject<{
+      flowId: z.ZodString;
+      nodeId: z.ZodString;
+      jobId: z.ZodString;
+    }, z.core.$strip>>;
+    traceContext: z.ZodOptional<z.ZodObject<{
+      traceId: z.ZodString;
+      spanId: z.ZodString;
+      traceFlags: z.ZodNumber;
+    }, z.core.$strip>>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_PROGRESS>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    progress: z.ZodNumber;
+    total: z.ZodNumber;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_FAILED>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    error: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_SUCCESS>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    validationType: z.ZodEnum<{
+      checksum: "checksum";
+      mimetype: "mimetype";
+    }>;
+    algorithm: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_FAILED>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    reason: z.ZodString;
+    expected: z.ZodString;
+    actual: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_WARNING>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>]>;
+type UploadEvent = z.infer<typeof uploadEventSchema>;
+//#endregion
+//#region src/types/websocket.d.ts
+/**
+ * Platform-agnostic WebSocket connection interface
+ */
+interface WebSocketConnection {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  readonly readyState: number;
+  readonly id: string;
+}
+/**
+ * WebSocket message that can be sent/received
+ */
+declare const webSocketMessageSchema: z$1.ZodUnion<readonly [z$1.ZodObject<{
+  type: z$1.ZodLiteral<"upload_event">;
+  payload: z$1.ZodUnion<readonly [z$1.ZodObject<{
+    type: z$1.ZodUnion<readonly [z$1.ZodLiteral<UploadEventType.UPLOAD_STARTED>, z$1.ZodLiteral<UploadEventType.UPLOAD_COMPLETE>]>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      size: z$1.ZodOptional<z$1.ZodNumber>;
+      offset: z$1.ZodNumber;
+      metadata: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodType<JsonValue, unknown, z$1.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+      creationDate: z$1.ZodOptional<z$1.ZodString>;
+      url: z$1.ZodOptional<z$1.ZodString>;
+      sizeIsDeferred: z$1.ZodOptional<z$1.ZodBoolean>;
+      checksum: z$1.ZodOptional<z$1.ZodString>;
+      checksumAlgorithm: z$1.ZodOptional<z$1.ZodString>;
+      storage: z$1.ZodObject<{
+        id: z$1.ZodString;
+        type: z$1.ZodString;
+        path: z$1.ZodOptional<z$1.ZodString>;
+        uploadId: z$1.ZodOptional<z$1.ZodString>;
+        bucket: z$1.ZodOptional<z$1.ZodString>;
+        parts: z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
+          partNumber: z$1.ZodNumber;
+          etag: z$1.ZodString;
+          size: z$1.ZodNumber;
+        }, z$1.core.$strip>>>;
+      }, z$1.core.$strip>;
+      flow: z$1.ZodOptional<z$1.ZodObject<{
+        flowId: z$1.ZodString;
+        nodeId: z$1.ZodString;
+        jobId: z$1.ZodString;
+      }, z$1.core.$strip>>;
+      traceContext: z$1.ZodOptional<z$1.ZodObject<{
+        traceId: z$1.ZodString;
+        spanId: z$1.ZodString;
+        traceFlags: z$1.ZodNumber;
+      }, z$1.core.$strip>>;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_PROGRESS>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      progress: z$1.ZodNumber;
+      total: z$1.ZodNumber;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_FAILED>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      error: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_SUCCESS>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      validationType: z$1.ZodEnum<{
+        checksum: "checksum";
+        mimetype: "mimetype";
+      }>;
+      algorithm: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_FAILED>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      reason: z$1.ZodString;
+      expected: z$1.ZodString;
+      actual: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_WARNING>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      message: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>]>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"flow_event">;
+  payload: z$1.ZodAny;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"subscribed">;
+  payload: z$1.ZodObject<{
+    eventKey: z$1.ZodString;
+  }, z$1.core.$strip>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"error">;
+  message: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"pong">;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"ping">;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"connection">;
+  message: z$1.ZodOptional<z$1.ZodString>;
+  uploadId: z$1.ZodOptional<z$1.ZodString>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>]>;
+type WebSocketMessage<TEvent = unknown> = z$1.infer<typeof webSocketMessageSchema> | {
+  type: "upload_event";
+  payload: TEvent;
+  timestamp?: string;
+} | {
+  type: "flow_event";
+  payload: TEvent;
+  timestamp?: string;
+};
+//#endregion
+//#region src/types/event-emitter.d.ts
+/**
+ * Base event emitter interface for raw string message broadcasting.
+ *
+ * This is the low-level interface that event broadcasting implementations
+ * (WebSocket, Server-Sent Events, etc.) implement. It emits raw string messages
+ * without type safety or serialization.
+ *
+ * @property subscribe - Registers a WebSocket connection to receive events for a key
+ * @property unsubscribe - Removes subscription for a key
+ * @property emit - Broadcasts a string message to all subscribers of a key
+ *
+ * @example
+ * ```typescript
+ * // Implement BaseEventEmitter with WebSocket broadcast
+ * const websocketEmitter: BaseEventEmitter = {
+ *   subscribe: (key, connection) => Effect.sync(() => {
+ *     connections.set(key, [...(connections.get(key) || []), connection]);
+ *   }),
+ *
+ *   unsubscribe: (key) => Effect.sync(() => {
+ *     connections.delete(key);
+ *   }),
+ *
+ *   emit: (key, event) => Effect.sync(() => {
+ *     const subs = connections.get(key) || [];
+ *     subs.forEach(conn => conn.send(event));
+ *   })
+ * };
+ * ```
+ */
+interface BaseEventEmitter {
+  readonly subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  readonly unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly emit: (key: string, event: string) => Effect.Effect<void, UploadistaError>;
+}
+/**
+ * Type-safe event emitter interface with automatic serialization.
+ *
+ * This wraps a BaseEventEmitter and handles event serialization to JSON messages,
+ * providing type safety for events and ensuring consistent message format.
+ *
+ * @template TEvent - The type of events emitted by this emitter
+ *
+ * @property subscribe - Registers a WebSocket connection to receive typed events
+ * @property unsubscribe - Removes subscription
+ * @property emit - Serializes and broadcasts a typed event
+ *
+ * @example
+ * ```typescript
+ * // Use a typed event emitter
+ * const uploadEmitter: EventEmitter<UploadEvent> = new TypedEventEmitter(
+ *   baseEmitter,
+ *   (event) => JSON.stringify({ type: 'upload', payload: event })
+ * );
+ *
+ * // Emit type-safe events
+ * const program = Effect.gen(function* () {
+ *   const event: UploadEvent = {
+ *     uploadId: "upload123",
+ *     type: "progress",
+ *     offset: 1024,
+ *     size: 2048
+ *   };
+ *
+ *   // Automatic serialization
+ *   yield* uploadEmitter.emit("upload123", event);
+ * });
+ * ```
+ */
+type EventEmitter<TEvent> = {
+  readonly subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  readonly unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly emit: (key: string, event: TEvent) => Effect.Effect<void, UploadistaError>;
+};
+/**
+ * Typed wrapper class that adds event serialization to a BaseEventEmitter.
+ *
+ * This class implements the EventEmitter interface by wrapping a BaseEventEmitter
+ * and handling serialization for a specific event type. It converts typed events
+ * to JSON message strings before broadcasting.
+ *
+ * @template TEvent - The type of events to emit
+ *
+ * @example
+ * ```typescript
+ * // Create a typed emitter for UploadEvent
+ * const uploadEmitter = new TypedEventEmitter<UploadEvent>(
+ *   baseEmitter,
+ *   (event) => JSON.stringify({
+ *     type: "upload_event",
+ *     payload: event,
+ *     timestamp: new Date().toISOString()
+ *   })
+ * );
+ *
+ * // Use the emitter
+ * const effect = Effect.gen(function* () {
+ *   // Subscribe a WebSocket connection
+ *   yield* uploadEmitter.subscribe("upload123", websocket);
+ *
+ *   // Emit an event (automatically serialized)
+ *   yield* uploadEmitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "completed",
+ *     offset: 2048,
+ *     size: 2048
+ *   });
+ *
+ *   // Unsubscribe when done
+ *   yield* uploadEmitter.unsubscribe("upload123");
+ * });
+ *
+ * // Custom message format
+ * const customEmitter = new TypedEventEmitter<MyEvent>(
+ *   baseEmitter,
+ *   (event) => `EVENT:${event.type}:${JSON.stringify(event.data)}`
+ * );
+ * ```
+ */
+declare class TypedEventEmitter<TEvent> implements EventEmitter<TEvent> {
+  private baseEmitter;
+  private eventToMessage;
+  constructor(baseEmitter: BaseEventEmitter, eventToMessage: (event: TEvent) => string);
+  subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  emit: (key: string, event: TEvent) => Effect.Effect<void, UploadistaError>;
+}
+/**
+ * Default event-to-message serialization helper.
+ *
+ * Creates a standardized JSON message format with type, payload, and timestamp.
+ * This is the recommended way to serialize events for WebSocket transmission.
+ *
+ * @param messageType - The message type identifier ("upload_event" or "flow_event")
+ * @returns An object with an eventToMessage function
+ *
+ * @example
+ * ```typescript
+ * // Create emitter with standard serialization
+ * const emitter = new TypedEventEmitter<UploadEvent>(
+ *   baseEmitter,
+ *   eventToMessageSerializer("upload_event").eventToMessage
+ * );
+ *
+ * // Messages will be formatted as:
+ * // {
+ * //   "type": "upload_event",
+ * //   "payload": { ...event data... },
+ * //   "timestamp": "2024-01-15T10:30:00.000Z"
+ * // }
+ * ```
+ */
+declare const eventToMessageSerializer: (messageType: "upload_event" | "flow_event") => {
+  eventToMessage: <T>(event: T) => string;
+};
+declare const BaseEventEmitterService_base: Context.TagClass<BaseEventEmitterService, "BaseEventEmitter", BaseEventEmitter>;
+/**
+ * Effect-TS context tag for the base untyped event emitter.
+ *
+ * This is the low-level emitter that broadcasting implementations provide.
+ * Most application code should use typed emitters like UploadEventEmitter instead.
+ *
+ * @example
+ * ```typescript
+ * // Provide a base emitter implementation
+ * const baseEmitterLayer = Layer.succeed(BaseEventEmitterService, websocketEmitter);
+ *
+ * // Use in an Effect
+ * const effect = Effect.gen(function* () {
+ *   const baseEmitter = yield* BaseEventEmitterService;
+ *   yield* baseEmitter.emit("channel1", "raw message");
+ * });
+ * ```
+ */
+declare class BaseEventEmitterService extends BaseEventEmitterService_base {}
+declare const UploadEventEmitter_base: Context.TagClass<UploadEventEmitter, "UploadEventEmitter", EventEmitter<{
+  type: UploadEventType.UPLOAD_STARTED | UploadEventType.UPLOAD_COMPLETE;
+  data: {
+    id: string;
+    offset: number;
+    storage: {
+      id: string;
+      type: string;
+      path?: string | undefined;
+      uploadId?: string | undefined;
+      bucket?: string | undefined;
+      parts?: {
+        partNumber: number;
+        etag: string;
+        size: number;
+      }[] | undefined;
+    };
+    size?: number | undefined;
+    metadata?: Record<string, JsonValue> | undefined;
+    creationDate?: string | undefined;
+    url?: string | undefined;
+    sizeIsDeferred?: boolean | undefined;
+    checksum?: string | undefined;
+    checksumAlgorithm?: string | undefined;
+    flow?: {
+      flowId: string;
+      nodeId: string;
+      jobId: string;
+    } | undefined;
+    traceContext?: {
+      traceId: string;
+      spanId: string;
+      traceFlags: number;
+    } | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_PROGRESS;
+  data: {
+    id: string;
+    progress: number;
+    total: number;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_FAILED;
+  data: {
+    id: string;
+    error: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_SUCCESS;
+  data: {
+    id: string;
+    validationType: "checksum" | "mimetype";
+    algorithm?: string | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_FAILED;
+  data: {
+    id: string;
+    reason: string;
+    expected: string;
+    actual: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_WARNING;
+  data: {
+    id: string;
+    message: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+}>>;
+/**
+ * Effect-TS context tag for the UploadEvent typed emitter.
+ *
+ * This provides type-safe event emission for upload progress and lifecycle events.
+ * It's the primary way to broadcast upload events to connected clients.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const emitter = yield* UploadEventEmitter;
+ *
+ *   // Subscribe a client to upload events
+ *   yield* emitter.subscribe("upload123", websocketConnection);
+ *
+ *   // Emit progress event
+ *   yield* emitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "progress",
+ *     offset: 512000,
+ *     size: 1024000
+ *   });
+ *
+ *   // Emit completion event
+ *   yield* emitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "completed",
+ *     offset: 1024000,
+ *     size: 1024000
+ *   });
+ * });
+ * ```
+ */
+declare class UploadEventEmitter extends UploadEventEmitter_base {}
+/**
+ * Effect Layer that creates the UploadEventEmitter from a BaseEventEmitter.
+ *
+ * This layer automatically wires up JSON serialization for UploadEvent objects
+ * with the standard "upload_event" message format.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const emitter = yield* UploadEventEmitter;
+ *   // Use the emitter...
+ * }).pipe(
+ *   Effect.provide(uploadEventEmitter),
+ *   Effect.provide(baseEmitterLayer)
+ * );
+ * ```
+ */
+declare const uploadEventEmitter: Layer.Layer<UploadEventEmitter, never, BaseEventEmitterService>;
+declare const FlowEventEmitter_base: Context.TagClass<FlowEventEmitter, "FlowEventEmitter", EventEmitter<FlowEvent>>;
+/**
+ * Effect-TS context tag for the FlowEvent typed emitter.
+ *
+ * This provides type-safe event emission for flow processing lifecycle events.
+ * It's used to broadcast flow execution progress, node completion, and errors.
+ *
+ * @example
+ * ```typescript
+ * const flowEffect = Effect.gen(function* () {
+ *   const emitter = yield* FlowEventEmitter;
+ *
+ *   // Subscribe a client to flow job events
+ *   yield* emitter.subscribe("job123", websocketConnection);
+ *
+ *   // Emit node start event
+ *   yield* emitter.emit("job123", {
+ *     jobId: "job123",
+ *     eventType: "NodeStart",
+ *     flowId: "flow_resize",
+ *     nodeId: "resize_1"
+ *   });
+ *
+ *   // Emit node completion event
+ *   yield* emitter.emit("job123", {
+ *     jobId: "job123",
+ *     eventType: "NodeEnd",
+ *     flowId: "flow_resize",
+ *     nodeId: "resize_1",
+ *     result: { width: 800, height: 600 }
+ *   });
+ * });
+ * ```
+ */
+declare class FlowEventEmitter extends FlowEventEmitter_base {}
+/**
+ * Effect Layer that creates the FlowEventEmitter from a BaseEventEmitter.
+ *
+ * This layer automatically wires up JSON serialization for FlowEvent objects
+ * with the standard "flow_event" message format.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const emitter = yield* FlowEventEmitter;
+ *   // Use the emitter...
+ * }).pipe(
+ *   Effect.provide(flowEventEmitter),
+ *   Effect.provide(baseEmitterLayer)
+ * );
+ * ```
+ */
+declare const flowEventEmitter: Layer.Layer<FlowEventEmitter, never, BaseEventEmitterService>;
+//#endregion
+//#region src/types/health-check.d.ts
+/**
+ * Health Check Types for Uploadista SDK.
+ *
+ * This module provides types for the health monitoring system including:
+ * - Liveness probes (`/health`)
+ * - Readiness probes (`/ready`)
+ * - Component health details (`/health/components`)
+ *
+ * @module types/health-check
+ */
+/**
+ * Health status values for components and overall system health.
+ *
+ * - `healthy`: All checks passed, system is fully operational
+ * - `degraded`: Some non-critical issues detected, but system is functional
+ * - `unhealthy`: Critical components unavailable, system cannot serve requests
+ */
+type HealthStatus = "healthy" | "degraded" | "unhealthy";
+/**
+ * Health status for an individual component (storage, KV store, etc.).
+ */
+interface ComponentHealth {
+  /** Current health status of the component */
+  status: HealthStatus;
+  /** Latency of the last health check in milliseconds */
+  latency?: number;
+  /** Human-readable status message */
+  message?: string;
+  /** ISO 8601 timestamp of the last health check */
+  lastCheck?: string;
+}
+/**
+ * Circuit breaker health summary aggregating all circuit states.
+ */
+interface CircuitBreakerHealthSummary {
+  /** Overall circuit breaker system status */
+  status: HealthStatus;
+  /** Number of circuits currently in open state */
+  openCircuits: number;
+  /** Total number of tracked circuits */
+  totalCircuits: number;
+  /** Detailed stats for each circuit (optional, for debugging) */
+  circuits?: Array<{
+    nodeType: string;
+    state: "closed" | "open" | "half-open";
+    failureCount: number;
+    timeSinceLastStateChange: number;
+  }>;
+}
+/**
+ * Dead Letter Queue health summary.
+ */
+interface DlqHealthSummary {
+  /** Overall DLQ status */
+  status: HealthStatus;
+  /** Number of items pending retry */
+  pendingItems: number;
+  /** Number of items that have exhausted all retries */
+  exhaustedItems: number;
+  /** ISO 8601 timestamp of the oldest item in the queue */
+  oldestItem?: string;
+}
+/**
+ * Components health map for detailed health responses.
+ */
+interface HealthComponents {
+  /** Storage backend health */
+  storage?: ComponentHealth;
+  /** KV store health */
+  kvStore?: ComponentHealth;
+  /** Event broadcaster health */
+  eventBroadcaster?: ComponentHealth;
+  /** Circuit breaker summary (if enabled) */
+  circuitBreaker?: CircuitBreakerHealthSummary;
+  /** Dead letter queue summary (if enabled) */
+  deadLetterQueue?: DlqHealthSummary;
+}
+/**
+ * Standard health response structure.
+ *
+ * Used for all health endpoints with varying levels of detail.
+ */
+interface HealthResponse {
+  /** Overall health status */
+  status: HealthStatus;
+  /** ISO 8601 timestamp of the response */
+  timestamp: string;
+  /** Optional version string for deployment identification */
+  version?: string;
+  /** Server uptime in milliseconds */
+  uptime?: number;
+  /** Component-level health details (for /health/components) */
+  components?: HealthComponents;
+}
+/**
+ * Configuration options for health check behavior.
+ */
+interface HealthCheckConfig {
+  /**
+   * Timeout for dependency health checks in milliseconds.
+   * @default 5000
+   */
+  timeout?: number;
+  /**
+   * Whether to check storage backend health.
+   * @default true
+   */
+  checkStorage?: boolean;
+  /**
+   * Whether to check KV store health.
+   * @default true
+   */
+  checkKvStore?: boolean;
+  /**
+   * Whether to check event broadcaster health.
+   * @default true
+   */
+  checkEventBroadcaster?: boolean;
+  /**
+   * Optional version string to include in health responses.
+   * Useful for identifying deployed versions.
+   */
+  version?: string;
+}
+/**
+ * Default health check configuration values.
+ */
+declare const DEFAULT_HEALTH_CHECK_CONFIG: Required<Omit<HealthCheckConfig, "version">>;
+/**
+ * Supported response formats for health endpoints.
+ */
+type HealthResponseFormat = "json" | "text";
+/**
+ * Determines the response format based on Accept header.
+ *
+ * @param acceptHeader - The Accept header value from the request
+ * @returns The response format to use
+ */
+declare function getHealthResponseFormat(acceptHeader?: string | null): HealthResponseFormat;
+/**
+ * Formats a health response as plain text.
+ *
+ * @param status - The health status
+ * @returns Plain text representation
+ */
+declare function formatHealthAsText(status: HealthStatus): string;
+//#endregion
+//#region src/types/input-file.d.ts
+/**
+ * Zod schema for validating InputFile objects.
+ *
+ * This schema defines the structure and validation rules for file upload requests.
+ * Use this schema to parse and validate input data when creating new uploads.
+ *
+ * @see {@link InputFile} for the TypeScript type
+ */
+declare const inputFileSchema: z.ZodObject<{
+  uploadLengthDeferred: z.ZodOptional<z.ZodBoolean>;
+  storageId: z.ZodString;
+  size: z.ZodOptional<z.ZodNumber>;
+  sizeHint: z.ZodOptional<z.ZodNumber>;
+  type: z.ZodString;
+  fileName: z.ZodOptional<z.ZodString>;
+  lastModified: z.ZodOptional<z.ZodNumber>;
+  metadata: z.ZodOptional<z.ZodString>;
+  checksum: z.ZodOptional<z.ZodString>;
+  checksumAlgorithm: z.ZodOptional<z.ZodString>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Represents the input data for creating a new file upload.
+ *
+ * This type defines the information required to initiate an upload.
+ * It's used by clients to provide upload metadata before sending file data.
+ *
+ * @property storageId - Target storage backend identifier (e.g., "s3-production", "azure-blob")
+ * @property size - File size in bytes. Optional when uploadLengthDeferred is true.
+ * @property sizeHint - Optional size hint for optimization when exact size is unknown
+ * @property type - MIME type of the file (e.g., "image/jpeg", "application/pdf")
+ * @property uploadLengthDeferred - If true, file size is not known upfront (streaming upload)
+ * @property fileName - Original filename from the client
+ * @property lastModified - File's last modified timestamp in milliseconds since epoch
+ * @property metadata - Base64-encoded metadata string (as per tus protocol)
+ * @property checksum - Expected file checksum for validation
+ * @property checksumAlgorithm - Algorithm used for checksum (e.g., "md5", "sha256")
+ * @property flow - Optional flow processing configuration
+ * @property flow.flowId - ID of the flow to execute on this file
+ * @property flow.nodeId - Starting node ID in the flow
+ * @property flow.jobId - Flow job execution ID
+ *
+ * @example
+ * ```typescript
+ * // Basic file upload
+ * const inputFile: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 1024000,
+ *   type: "image/jpeg",
+ *   fileName: "photo.jpg",
+ *   lastModified: Date.now()
+ * };
+ *
+ * // Upload with metadata (base64 encoded as per tus protocol)
+ * const metadata = btoa(JSON.stringify({
+ *   userId: "user_123",
+ *   albumId: "album_456"
+ * }));
+ * const inputWithMetadata: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 2048000,
+ *   type: "image/png",
+ *   fileName: "screenshot.png",
+ *   metadata
+ * };
+ *
+ * // Upload with checksum validation
+ * const inputWithChecksum: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 512000,
+ *   type: "application/pdf",
+ *   fileName: "document.pdf",
+ *   checksum: "5d41402abc4b2a76b9719d911017c592",
+ *   checksumAlgorithm: "md5"
+ * };
+ *
+ * // Upload that triggers a flow
+ * const inputWithFlow: InputFile = {
+ *   storageId: "s3-temp",
+ *   size: 4096000,
+ *   type: "image/jpeg",
+ *   fileName: "large-image.jpg",
+ *   flow: {
+ *     flowId: "resize-and-optimize",
+ *     nodeId: "input_1",
+ *     jobId: "job_789"
+ *   }
+ * };
+ *
+ * // Streaming upload (size unknown) - size can be omitted
+ * const streamingInput: InputFile = {
+ *   storageId: "s3-production",
+ *   type: "video/mp4",
+ *   uploadLengthDeferred: true,
+ *   fileName: "live-stream.mp4"
+ * };
+ *
+ * // Streaming upload with size hint for optimization
+ * const streamingWithHint: InputFile = {
+ *   storageId: "s3-production",
+ *   type: "image/webp",
+ *   uploadLengthDeferred: true,
+ *   sizeHint: 5_000_000, // ~5MB expected
+ *   fileName: "optimized-image.webp"
+ * };
+ * ```
+ */
+type InputFile = z.infer<typeof inputFileSchema>;
+//#endregion
+//#region src/types/middleware.d.ts
+type MiddlewareContext = {
+  request: Request;
+  uploadId?: string;
+  metadata?: Record<string, string>;
+};
+type MiddlewareNext = () => Promise<Response>;
+type Middleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
+declare const MiddlewareService_base: Context.TagClass<MiddlewareService, "MiddlewareService", {
+  readonly execute: (middlewares: Middleware[], context: MiddlewareContext, handler: MiddlewareNext) => Effect.Effect<Response, UploadistaError>;
+}>;
+declare class MiddlewareService extends MiddlewareService_base {}
+declare const MiddlewareServiceLive: Layer.Layer<MiddlewareService, never, never>;
+//#endregion
+export { BaseKvStoreService as $, calculateBackoffDelay as $t, webSocketMessageSchema as A, JsonValue as An, FlowDeadLetterQueueConfig as At, DataStoreCapabilities as B, DeadLetterItemStatus as Bn, TypedOutput as Bt, TypedEventEmitter as C, FlowEventNodeStart as Cn, BuiltInTypedOutput as Ct, uploadEventEmitter as D, NodeType as Dn, FlowCircuitBreakerConfig as Dt, flowEventEmitter as E, ConditionValue as En, FileNamingFunction as Et, EventBroadcasterService as F, uploadFileSchema as Fn, NarrowTypedOutput as Ft, StreamingConfig as G, DeadLetterRetryAttempt as Gn, isStreamingInputV1 as Gt, DataStoreWriteOptions as H, DeadLetterProcessResult as Hn, completeNodeExecution as Ht, BufferedUploadFileDataStore as I, DeadLetterCleanupOptions as In, NodeConnectionValidator as It, UploadFileDataStoresShape as J, CircuitBreakerStats as Jn, DEFAULT_RETRY_POLICY as Jt, UploadFileDataStore as K, CircuitBreakerStateData as Kn, waitingNodeExecution as Kt, DEFAULT_MULTIPART_PART_SIZE as L, DeadLetterCleanupResult as Ln, NodeExecutionResult as Lt, UploadEventType as M, UploadFileTraceContext as Mn, FlowNode as Mt, uploadEventSchema as N, jsonValueSchema as Nn, FlowNodeData as Nt, WebSocketConnection as O, createFlowNode as On, FlowCircuitBreakerFallback as Ot, EventBroadcaster as P, traceContextSchema as Pn, NamingContext as Pt, BaseKvStore as Q, RetryPolicy as Qt, DEFAULT_STREAMING_CONFIG as R, DeadLetterError as Rn, NodeTypeMap as Rt, FlowEventEmitter as S, FlowEventNodeResume as Sn, BuiltInNodeType as St, eventToMessageSerializer as T, ConditionOperator as Tn, FileNamingConfig as Tt, StreamWriteOptions as U, DeadLetterQueueStats as Un, createOutputGuard as Ut, DataStoreConfig as V, DeadLetterListOptions as Vn, TypedOutputGuard as Vt, StreamWriteResult as W, DeadLetterRetryAllResult as Wn, isStorageOutputV1 as Wt, createDataStoreLayer as X, CircuitBreakerStoreService as Xn, FixedBackoff as Xt, UploadStrategy as Y, CircuitBreakerStore as Yn, ExponentialBackoff as Yt, isDataStore as Z, createInitialCircuitBreakerState as Zn, ImmediateBackoff as Zt, formatHealthAsText as _, FlowEventJobStart as _n, FlowJobStatus as _t, MiddlewareServiceLive as a, FlowEventDlqItemAdded as an, UploadFileKVStore as at, BaseEventEmitterService as b, FlowEventNodePause as bn, FlowJobTraceContext as bt, CircuitBreakerHealthSummary as c, FlowEventDlqRetryFailed as cn, flowQueueKvStore as ct, DlqHealthSummary as d, FlowEventFlowCancel as dn, DEFAULT_QUEUE_CONFIG as dt, calculateExpirationDate as en, DeadLetterQueueKVStore as et, HealthCheckConfig as f, FlowEventFlowEnd as fn, FlowQueueConfig as ft, HealthStatus as g, FlowEventJobEnd as gn, FlowJob as gt, HealthResponseFormat as h, FlowEventFlowStart as hn, FlowQueueStats as ht, MiddlewareService as i, FlowEvent as in, TypedKvStore as it, UploadEvent as j, UploadFile as jn, FlowEdge as jt, WebSocketMessage as k, getNodeData as kn, FlowConfig as kt, ComponentHealth as l, FlowEventDlqRetryStart as ln, jsonSerializer as lt, HealthResponse as m, FlowEventFlowPause as mn, FlowQueueItemStatus as mt, MiddlewareContext as n, DlqEvent as nn, FlowQueueKVStore as nt, InputFile as o, FlowEventDlqItemExhausted as on, deadLetterQueueKvStore as ot, HealthComponents as p, FlowEventFlowError as pn, FlowQueueItem as pt, UploadFileDataStores as q, CircuitBreakerStateValue as qn, BackoffStrategy as qt, MiddlewareNext as r, EventType as rn, KvStore as rt, inputFileSchema as s, FlowEventDlqItemResolved as sn, flowJobKvStore as st, Middleware as t, isErrorRetryable as tn, FlowJobKVStore as tt, DEFAULT_HEALTH_CHECK_CONFIG as u, FlowEventDlqRetrySuccess as un, uploadFileKvStore as ut, getHealthResponseFormat as v, FlowEventNodeEnd as vn, FlowJobTask as vt, UploadEventEmitter as w, ConditionField as wn, CustomTypedOutput as wt, EventEmitter as x, FlowEventNodeResponse as xn, AutoNamingSuffixGenerator as xt, BaseEventEmitter as y, FlowEventNodeError as yn, FlowJobTaskStatus as yt, DataStore as z, DeadLetterItem as zn, TypeCompatibilityChecker as zt };
+//# sourceMappingURL=middleware-BmRmwme_.d.mts.map