@uploadista/core 0.0.17 → 0.0.18-beta.10

package/dist/{index-BQ5luyME.d.cts → index-D7i4bgl3.d.mts}

@@ -1,12 +1,82 @@
-import { n as UploadistaError } from "./uploadista-error-Bb-qIIKM.cjs";
-import { l as GenerateId, p as GenerateIdShape } from "./index-B_SvQ0MU.cjs";
+import { n as UploadistaError } from "./uploadista-error-DR0XimpE.mjs";
+import { l as GenerateId, p as GenerateIdShape } from "./index-B9V5SSxl.mjs";
 import { Context, Effect, Layer, Option, Stream } from "effect";
 import * as zod0 from "zod";
 import z$1, { z } from "zod";
 import * as zod_v4_core0 from "zod/v4/core";
 
-//#region src/types/upload-file.d.ts
+//#region src/flow/circuit-breaker.d.ts
 
+/**
+ * Circuit breaker state machine states.
+ *
+ * - `closed`: Normal operation, tracking failures in sliding window
+ * - `open`: Rejecting all requests immediately, waiting for reset timeout
+ * - `half-open`: Allowing limited test requests to probe service health
+ */
+type CircuitBreakerState = "closed" | "open" | "half-open";
+/**
+ * Configuration for a circuit breaker.
+ *
+ * @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
+ */
+interface CircuitBreakerConfig {
+  /** 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?: CircuitBreakerFallback;
+}
+/**
+ * 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 CircuitBreakerFallback = {
+  type: "fail";
+} | {
+  type: "skip";
+  passThrough: true;
+} | {
+  type: "default";
+  value: unknown;
+};
+/**
+ * Event emitted when circuit state changes.
+ */
+interface CircuitBreakerEvent {
+  nodeType: string;
+  previousState: CircuitBreakerState;
+  newState: CircuitBreakerState;
+  timestamp: number;
+  failureCount?: number;
+}
+/**
+ * Callback type for circuit state change events.
+ */
+type CircuitBreakerEventHandler = (event: CircuitBreakerEvent) => Effect.Effect<void, never, never>;
+/**
+ * Default circuit breaker configuration values.
+ */
+declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: Required<Omit<CircuitBreakerConfig, "fallback">> & {
+  fallback: CircuitBreakerFallback;
+};
+//#endregion
+//#region src/types/upload-file.d.ts
 /**
  * Zod schema for validating UploadFile objects.
  *
@@ -50,108 +120,830 @@ declare const uploadFileSchema: z.ZodObject<{
  * 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")
+ * @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
+ *   }
+ * };
+ * ```
+ */
+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, string | number | boolean> | undefined;
+  creationDate?: string | undefined;
+  url?: string | undefined;
+  sizeIsDeferred?: boolean | undefined;
+  checksum?: string | undefined;
+  checksumAlgorithm?: string | undefined;
+};
+//#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>;
+//#endregion
+//#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/circuit-breaker-store.d.ts
+/**
+ * Creates a CircuitBreakerStore backed by any BaseKvStore.
+ *
+ * This adapter wraps a generic KV store to provide circuit breaker state
+ * storage. It handles:
+ * - JSON serialization of state data
+ * - Sliding window expiry (checked on read/increment)
+ * - Read-modify-write for increment operations
+ *
+ * Note: This implementation uses read-modify-write for increments, which
+ * may have race conditions under high concurrency. This is acceptable for
+ * circuit breakers as they tolerate eventual consistency.
+ *
+ * @param baseStore - The underlying KV store
+ * @returns A CircuitBreakerStore implementation
+ *
+ * @example
+ * ```typescript
+ * const baseStore = makeRedisBaseKvStore({ redis: redisClient });
+ * const cbStore = makeKvCircuitBreakerStore(baseStore);
+ *
+ * // Use the store
+ * yield* cbStore.incrementFailures("describe-image", 60000);
+ * ```
+ */
+declare function makeKvCircuitBreakerStore(baseStore: BaseKvStore): CircuitBreakerStore;
+/**
+ * Creates an in-memory CircuitBreakerStore.
+ *
+ * This implementation keeps all state in memory and is suitable for:
+ * - Single-instance deployments
+ * - Development and testing
+ * - Serverless functions (where state is ephemeral anyway)
+ *
+ * @returns A CircuitBreakerStore backed by in-memory Map
+ *
+ * @example
+ * ```typescript
+ * const cbStore = makeMemoryCircuitBreakerStore();
+ *
+ * // Use for testing
+ * yield* cbStore.incrementFailures("test-node", 60000);
+ * const state = yield* cbStore.getState("test-node");
+ * ```
+ */
+declare function makeMemoryCircuitBreakerStore(): CircuitBreakerStore;
+/**
+ * Effect Layer that provides a CircuitBreakerStore backed by the BaseKvStore.
+ *
+ * Use this layer when you want circuit breaker state to be distributed
+ * across multiple instances (e.g., in a cluster).
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cbStore = yield* CircuitBreakerStoreService;
+ *   // ...
+ * }).pipe(
+ *   Effect.provide(kvCircuitBreakerStoreLayer),
+ *   Effect.provide(redisKvStore({ redis: redisClient }))
+ * );
+ * ```
+ */
+declare const kvCircuitBreakerStoreLayer: Layer.Layer<CircuitBreakerStoreService, never, BaseKvStoreService>;
+/**
+ * Effect Layer that provides an in-memory CircuitBreakerStore.
+ *
+ * Use this layer for single-instance deployments, development, or testing.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cbStore = yield* CircuitBreakerStoreService;
+ *   // ...
+ * }).pipe(
+ *   Effect.provide(memoryCircuitBreakerStoreLayer)
+ * );
+ * ```
+ */
+declare const memoryCircuitBreakerStoreLayer: Layer.Layer<CircuitBreakerStoreService, never, never>;
+//#endregion
+//#region src/flow/distributed-circuit-breaker.d.ts
+/**
+ * Result of checking if a request is allowed.
+ */
+interface AllowRequestResult {
+  allowed: boolean;
+  state: CircuitBreakerStateValue;
+  failureCount: number;
+}
+/**
+ * Distributed circuit breaker that uses a store for state persistence.
+ *
+ * Unlike the in-memory CircuitBreaker, this implementation stores all state
+ * in a CircuitBreakerStore, allowing multiple instances to share circuit state.
+ *
+ * All operations are Effect-based since they may involve I/O.
  *
  * @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"
- * };
+ * const breaker = new DistributedCircuitBreaker(
+ *   "describe-image",
+ *   { enabled: true, failureThreshold: 5 },
+ *   store
+ * );
  *
- * // 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"
- *   }
- * };
+ * // Check if request is allowed
+ * const { allowed, state } = yield* breaker.allowRequest();
+ * if (!allowed) {
+ *   // Handle circuit open
+ * }
  *
- * // 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
- *   }
- * };
+ * // Record result
+ * try {
+ *   const result = yield* executeNode();
+ *   yield* breaker.recordSuccess();
+ *   return result;
+ * } catch (error) {
+ *   yield* breaker.recordFailure(error.message);
+ *   throw error;
+ * }
  * ```
  */
-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;
+declare class DistributedCircuitBreaker {
+  private eventHandler?;
+  readonly nodeType: string;
+  readonly config: Required<Omit<CircuitBreakerConfig, "fallback">> & {
+    fallback: CircuitBreakerFallback;
   };
-  size?: number | undefined;
-  metadata?: Record<string, string | number | boolean> | undefined;
-  creationDate?: string | undefined;
-  url?: string | undefined;
-  sizeIsDeferred?: boolean | undefined;
-  checksum?: string | undefined;
-  checksumAlgorithm?: string | undefined;
-};
+  readonly store: CircuitBreakerStore;
+  constructor(nodeType: string, config: CircuitBreakerConfig, store: CircuitBreakerStore);
+  /**
+   * Sets the event handler for state change notifications.
+   */
+  setEventHandler(handler: CircuitBreakerEventHandler): void;
+  /**
+   * Checks if a request is allowed through the circuit.
+   *
+   * This method reads state from the store, checks for time-based transitions,
+   * and returns whether the request should proceed.
+   */
+  allowRequest(): Effect.Effect<AllowRequestResult, UploadistaError>;
+  /**
+   * Gets the current circuit state from the store.
+   */
+  getState(): Effect.Effect<CircuitBreakerStateValue, UploadistaError>;
+  /**
+   * Gets the current failure count from the store.
+   */
+  getFailureCount(): Effect.Effect<number, UploadistaError>;
+  /**
+   * Records a successful execution.
+   *
+   * In half-open state, tracks successes toward closing the circuit.
+   * In closed state, resets the failure count.
+   */
+  recordSuccess(): Effect.Effect<void, UploadistaError>;
+  /**
+   * Records a failed execution.
+   *
+   * In closed state, increments failure count and may trip the circuit.
+   * In half-open state, immediately reopens the circuit.
+   */
+  recordFailure(_errorMessage: string): Effect.Effect<void, UploadistaError>;
+  /**
+   * Gets the fallback configuration.
+   */
+  getFallback(): CircuitBreakerFallback;
+  /**
+   * Resets the circuit breaker to closed state.
+   */
+  reset(): Effect.Effect<void, UploadistaError>;
+  /**
+   * Transitions to a new state.
+   */
+  private transitionTo;
+  /**
+   * Emits a state change event if handler is set.
+   */
+  private emitEvent;
+}
+/**
+ * Registry for managing distributed circuit breakers.
+ *
+ * Unlike the in-memory CircuitBreakerRegistry, this registry creates
+ * DistributedCircuitBreaker instances that share state via a store.
+ *
+ * @example
+ * ```typescript
+ * const store = makeKvCircuitBreakerStore(baseKvStore);
+ * const registry = new DistributedCircuitBreakerRegistry(store);
+ *
+ * const breaker = registry.getOrCreate("describe-image", {
+ *   enabled: true,
+ *   failureThreshold: 5
+ * });
+ * ```
+ */
+declare class DistributedCircuitBreakerRegistry {
+  readonly store: CircuitBreakerStore;
+  private breakers;
+  private eventHandler?;
+  constructor(store: CircuitBreakerStore);
+  /**
+   * Sets a global event handler for all circuit breakers.
+   */
+  setEventHandler(handler: CircuitBreakerEventHandler): void;
+  /**
+   * Gets an existing circuit breaker or creates a new one.
+   */
+  getOrCreate(nodeType: string, config: CircuitBreakerConfig): DistributedCircuitBreaker;
+  /**
+   * Gets an existing circuit breaker if it exists.
+   */
+  get(nodeType: string): DistributedCircuitBreaker | undefined;
+  /**
+   * Gets statistics for all circuit breakers from the store.
+   */
+  getAllStats(): Effect.Effect<Map<string, {
+    state: CircuitBreakerStateValue;
+    failureCount: number;
+  }>, UploadistaError>;
+  /**
+   * Resets all circuit breakers.
+   */
+  resetAll(): Effect.Effect<void, UploadistaError>;
+  /**
+   * Clears all circuit breakers from the local cache.
+   * Note: This does not clear state from the store.
+   */
+  clear(): void;
+}
 //#endregion
 //#region src/flow/node.d.ts
 /**
@@ -211,8 +1003,11 @@ type ConditionValue = string | number;
  * @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.nodeTypeId - Optional type ID from the registry (e.g., "storage-output-v1"). If provided, the node type must be registered.
+ * @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
  *
@@ -259,8 +1054,11 @@ declare function createFlowNode<Input, Output, TType extends NodeType = NodeType
   multiOutput,
   pausable,
   retry,
-  nodeTypeId,
-  keepOutput
+  inputTypeId,
+  outputTypeId,
+  keepOutput,
+  circuitBreaker,
+  nodeTypeId
 }: {
   id: string;
   name: string;
@@ -288,8 +1086,19 @@ declare function createFlowNode<Input, Output, TType extends NodeType = NodeType
     retryDelay?: number;
     exponentialBackoff?: boolean;
   };
-  nodeTypeId?: string;
+  /** 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>;
@@ -301,7 +1110,7 @@ declare function createFlowNode<Input, Output, TType extends NodeType = NodeType
  * 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)
+ * @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
@@ -351,6 +1160,18 @@ declare enum EventType {
   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.
@@ -526,6 +1347,77 @@ type FlowEventNodeResponse = {
   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.
  *
@@ -547,11 +1439,199 @@ type FlowEventNodeResponse = {
  *     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;
+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
 /**
@@ -570,6 +1650,8 @@ type NodeTypeMap = Record<string, {
  * @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 = {
@@ -577,8 +1659,17 @@ type FlowNodeData = {
   name: string;
   description: string;
   type: NodeType;
-  nodeTypeId: string;
+  /** 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;
 };
 /**
  * Built-in typed outputs with automatic TypeScript narrowing.
@@ -710,7 +1801,7 @@ type TypedOutput<T = unknown> = BuiltInTypedOutput | CustomTypedOutput<T>;
  *
  * 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 a `nodeTypeId`.
+ * by the node execution wrapper when a node is created with an `outputTypeId`.
  *
  * @example
  * ```typescript
@@ -847,6 +1938,8 @@ type FlowNode<TInput = unknown, TOutput = unknown, TError$1 = UploadistaError> =
     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.
@@ -913,6 +2006,104 @@ type NodeConnectionValidator = {
   validateConnection: (sourceNode: FlowNode<any, any>, targetNode: FlowNode<any, any>, edge: FlowEdge$1) => 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.
  *
@@ -985,6 +2176,58 @@ type FlowConfig<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema ext
     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.
@@ -1026,345 +2269,208 @@ type FlowConfig<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema ext
      *     // 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>;
-  };
-};
-//#endregion
-//#region src/flow/edge.d.ts
-/**
- * Represents a connection between two nodes in a flow, defining the data flow direction.
- *
- * Edges connect the output of a source node to the input of a target node,
- * enabling data to flow through the processing pipeline in a directed acyclic graph (DAG).
- */
-type FlowEdge = FlowEdge$1;
-/**
- * Creates a flow edge connecting two nodes in a processing pipeline.
- *
- * Edges define how data flows between nodes. The data output from the source node
- * becomes the input for the target node. For nodes with multiple inputs/outputs,
- * ports can be specified to route data to specific connections.
- *
- * @param config - Edge configuration
- * @param config.source - ID of the source node (data originates here)
- * @param config.target - ID of the target node (data flows to here)
- * @param config.sourcePort - Optional port name on the source node for multi-output nodes
- * @param config.targetPort - Optional port name on the target node for multi-input nodes
- *
- * @returns A FlowEdge object representing the connection
- *
- * @example
- * ```typescript
- * // Simple edge connecting two nodes
- * const edge = createFlowEdge({
- *   source: "input-1",
- *   target: "process-1"
- * });
- *
- * // Edge with ports for multi-input/output nodes
- * const portEdge = createFlowEdge({
- *   source: "multiplex-1",
- *   target: "merge-1",
- *   sourcePort: "out-a",
- *   targetPort: "in-1"
- * });
- * ```
- */
-declare function createFlowEdge({
-  source,
-  target,
-  sourcePort,
-  targetPort
-}: {
-  source: string;
-  target: string;
-  sourcePort?: string;
-  targetPort?: string;
-}): FlowEdge;
-//#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>;
-}
+     * }
+     * ```
+     */
+    onNodeOutput?: <TOutput>(context: {
+      output: TOutput;
+      nodeId: string;
+      flowId: string;
+      jobId: string;
+      storageId: string;
+      clientId: string | null;
+    }) => Effect.Effect<TOutput, UploadistaError, never> | Promise<TOutput>;
+  };
+};
 /**
- * Default JSON serialization helpers.
+ * Context provided to file naming functions and templates.
  *
- * These functions provide standard JSON serialization for use with TypedKvStore.
- * They work with any JSON-serializable type.
+ * 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
- * const store = new TypedKvStore<MyType>(
- *   baseStore,
- *   "mydata:",
- *   jsonSerializer.serialize,
- *   jsonSerializer.deserialize
- * );
+ * // Available in templates as {{variable}}
+ * const pattern = "{{baseName}}-{{width}}x{{height}}.{{extension}}";
+ * // Result: "photo-800x600.jpg"
  * ```
  */
-declare const jsonSerializer: {
-  serialize: <T>(data: T) => string;
-  deserialize: <T>(str: string) => T;
+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;
 };
-declare const BaseKvStoreService_base: Context.TagClass<BaseKvStoreService, "BaseKvStore", BaseKvStore>;
 /**
- * Effect-TS context tag for the base untyped KV store.
+ * Function type for custom file naming logic.
  *
- * This is the low-level store that storage adapter implementations provide.
- * Most application code should use typed stores like UploadFileKVStore instead.
+ * @param file - The UploadFile being processed
+ * @param context - Naming context with all available variables
+ * @returns The new filename (including extension)
  *
  * @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");
- * });
+ * const customRename: FileNamingFunction = (file, ctx) =>
+ *   `${ctx.flowId}-${ctx.baseName}-${ctx.timestamp}.${ctx.extension}`;
  * ```
  */
-declare class BaseKvStoreService extends BaseKvStoreService_base {}
-declare const UploadFileKVStore_base: Context.TagClass<UploadFileKVStore, "UploadFileKVStore", KvStore<UploadFile>>;
+type FileNamingFunction = (file: UploadFile, context: NamingContext) => string;
 /**
- * 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);
+ * Function type for generating auto-naming suffixes.
  *
- *   // 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.
+ * Each node type can define its own auto suffix generator that creates
+ * a descriptive suffix based on the processing parameters.
  *
- * This layer automatically wires up JSON serialization for UploadFile objects
- * with the "uploadista:upload-file:" key prefix.
+ * @param context - Naming context with all available variables
+ * @returns The suffix to append (without leading dash)
  *
  * @example
  * ```typescript
- * const program = Effect.gen(function* () {
- *   const kvStore = yield* UploadFileKVStore;
- *   // Use the store...
- * }).pipe(
- *   Effect.provide(uploadFileKvStore),
- *   Effect.provide(baseStoreLayer)
- * );
+ * // 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"
  * ```
  */
-declare const uploadFileKvStore: Layer.Layer<UploadFileKVStore, never, BaseKvStoreService>;
-declare const FlowJobKVStore_base: Context.TagClass<FlowJobKVStore, "FlowJobKVStore", KvStore<FlowJob>>;
+type AutoNamingSuffixGenerator = (context: NamingContext) => string;
 /**
- * Effect-TS context tag for the FlowJob typed KV store.
+ * Configuration for file naming behavior on a node.
  *
- * This provides type-safe storage for FlowJob metadata, tracking the
- * execution state of flow processing jobs.
+ * 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
- * const flowEffect = Effect.gen(function* () {
- *   const jobStore = yield* FlowJobKVStore;
+ * // Auto mode with smart suffix
+ * const autoNaming: FileNamingConfig = {
+ *   mode: 'auto',
+ *   autoSuffix: (ctx) => `${ctx.width}x${ctx.height}`
+ * };
  *
- *   // 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);
+ * // Custom mode with template
+ * const templateNaming: FileNamingConfig = {
+ *   mode: 'custom',
+ *   pattern: '{{baseName}}-{{nodeType}}.{{extension}}'
+ * };
  *
- *   // Retrieve and check status
- *   const retrieved = yield* jobStore.get("job123");
- *   return retrieved.status;
- * });
+ * // Custom mode with function
+ * const functionNaming: FileNamingConfig = {
+ *   mode: 'custom',
+ *   rename: (file, ctx) => `processed-${ctx.fileName}`
+ * };
  * ```
  */
-declare class FlowJobKVStore extends FlowJobKVStore_base {}
+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/edge.d.ts
 /**
- * Effect Layer that creates the FlowJobKVStore from a BaseKvStore.
+ * Represents a connection between two nodes in a flow, defining the data flow direction.
  *
- * This layer automatically wires up JSON serialization for FlowJob objects
- * with the "uploadista:flow-job:" key prefix.
+ * Edges connect the output of a source node to the input of a target node,
+ * enabling data to flow through the processing pipeline in a directed acyclic graph (DAG).
+ */
+type FlowEdge = FlowEdge$1;
+/**
+ * Creates a flow edge connecting two nodes in a processing pipeline.
+ *
+ * Edges define how data flows between nodes. The data output from the source node
+ * becomes the input for the target node. For nodes with multiple inputs/outputs,
+ * ports can be specified to route data to specific connections.
+ *
+ * @param config - Edge configuration
+ * @param config.source - ID of the source node (data originates here)
+ * @param config.target - ID of the target node (data flows to here)
+ * @param config.sourcePort - Optional port name on the source node for multi-output nodes
+ * @param config.targetPort - Optional port name on the target node for multi-input nodes
+ *
+ * @returns A FlowEdge object representing the connection
  *
  * @example
  * ```typescript
- * const program = Effect.gen(function* () {
- *   const jobStore = yield* FlowJobKVStore;
- *   // Use the store...
- * }).pipe(
- *   Effect.provide(flowJobKvStore),
- *   Effect.provide(baseStoreLayer)
- * );
+ * // Simple edge connecting two nodes
+ * const edge = createFlowEdge({
+ *   source: "input-1",
+ *   target: "process-1"
+ * });
+ *
+ * // Edge with ports for multi-input/output nodes
+ * const portEdge = createFlowEdge({
+ *   source: "multiplex-1",
+ *   target: "merge-1",
+ *   sourcePort: "out-a",
+ *   targetPort: "in-1"
+ * });
  * ```
  */
-declare const flowJobKvStore: Layer.Layer<FlowJobKVStore, never, BaseKvStoreService>;
+declare function createFlowEdge({
+  source,
+  target,
+  sourcePort,
+  targetPort
+}: {
+  source: string;
+  target: string;
+  sourcePort?: string;
+  targetPort?: string;
+}): FlowEdge;
 //#endregion
 //#region src/types/data-store.d.ts
 /**
@@ -1900,57 +3006,172 @@ type Flow<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z
  */
 declare function createFlowWithSchema<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TRequirements = never, TNodeError = never, TNodeRequirements = never>(config: FlowConfig<TFlowInputSchema, TFlowOutputSchema, TNodeError, TNodeRequirements>): Effect.Effect<Flow<TFlowInputSchema, TFlowOutputSchema, TRequirements>, TNodeError, TNodeRequirements>;
 //#endregion
-//#region src/flow/type-registry.d.ts
+//#region src/flow/input-type-registry.d.ts
 /**
- * Node type category - determines where the node appears in the flow.
+ * Defines a registered input type with its schema and metadata.
+ *
+ * Input type definitions describe how external clients interact with input nodes.
+ * Unlike output types, input types define the external interface (e.g., init/finalize
+ * operations for streaming uploads).
  *
- * - `input`: Nodes that receive data from external sources (e.g., file uploads)
- * - `output`: Nodes that produce final results (e.g., storage, webhooks, descriptions)
+ * @template TSchema - The Zod schema type for this input's data
+ *
+ * @property id - Unique identifier (e.g., "streaming-input-v1")
+ * @property schema - Zod schema for validating input data from clients
+ * @property version - Semantic version (e.g., "1.0.0") for tracking type evolution
+ * @property description - Human-readable explanation of what this input type does
  */
-type NodeTypeCategory = "input" | "output";
+interface InputTypeDefinition<TSchema = unknown> {
+  id: string;
+  schema: z.ZodSchema<TSchema>;
+  version: string;
+  description: string;
+}
 /**
- * Defines a registered node type with its schema and metadata.
+ * Result type for input validation operations.
  *
- * Node type definitions are registered globally and used to validate and type-narrow
- * flow results at runtime. Each definition includes:
- * - A unique identifier with versioning
- * - A category (input or output)
- * - A Zod schema for runtime validation
- * - A semantic version for evolution
- * - A human-readable description
+ * @template T - The expected type on successful validation
+ */
+type InputValidationResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: UploadistaError;
+};
+/**
+ * Registry for input node type definitions.
  *
- * @template TSchema - The Zod schema type for this node's data
+ * The InputTypeRegistry maintains a global registry of input types with their schemas
+ * and metadata. Input types describe how data enters the flow from external sources.
  *
- * @property id - Unique identifier (e.g., "storage-output-v1", "webhook-output-v1")
- * @property category - Whether this is an input or output node type
- * @property schema - Zod schema for validating data produced by this node type
- * @property version - Semantic version (e.g., "1.0.0") for tracking type evolution
- * @property description - Human-readable explanation of what this node type does
+ * @remarks
+ * - Use the exported `inputTypeRegistry` singleton instance
+ * - Types cannot be unregistered or modified after registration
+ * - Duplicate type IDs are rejected
  *
  * @example
  * ```typescript
- * const storageOutputDef: NodeTypeDefinition<z.infer<typeof uploadFileSchema>> = {
- *   id: "storage-output-v1",
- *   category: "output",
- *   schema: uploadFileSchema,
+ * // Register a new input type
+ * inputTypeRegistry.register({
+ *   id: "form-input-v1",
+ *   schema: formInputSchema,
  *   version: "1.0.0",
- *   description: "Storage output node that saves files to configured storage backend",
- * };
+ *   description: "Form-based file input",
+ * });
+ *
+ * // Check if type exists
+ * if (inputTypeRegistry.has("streaming-input-v1")) {
+ *   const def = inputTypeRegistry.get("streaming-input-v1");
+ * }
+ * ```
+ */
+declare class InputTypeRegistry {
+  private readonly types;
+  constructor();
+  /**
+   * Register a new input type in the registry.
+   *
+   * @template T - The TypeScript type inferred from the Zod schema
+   * @param definition - The complete type definition including schema and metadata
+   * @throws {UploadistaError} If a type with the same ID is already registered
+   */
+  register<T>(definition: InputTypeDefinition<T>): void;
+  /**
+   * Retrieve a registered type definition by its ID.
+   *
+   * @param id - The unique type identifier (e.g., "streaming-input-v1")
+   * @returns The type definition if found, undefined otherwise
+   */
+  get(id: string): InputTypeDefinition<unknown> | undefined;
+  /**
+   * List all registered input types.
+   *
+   * @returns Array of all input type definitions
+   */
+  list(): InputTypeDefinition<unknown>[];
+  /**
+   * Validate data against a registered type's schema.
+   *
+   * @template T - The expected TypeScript type after validation
+   * @param typeId - The ID of the registered type to validate against
+   * @param data - The data to validate
+   * @returns A result object with either the validated data or an error
+   */
+  validate<T>(typeId: string, data: unknown): InputValidationResult<T>;
+  /**
+   * Check if a type is registered.
+   *
+   * @param id - The unique type identifier to check
+   * @returns True if the type is registered, false otherwise
+   */
+  has(id: string): boolean;
+  /**
+   * Get the total number of registered types.
+   *
+   * @returns The count of registered types
+   */
+  size(): number;
+}
+/**
+ * Global singleton instance of the input type registry.
+ *
+ * Use this instance to register and access input node type definitions.
+ * Input types describe how data enters the flow from external sources.
+ *
+ * @example
+ * ```typescript
+ * import { inputTypeRegistry } from "@uploadista/core/flow";
+ *
+ * // Register a type
+ * inputTypeRegistry.register({
+ *   id: "my-input-v1",
+ *   schema: myInputSchema,
+ *   version: "1.0.0",
+ *   description: "My custom input type",
+ * });
+ *
+ * // Validate data
+ * const result = inputTypeRegistry.validate("my-input-v1", data);
  * ```
  */
-interface NodeTypeDefinition<TSchema = unknown> {
+declare const inputTypeRegistry: InputTypeRegistry;
+/**
+ * Validates flow input data against a registered input type.
+ *
+ * @param typeId - The registered type ID (e.g., "streaming-input-v1")
+ * @param data - The input data to validate
+ * @returns A validation result with either the typed data or an error
+ */
+declare function validateFlowInput<T = unknown>(typeId: string, data: unknown): InputValidationResult<T>;
+//#endregion
+//#region src/flow/output-type-registry.d.ts
+/**
+ * Defines a registered output type with its schema and metadata.
+ *
+ * Output type definitions describe the data shapes produced by nodes. This enables
+ * type-safe result consumption where clients can narrow types based on the
+ * `nodeType` field in results.
+ *
+ * @template TSchema - The Zod schema type for this output's data
+ *
+ * @property id - Unique identifier (e.g., "storage-output-v1", "ocr-output-v1")
+ * @property schema - Zod schema for validating output data
+ * @property version - Semantic version (e.g., "1.0.0") for tracking type evolution
+ * @property description - Human-readable explanation of what this output type contains
+ */
+interface OutputTypeDefinition<TSchema = unknown> {
   id: string;
-  category: NodeTypeCategory;
   schema: z.ZodSchema<TSchema>;
   version: string;
   description: string;
 }
 /**
- * Result type for validation operations.
+ * Result type for output validation operations.
  *
  * @template T - The expected type on successful validation
  */
-type ValidationResult<T> = {
+type OutputValidationResult<T> = {
   success: true;
   data: T;
 } | {
@@ -1958,221 +3179,112 @@ type ValidationResult<T> = {
   error: UploadistaError;
 };
 /**
- * Central registry for node type definitions.
+ * Registry for output node type definitions.
  *
- * The FlowTypeRegistry maintains a global registry of node types with their schemas
- * and metadata. It provides methods for:
- * - Registering new node types
- * - Retrieving type definitions
- * - Listing types by category
- * - Validating data against registered schemas
- *
- * The registry is immutable after registration - types cannot be modified or removed
- * once registered to prevent runtime errors.
+ * The OutputTypeRegistry maintains a global registry of output types with their schemas
+ * and metadata. Output types describe the data shapes that flow through the system
+ * and appear in results.
  *
  * @remarks
- * - This is a singleton - use the exported `flowTypeRegistry` instance
+ * - Use the exported `outputTypeRegistry` singleton instance
  * - Types cannot be unregistered or modified after registration
  * - Duplicate type IDs are rejected
- * - Version strings should follow semantic versioning
  *
  * @example
  * ```typescript
- * // Register a new type
- * flowTypeRegistry.register({
- *   id: "webhook-output-v1",
- *   category: "output",
- *   schema: webhookResponseSchema,
+ * // Register a new output type
+ * outputTypeRegistry.register({
+ *   id: "metadata-output-v1",
+ *   schema: metadataSchema,
  *   version: "1.0.0",
- *   description: "HTTP webhook notification output",
+ *   description: "File metadata extraction output",
  * });
  *
- * // Retrieve a type definition
- * const def = flowTypeRegistry.get("webhook-output-v1");
- * if (def) {
- *   console.log(def.description);
- * }
- *
- * // List all output types
- * const outputTypes = flowTypeRegistry.listByCategory("output");
- * console.log(outputTypes.map(t => t.id));
- *
- * // Validate data
- * const result = flowTypeRegistry.validate("webhook-output-v1", data);
+ * // Validate result data
+ * const result = outputTypeRegistry.validate("storage-output-v1", data);
  * if (result.success) {
- *   // data is now typed according to the schema
- *   processWebhookResponse(result.data);
+ *   console.log(result.data.url);
  * }
  * ```
  */
-declare class FlowTypeRegistry {
+declare class OutputTypeRegistry {
   private readonly types;
   constructor();
   /**
-   * Register a new node type in the registry.
-   *
-   * Once registered, a type cannot be modified or removed. Attempting to register
-   * a type with a duplicate ID will throw an error.
+   * Register a new output type in the registry.
    *
    * @template T - The TypeScript type inferred from the Zod schema
    * @param definition - The complete type definition including schema and metadata
    * @throws {UploadistaError} If a type with the same ID is already registered
-   *
-   * @example
-   * ```typescript
-   * import { z } from "zod";
-   *
-   * flowTypeRegistry.register({
-   *   id: "description-output-v1",
-   *   category: "output",
-   *   schema: z.object({
-   *     description: z.string(),
-   *     confidence: z.number().min(0).max(1),
-   *     tags: z.array(z.string()).optional(),
-   *   }),
-   *   version: "1.0.0",
-   *   description: "AI-generated image description with confidence score",
-   * });
-   * ```
    */
-  register<T>(definition: NodeTypeDefinition<T>): void;
+  register<T>(definition: OutputTypeDefinition<T>): void;
   /**
    * Retrieve a registered type definition by its ID.
    *
    * @param id - The unique type identifier (e.g., "storage-output-v1")
    * @returns The type definition if found, undefined otherwise
-   *
-   * @example
-   * ```typescript
-   * const def = flowTypeRegistry.get("storage-output-v1");
-   * if (def) {
-   *   console.log(`Found ${def.description} (v${def.version})`);
-   * } else {
-   *   console.warn("Type not registered");
-   * }
-   * ```
    */
-  get(id: string): NodeTypeDefinition<unknown> | undefined;
+  get(id: string): OutputTypeDefinition<unknown> | undefined;
   /**
-   * List all registered types in a specific category.
-   *
-   * @param category - The node category to filter by ("input" or "output")
-   * @returns Array of type definitions in the specified category
+   * List all registered output types.
    *
-   * @example
-   * ```typescript
-   * // List all registered output types
-   * const outputTypes = flowTypeRegistry.listByCategory("output");
-   * console.log("Available output types:");
-   * for (const type of outputTypes) {
-   *   console.log(`- ${type.id}: ${type.description}`);
-   * }
-   * ```
+   * @returns Array of all output type definitions
    */
-  listByCategory(category: NodeTypeCategory): NodeTypeDefinition<unknown>[];
+  list(): OutputTypeDefinition<unknown>[];
   /**
    * Validate data against a registered type's schema.
    *
-   * This method performs runtime validation using the Zod schema associated with
-   * the type. If validation succeeds, the data is returned with proper typing.
-   * If validation fails, an UploadistaError is returned with details.
-   *
    * @template T - The expected TypeScript type after validation
    * @param typeId - The ID of the registered type to validate against
    * @param data - The data to validate
    * @returns A result object with either the validated data or an error
-   *
-   * @example
-   * ```typescript
-   * const result = flowTypeRegistry.validate("storage-output-v1", unknownData);
-   *
-   * if (result.success) {
-   *   // TypeScript knows result.data is an UploadFile
-   *   console.log(`File stored at: ${result.data.url}`);
-   * } else {
-   *   console.error(`Validation failed: ${result.error.body}`);
-   * }
-   * ```
    */
-  validate<T>(typeId: string, data: unknown): ValidationResult<T>;
+  validate<T>(typeId: string, data: unknown): OutputValidationResult<T>;
   /**
    * Check if a type is registered.
    *
    * @param id - The unique type identifier to check
    * @returns True if the type is registered, false otherwise
-   *
-   * @example
-   * ```typescript
-   * if (flowTypeRegistry.has("custom-output-v1")) {
-   *   console.log("Custom output type is available");
-   * }
-   * ```
    */
   has(id: string): boolean;
   /**
    * Get the total number of registered types.
    *
    * @returns The count of registered types
-   *
-   * @example
-   * ```typescript
-   * console.log(`Registry contains ${flowTypeRegistry.size()} types`);
-   * ```
    */
   size(): number;
 }
 /**
- * Global singleton instance of the flow type registry.
+ * Global singleton instance of the output type registry.
  *
- * Use this instance to register and access node type definitions throughout
- * your application. The registry is initialized once and shared globally.
+ * Use this instance to register and access output node type definitions.
+ * Output types describe the data shapes produced by nodes and used in results.
  *
  * @example
  * ```typescript
- * import { flowTypeRegistry } from "@uploadista/core/flow";
+ * import { outputTypeRegistry } from "@uploadista/core/flow";
  *
  * // Register a type
- * flowTypeRegistry.register({
+ * outputTypeRegistry.register({
  *   id: "my-output-v1",
- *   category: "output",
- *   schema: mySchema,
+ *   schema: myOutputSchema,
  *   version: "1.0.0",
  *   description: "My custom output type",
  * });
  *
- * // Validate data
- * const result = flowTypeRegistry.validate("my-output-v1", data);
+ * // Validate result data
+ * const result = outputTypeRegistry.validate("my-output-v1", data);
  * ```
  */
-declare const flowTypeRegistry: FlowTypeRegistry;
+declare const outputTypeRegistry: OutputTypeRegistry;
 /**
- * Validates flow input data against a registered node type.
- *
- * This helper function looks up the node type by ID and validates the provided
- * data against its schema. It's specifically designed for input validation
- * before flow execution.
+ * Validates flow output data against a registered output type.
  *
- * @param typeId - The registered type ID (e.g., "streaming-input-v1")
- * @param data - The input data to validate
+ * @param typeId - The registered type ID (e.g., "storage-output-v1")
+ * @param data - The output data to validate
  * @returns A validation result with either the typed data or an error
- *
- * @example
- * ```typescript
- * import { validateFlowInput } from "@uploadista/core/flow";
- *
- * const result = validateFlowInput("streaming-input-v1", {
- *   operation: "url",
- *   url: "https://example.com/image.jpg"
- * });
- *
- * if (result.success) {
- *   console.log("Valid input:", result.data);
- * } else {
- *   console.error("Validation error:", result.error);
- * }
- * ```
  */
-declare function validateFlowInput<T = unknown>(typeId: string, data: unknown): ValidationResult<T>;
+declare function validateFlowOutput<T = unknown>(typeId: string, data: unknown): OutputValidationResult<T>;
 //#endregion
 //#region src/flow/node-types/index.d.ts
 /**
@@ -2183,11 +3295,12 @@ declare function validateFlowInput<T = unknown>(typeId: string, data: unknown):
  *
  * @example
  * ```typescript
- * import { STREAMING_INPUT_TYPE_ID } from "@uploadista/core/flow";
+ * import { STREAMING_INPUT_TYPE_ID, STORAGE_OUTPUT_TYPE_ID } from "@uploadista/core/flow";
  *
  * const inputNode = createFlowNode({
  *   // ... other config
- *   nodeTypeId: STREAMING_INPUT_TYPE_ID
+ *   inputTypeId: STREAMING_INPUT_TYPE_ID,
+ *   outputTypeId: STORAGE_OUTPUT_TYPE_ID,
  * });
  * ```
  */
@@ -2893,6 +4006,154 @@ declare class FlowEventEmitter extends FlowEventEmitter_base {}
  */
 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.
@@ -3218,7 +4479,7 @@ declare function createUploadServer(): Effect.Effect<{
   getCapabilities: (storageId: string, clientId: string | null) => Effect.Effect<DataStoreCapabilities, UploadistaError, never>;
   subscribeToUploadEvents: (uploadId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError, never>;
   unsubscribeFromUploadEvents: (uploadId: string) => Effect.Effect<void, UploadistaError, never>;
-}, never, UploadFileDataStores | UploadFileKVStore | UploadEventEmitter | GenerateId>;
+}, never, GenerateId | UploadFileDataStores | UploadFileKVStore | UploadEventEmitter>;
 /**
  * Pre-built UploadServer Effect Layer.
  *
@@ -3249,7 +4510,7 @@ declare function createUploadServer(): Effect.Effect<{
  * }).pipe(Effect.provide(fullUploadSystem));
  * ```
  */
-declare const uploadServer: Layer.Layer<UploadServer, never, UploadFileDataStores | UploadFileKVStore | UploadEventEmitter | GenerateId>;
+declare const uploadServer: Layer.Layer<UploadServer, never, GenerateId | UploadFileDataStores | UploadFileKVStore | UploadEventEmitter>;
 //#endregion
 //#region src/upload/upload-strategy-negotiator.d.ts
 /**
@@ -3931,10 +5192,200 @@ declare function createInputNode(id: string, params?: InputNodeParams, options?:
     retryDelay?: number;
     exponentialBackoff?: boolean;
   };
+  circuitBreaker?: FlowCircuitBreakerConfig;
 } & {
   type: NodeType.input;
 }, UploadistaError, UploadServer>;
 //#endregion
+//#region src/flow/types/flow-file.d.ts
+/**
+ * Conditional execution rules for flow nodes.
+ *
+ * Conditions allow nodes to execute conditionally based on file properties or metadata.
+ * They are evaluated before node execution and can skip nodes that don't match.
+ *
+ * @module flow/types/flow-file
+ * @see {@link FlowNode} for how conditions are used in nodes
+ *
+ * @example
+ * ```typescript
+ * // Only process images larger than 1MB
+ * const condition: FlowCondition = {
+ *   field: "size",
+ *   operator: "greaterThan",
+ *   value: 1024 * 1024
+ * };
+ *
+ * // Only process JPEG images
+ * const jpegCondition: FlowCondition = {
+ *   field: "mimeType",
+ *   operator: "startsWith",
+ *   value: "image/jpeg"
+ * };
+ * ```
+ */
+/**
+ * Represents a conditional rule for node execution.
+ *
+ * @property field - The file property to check
+ * @property operator - The comparison operator to apply
+ * @property value - The value to compare against
+ *
+ * @remarks
+ * - Fields can check file metadata (mimeType, size) or image properties (width, height)
+ * - String operators (contains, startsWith) work with string values
+ * - Numeric operators (greaterThan, lessThan) work with numeric values
+ * - The extension field checks the file extension without the dot
+ */
+type FlowCondition = {
+  field: "mimeType" | "size" | "width" | "height" | "extension";
+  operator: "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "startsWith";
+  value: string | number;
+};
+//#endregion
+//#region src/flow/types/type-utils.d.ts
+/**
+ * Extracts the service type from an Effect Layer.
+ *
+ * Given a Layer that provides a service, this type utility extracts
+ * the service type from the Layer's type signature.
+ *
+ * @template T - The Layer type to extract from
+ * @returns The service type provided by the layer, or never if T is not a Layer
+ *
+ * @example
+ * ```typescript
+ * type MyLayer = Layer.Layer<ServiceA, never, never>;
+ * type Service = ExtractLayerService<MyLayer>;
+ * // Service = ServiceA
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { ImagePluginLayer } from '@uploadista/core';
+ *
+ * type ImageService = ExtractLayerService<ImagePluginLayer>;
+ * // ImageService = ImagePlugin
+ * ```
+ */
+type ExtractLayerService<T, TError$1 = never, TRequirements = never> = T extends Layer.Layer<infer S, TError$1, TRequirements> ? S : never;
+/**
+ * Extracts all service types from a tuple of layers and returns them as a union.
+ *
+ * This type recursively processes a tuple of Layer types and extracts all
+ * the services they provide, combining them into a single union type.
+ *
+ * @template T - A readonly tuple of Layer types
+ * @returns A union of all service types provided by the layers, or never for empty tuples
+ *
+ * @example
+ * ```typescript
+ * type Layers = [
+ *   Layer.Layer<ServiceA, never, never>,
+ *   Layer.Layer<ServiceB, never, never>,
+ *   Layer.Layer<ServiceC, never, never>
+ * ];
+ * type Services = ExtractLayerServices<Layers>;
+ * // Services = ServiceA | ServiceB | ServiceC
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { ImagePluginLayer, ZipPluginLayer } from '@uploadista/core';
+ *
+ * type PluginLayers = [ImagePluginLayer, ZipPluginLayer];
+ * type AllServices = ExtractLayerServices<PluginLayers>;
+ * // AllServices = ImagePlugin | ZipPlugin
+ * ```
+ *
+ * @example
+ * ```typescript
+ * type EmptyLayers = [];
+ * type NoServices = ExtractLayerServices<EmptyLayers>;
+ * // NoServices = never
+ * ```
+ */
+type ExtractLayerServices<T extends readonly Layer.Layer<any, any, any>[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends Layer.Layer<infer S, any, any> ? S : never }[number];
+/**
+ * Unwraps an Effect type to extract its success value type.
+ *
+ * If the input type is an Effect, this extracts the success type (first type parameter).
+ * If the input is not an Effect, it returns the type unchanged.
+ *
+ * @template T - The type to resolve, potentially an Effect
+ * @returns The success type if T is an Effect, otherwise T
+ *
+ * @example
+ * ```typescript
+ * type MyEffect = Effect.Effect<string, Error, never>;
+ * type Result = ResolveEffect<MyEffect>;
+ * // Result = string
+ * ```
+ *
+ * @example
+ * ```typescript
+ * type NonEffect = { data: string };
+ * type Result = ResolveEffect<NonEffect>;
+ * // Result = { data: string }
+ * ```
+ */
+type ResolveEffect<T> = T extends Effect.Effect<infer S, any, any> ? S : T;
+/**
+ * Extracts the error type from an Effect.
+ *
+ * Given an Effect type, this utility extracts the error type
+ * (second type parameter) from the Effect's type signature.
+ *
+ * @template T - The Effect type to extract from
+ * @returns The error type of the Effect, or never if T is not an Effect
+ *
+ * @example
+ * ```typescript
+ * type MyEffect = Effect.Effect<string, ValidationError, never>;
+ * type ErrorType = ExtractEffectError<MyEffect>;
+ * // ErrorType = ValidationError
+ * ```
+ *
+ * @example
+ * ```typescript
+ * type SafeEffect = Effect.Effect<number, never, SomeService>;
+ * type ErrorType = ExtractEffectError<SafeEffect>;
+ * // ErrorType = never (no errors possible)
+ * ```
+ */
+type ExtractEffectError<T> = T extends Effect.Effect<any, infer E, any> ? E : never;
+/**
+ * Extracts the requirements (context) type from an Effect.
+ *
+ * Given an Effect type, this utility extracts the requirements type
+ * (third type parameter) from the Effect's type signature. This represents
+ * the services that must be provided for the Effect to run.
+ *
+ * @template T - The Effect type to extract from
+ * @returns The requirements type of the Effect, or never if T is not an Effect
+ *
+ * @example
+ * ```typescript
+ * type MyEffect = Effect.Effect<string, Error, Database | Logger>;
+ * type Requirements = ExtractEffectRequirements<MyEffect>;
+ * // Requirements = Database | Logger
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin, ZipPlugin } from '@uploadista/core';
+ *
+ * type ProcessEffect = Effect.Effect<
+ *   ProcessedImage,
+ *   ProcessError,
+ *   ImagePlugin | ZipPlugin
+ * >;
+ * type Needed = ExtractEffectRequirements<ProcessEffect>;
+ * // Needed = ImagePlugin | ZipPlugin
+ * ```
+ */
+type ExtractEffectRequirements<T> = T extends Effect.Effect<any, any, infer R> ? R : never;
+//#endregion
 //#region src/flow/nodes/transform-node.d.ts
 /**
  * Configuration object for creating a transform node.
@@ -3946,14 +5397,44 @@ interface TransformNodeConfig {
   name: string;
   /** Description of what the node does */
   description: string;
-  /** Optional node type ID for result type registration */
-  nodeTypeId?: string;
+  /** Optional output type ID from outputTypeRegistry for result type registration */
+  outputTypeId?: string;
   /**
    * Whether to keep this node's output as a flow result even if it has outgoing edges.
    * When true, the node's output will be included in the final flow outputs alongside topology sinks.
    * Defaults to false.
    */
   keepOutput?: boolean;
+  /**
+   * Optional file naming configuration.
+   * - undefined: Preserve original filename (backward compatible)
+   * - mode: 'auto': Generate smart suffix based on node type
+   * - mode: 'custom': Use template pattern or rename function
+   */
+  naming?: FileNamingConfig;
+  /**
+   * Node type identifier used for auto-naming context.
+   * Defaults to "transform" if not specified.
+   */
+  nodeType?: string;
+  /**
+   * Stable node type identifier for circuit breaker configuration.
+   * Used to share circuit breaker state across nodes of the same type
+   * and for nodeTypeOverrides in flow config.
+   * Example: "describe-image", "remove-background", "scan-virus"
+   */
+  nodeTypeId?: string;
+  /**
+   * Additional variables to include in the naming context.
+   * These are merged with the base context (flowId, jobId, etc.)
+   * and can be used in templates.
+   */
+  namingVars?: Record<string, string | number | undefined>;
+  /**
+   * Circuit breaker configuration for resilience against external service failures.
+   * Overrides flow-level circuit breaker defaults for this node.
+   */
+  circuitBreaker?: FlowCircuitBreakerConfig;
   /** Function that transforms file bytes */
   transform: (bytes: Uint8Array, file: UploadFile) => Effect.Effect<Uint8Array | {
     bytes: Uint8Array;
@@ -4016,8 +5497,13 @@ declare function createTransformNode({
   id,
   name,
   description,
-  nodeTypeId,
+  outputTypeId,
   keepOutput,
+  naming,
+  nodeType: namingNodeType,
+  nodeTypeId,
+  namingVars,
+  circuitBreaker,
   transform
 }: TransformNodeConfig): Effect.Effect<FlowNodeData & {
   inputSchema: zod0.ZodType<UploadFile, unknown, zod_v4_core0.$ZodTypeInternals<UploadFile, unknown>>;
@@ -4043,6 +5529,7 @@ declare function createTransformNode({
     retryDelay?: number;
     exponentialBackoff?: boolean;
   };
+  circuitBreaker?: FlowCircuitBreakerConfig;
 } & {
   type: NodeType;
 }, UploadistaError, UploadServer>;
@@ -5405,6 +6892,20 @@ declare const removeBackgroundParamsSchema: z.ZodObject<{
 type RemoveBackgroundParams = z.infer<typeof removeBackgroundParamsSchema>;
 //#endregion
 //#region src/flow/type-guards.d.ts
+/**
+ * A narrowed typed output with a specific node type and data type.
+ * Unlike TypedOutput<T>, this type has a required nodeType field and
+ * excludes BuiltInTypedOutput from the union, providing better type narrowing.
+ *
+ * @template T - The TypeScript type of the output data
+ * @template TNodeType - The literal string type of the node type ID
+ */
+type NarrowedTypedOutput<T, TNodeType extends string = string> = {
+  nodeType: TNodeType;
+  data: T;
+  nodeId: string;
+  timestamp: string;
+};
 /**
  * Factory function to create type guards for specific node types.
  *
@@ -5413,8 +6914,9 @@ type RemoveBackgroundParams = z.infer<typeof removeBackgroundParamsSchema>;
  * narrowing of TypedOutput objects in TypeScript.
  *
  * @template T - The expected TypeScript type after narrowing
+ * @template TNodeType - The literal string type of the node type ID
  * @param typeId - The registered type ID to check against (e.g., "storage-output-v1")
- * @returns A type guard function that narrows TypedOutput to TypedOutput<T>
+ * @returns A type guard function that narrows TypedOutput to NarrowedTypedOutput<T, TNodeType>
  *
  * @example
  * ```typescript
@@ -5439,7 +6941,7 @@ type RemoveBackgroundParams = z.infer<typeof removeBackgroundParamsSchema>;
  * }
  * ```
  */
-declare function createTypeGuard<T>(typeId: string): (output: TypedOutput) => output is TypedOutput<T>;
+declare function createTypeGuard<T, TNodeType extends string = string>(typeId: TNodeType): (output: TypedOutput) => output is NarrowedTypedOutput<T, TNodeType>;
 /**
  * Type guard for UploadFile objects.
  *
@@ -5481,7 +6983,7 @@ declare function isUploadFile(value: unknown): value is UploadFile;
  * }
  * ```
  */
-declare const isStorageOutput: (output: TypedOutput) => output is TypedOutput<UploadFile>;
+declare const isStorageOutput: (output: TypedOutput) => output is NarrowedTypedOutput<UploadFile, string>;
 /**
  * Type guard for OCR output nodes.
  *
@@ -5502,12 +7004,12 @@ declare const isStorageOutput: (output: TypedOutput) => output is TypedOutput<Up
  * }
  * ```
  */
-declare const isOcrOutput: (output: TypedOutput) => output is TypedOutput<{
+declare const isOcrOutput: (output: TypedOutput) => output is NarrowedTypedOutput<{
   extractedText: string;
   format: "markdown" | "plain" | "structured";
   taskType: "convertToMarkdown" | "freeOcr" | "parseFigure" | "locateObject";
   confidence?: number | undefined;
-}>;
+}, string>;
 /**
  * Type guard for image description output nodes.
  *
@@ -5527,11 +7029,11 @@ declare const isOcrOutput: (output: TypedOutput) => output is TypedOutput<{
  * }
  * ```
  */
-declare const isImageDescriptionOutput: (output: TypedOutput) => output is TypedOutput<{
+declare const isImageDescriptionOutput: (output: TypedOutput) => output is NarrowedTypedOutput<{
   description: string;
   confidence?: number | undefined;
   metadata?: Record<string, unknown> | undefined;
-}>;
+}, string>;
 /**
  * Filter an array of outputs to only those matching a specific type.
  *
@@ -5539,7 +7041,7 @@ declare const isImageDescriptionOutput: (output: TypedOutput) => output is Typed
  * properly typed array of results. It's useful for extracting specific
  * output types from multi-output flows.
  *
- * @template T - The expected output data type
+ * @template TOutput - The expected narrowed output type
  * @param outputs - Array of typed outputs to filter
  * @param typeGuard - Type guard function to use for filtering
  * @returns Array of outputs that match the type guard, properly typed
@@ -5560,7 +7062,7 @@ declare const isImageDescriptionOutput: (output: TypedOutput) => output is Typed
  * }
  * ```
  */
-declare function filterOutputsByType<T>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TypedOutput<T>): TypedOutput<T>[];
+declare function filterOutputsByType<TOutput extends TypedOutput>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TOutput): TOutput[];
 /**
  * Get a single output of a specific type from an array of outputs.
  *
@@ -5568,7 +7070,7 @@ declare function filterOutputsByType<T>(outputs: TypedOutput[], typeGuard: (outp
  * It throws an error if no outputs match or if multiple outputs match,
  * ensuring the caller receives exactly the expected result.
  *
- * @template T - The expected output data type
+ * @template TOutput - The expected narrowed output type
  * @param outputs - Array of typed outputs to search
  * @param typeGuard - Type guard function to use for matching
  * @returns The single matching output, properly typed
@@ -5595,7 +7097,7 @@ declare function filterOutputsByType<T>(outputs: TypedOutput[], typeGuard: (outp
  * }
  * ```
  */
-declare function getSingleOutputByType<T>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TypedOutput<T>): Effect.Effect<TypedOutput<T>, UploadistaError>;
+declare function getSingleOutputByType<TOutput extends TypedOutput>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TOutput): Effect.Effect<TOutput, UploadistaError>;
 /**
  * Get the first output of a specific type, if any exists.
  *
@@ -5603,7 +7105,7 @@ declare function getSingleOutputByType<T>(outputs: TypedOutput[], typeGuard: (ou
  * match, and returns the first match if multiple outputs exist. This is useful
  * when you want a more lenient matching strategy.
  *
- * @template T - The expected output data type
+ * @template TOutput - The expected narrowed output type
  * @param outputs - Array of typed outputs to search
  * @param typeGuard - Type guard function to use for matching
  * @returns The first matching output, or undefined if none match
@@ -5624,7 +7126,7 @@ declare function getSingleOutputByType<T>(outputs: TypedOutput[], typeGuard: (ou
  * }
  * ```
  */
-declare function getFirstOutputByType<T>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TypedOutput<T>): TypedOutput<T> | undefined;
+declare function getFirstOutputByType<TOutput extends TypedOutput>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TOutput): TOutput | undefined;
 /**
  * Get an output by its node ID.
  *
@@ -5653,7 +7155,7 @@ declare function getOutputByNodeId(outputs: TypedOutput[], nodeId: string): Type
  * Simple predicate function to check if at least one output of a given
  * type exists in the results.
  *
- * @template T - The expected output data type
+ * @template TOutput - The expected narrowed output type
  * @param outputs - Array of typed outputs to check
  * @param typeGuard - Type guard function to use for checking
  * @returns True if at least one output matches the type guard
@@ -5669,7 +7171,7 @@ declare function getOutputByNodeId(outputs: TypedOutput[], nodeId: string): Type
  * }
  * ```
  */
-declare function hasOutputOfType<T>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TypedOutput<T>): boolean;
+declare function hasOutputOfType<TOutput extends TypedOutput>(outputs: TypedOutput[], typeGuard: (output: TypedOutput) => output is TOutput): boolean;
 /**
  * Type guard for init operation (streaming file upload initialization).
  *
@@ -5701,247 +7203,58 @@ declare function isInitOperation(data: InputData): data is Extract<InputData, {
  *
  * @example
  * ```typescript
- * if (isFinalizeOperation(inputData)) {
- *   console.log("Upload ID:", inputData.uploadId);
- * }
- * ```
- */
-declare function isFinalizeOperation(data: InputData): data is Extract<InputData, {
-  operation: "finalize";
-}>;
-/**
- * Type guard for URL operation (direct file fetch from URL).
- *
- * Checks if the input data is a URL operation that fetches a file
- * directly from an external URL.
- *
- * @param data - Input data to check
- * @returns True if data is a URL operation
- *
- * @example
- * ```typescript
- * if (isUrlOperation(inputData)) {
- *   console.log("Fetching from:", inputData.url);
- *   console.log("Optional storage:", inputData.storageId);
- * }
- * ```
- */
-declare function isUrlOperation(data: InputData): data is Extract<InputData, {
-  operation: "url";
-}>;
-/**
- * Type guard for upload operations (init or url).
- *
- * Checks if the input data is either an init or URL operation (i.e., operations
- * that trigger new uploads, as opposed to finalize which completes an existing upload).
- *
- * @param data - Input data to check
- * @returns True if data is an init or URL operation
- *
- * @example
- * ```typescript
- * if (isUploadOperation(inputData)) {
- *   // This is a new upload, not a finalization
- *   if (isInitOperation(inputData)) {
- *     console.log("Streaming upload");
- *   } else {
- *     console.log("URL fetch");
- *   }
- * }
- * ```
- */
-declare function isUploadOperation(data: InputData): data is Extract<InputData, {
-  operation: "init" | "url";
-}>;
-//#endregion
-//#region src/flow/types/flow-file.d.ts
-/**
- * Conditional execution rules for flow nodes.
- *
- * Conditions allow nodes to execute conditionally based on file properties or metadata.
- * They are evaluated before node execution and can skip nodes that don't match.
- *
- * @module flow/types/flow-file
- * @see {@link FlowNode} for how conditions are used in nodes
- *
- * @example
- * ```typescript
- * // Only process images larger than 1MB
- * const condition: FlowCondition = {
- *   field: "size",
- *   operator: "greaterThan",
- *   value: 1024 * 1024
- * };
- *
- * // Only process JPEG images
- * const jpegCondition: FlowCondition = {
- *   field: "mimeType",
- *   operator: "startsWith",
- *   value: "image/jpeg"
- * };
- * ```
- */
-/**
- * Represents a conditional rule for node execution.
- *
- * @property field - The file property to check
- * @property operator - The comparison operator to apply
- * @property value - The value to compare against
- *
- * @remarks
- * - Fields can check file metadata (mimeType, size) or image properties (width, height)
- * - String operators (contains, startsWith) work with string values
- * - Numeric operators (greaterThan, lessThan) work with numeric values
- * - The extension field checks the file extension without the dot
- */
-type FlowCondition = {
-  field: "mimeType" | "size" | "width" | "height" | "extension";
-  operator: "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "startsWith";
-  value: string | number;
-};
-//#endregion
-//#region src/flow/types/type-utils.d.ts
-/**
- * Extracts the service type from an Effect Layer.
- *
- * Given a Layer that provides a service, this type utility extracts
- * the service type from the Layer's type signature.
- *
- * @template T - The Layer type to extract from
- * @returns The service type provided by the layer, or never if T is not a Layer
- *
- * @example
- * ```typescript
- * type MyLayer = Layer.Layer<ServiceA, never, never>;
- * type Service = ExtractLayerService<MyLayer>;
- * // Service = ServiceA
- * ```
- *
- * @example
- * ```typescript
- * import { ImagePluginLayer } from '@uploadista/core';
- *
- * type ImageService = ExtractLayerService<ImagePluginLayer>;
- * // ImageService = ImagePlugin
- * ```
- */
-type ExtractLayerService<T, TError$1 = never, TRequirements = never> = T extends Layer.Layer<infer S, TError$1, TRequirements> ? S : never;
-/**
- * Extracts all service types from a tuple of layers and returns them as a union.
- *
- * This type recursively processes a tuple of Layer types and extracts all
- * the services they provide, combining them into a single union type.
- *
- * @template T - A readonly tuple of Layer types
- * @returns A union of all service types provided by the layers, or never for empty tuples
- *
- * @example
- * ```typescript
- * type Layers = [
- *   Layer.Layer<ServiceA, never, never>,
- *   Layer.Layer<ServiceB, never, never>,
- *   Layer.Layer<ServiceC, never, never>
- * ];
- * type Services = ExtractLayerServices<Layers>;
- * // Services = ServiceA | ServiceB | ServiceC
- * ```
- *
- * @example
- * ```typescript
- * import { ImagePluginLayer, ZipPluginLayer } from '@uploadista/core';
- *
- * type PluginLayers = [ImagePluginLayer, ZipPluginLayer];
- * type AllServices = ExtractLayerServices<PluginLayers>;
- * // AllServices = ImagePlugin | ZipPlugin
- * ```
- *
- * @example
- * ```typescript
- * type EmptyLayers = [];
- * type NoServices = ExtractLayerServices<EmptyLayers>;
- * // NoServices = never
- * ```
- */
-type ExtractLayerServices<T extends readonly Layer.Layer<any, any, any>[]> = T extends readonly [] ? never : { [K in keyof T]: T[K] extends Layer.Layer<infer S, any, any> ? S : never }[number];
-/**
- * Unwraps an Effect type to extract its success value type.
- *
- * If the input type is an Effect, this extracts the success type (first type parameter).
- * If the input is not an Effect, it returns the type unchanged.
- *
- * @template T - The type to resolve, potentially an Effect
- * @returns The success type if T is an Effect, otherwise T
- *
- * @example
- * ```typescript
- * type MyEffect = Effect.Effect<string, Error, never>;
- * type Result = ResolveEffect<MyEffect>;
- * // Result = string
- * ```
- *
- * @example
- * ```typescript
- * type NonEffect = { data: string };
- * type Result = ResolveEffect<NonEffect>;
- * // Result = { data: string }
- * ```
- */
-type ResolveEffect<T> = T extends Effect.Effect<infer S, any, any> ? S : T;
-/**
- * Extracts the error type from an Effect.
- *
- * Given an Effect type, this utility extracts the error type
- * (second type parameter) from the Effect's type signature.
- *
- * @template T - The Effect type to extract from
- * @returns The error type of the Effect, or never if T is not an Effect
- *
- * @example
- * ```typescript
- * type MyEffect = Effect.Effect<string, ValidationError, never>;
- * type ErrorType = ExtractEffectError<MyEffect>;
- * // ErrorType = ValidationError
- * ```
- *
- * @example
- * ```typescript
- * type SafeEffect = Effect.Effect<number, never, SomeService>;
- * type ErrorType = ExtractEffectError<SafeEffect>;
- * // ErrorType = never (no errors possible)
+ * if (isFinalizeOperation(inputData)) {
+ *   console.log("Upload ID:", inputData.uploadId);
+ * }
  * ```
  */
-type ExtractEffectError<T> = T extends Effect.Effect<any, infer E, any> ? E : never;
+declare function isFinalizeOperation(data: InputData): data is Extract<InputData, {
+  operation: "finalize";
+}>;
 /**
- * Extracts the requirements (context) type from an Effect.
+ * Type guard for URL operation (direct file fetch from URL).
  *
- * Given an Effect type, this utility extracts the requirements type
- * (third type parameter) from the Effect's type signature. This represents
- * the services that must be provided for the Effect to run.
+ * Checks if the input data is a URL operation that fetches a file
+ * directly from an external URL.
  *
- * @template T - The Effect type to extract from
- * @returns The requirements type of the Effect, or never if T is not an Effect
+ * @param data - Input data to check
+ * @returns True if data is a URL operation
  *
  * @example
  * ```typescript
- * type MyEffect = Effect.Effect<string, Error, Database | Logger>;
- * type Requirements = ExtractEffectRequirements<MyEffect>;
- * // Requirements = Database | Logger
+ * if (isUrlOperation(inputData)) {
+ *   console.log("Fetching from:", inputData.url);
+ *   console.log("Optional storage:", inputData.storageId);
+ * }
  * ```
+ */
+declare function isUrlOperation(data: InputData): data is Extract<InputData, {
+  operation: "url";
+}>;
+/**
+ * Type guard for upload operations (init or url).
+ *
+ * Checks if the input data is either an init or URL operation (i.e., operations
+ * that trigger new uploads, as opposed to finalize which completes an existing upload).
+ *
+ * @param data - Input data to check
+ * @returns True if data is an init or URL operation
  *
  * @example
  * ```typescript
- * import { ImagePlugin, ZipPlugin } from '@uploadista/core';
- *
- * type ProcessEffect = Effect.Effect<
- *   ProcessedImage,
- *   ProcessError,
- *   ImagePlugin | ZipPlugin
- * >;
- * type Needed = ExtractEffectRequirements<ProcessEffect>;
- * // Needed = ImagePlugin | ZipPlugin
+ * if (isUploadOperation(inputData)) {
+ *   // This is a new upload, not a finalization
+ *   if (isInitOperation(inputData)) {
+ *     console.log("Streaming upload");
+ *   } else {
+ *     console.log("URL fetch");
+ *   }
+ * }
  * ```
  */
-type ExtractEffectRequirements<T> = T extends Effect.Effect<any, any, infer R> ? R : never;
+declare function isUploadOperation(data: InputData): data is Extract<InputData, {
+  operation: "init" | "url";
+}>;
 //#endregion
 //#region src/flow/typed-flow.d.ts
 /**
@@ -6127,6 +7440,30 @@ type TypedFlowConfig<TNodes extends NodeDefinitionsRecord> = {
       clientId: string | null;
     }) => Effect.Effect<TOutput, UploadistaError, never> | Promise<TOutput>;
   };
+  /**
+   * Circuit breaker configuration for resilience against external service failures.
+   *
+   * @example
+   * ```typescript
+   * circuitBreaker: {
+   *   defaults: { enabled: false },
+   *   nodeTypeOverrides: {
+   *     "Describe Image": {
+   *       enabled: true,
+   *       failureThreshold: 5,
+   *       resetTimeout: 60000,
+   *       fallback: { type: "skip", passThrough: true }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  circuitBreaker?: {
+    /** Default circuit breaker config for all nodes */
+    defaults?: FlowCircuitBreakerConfig;
+    /** Override circuit breaker config per node type (node name) */
+    nodeTypeOverrides?: Record<string, FlowCircuitBreakerConfig>;
+  };
 };
 declare const typedFlowInputsSymbol: unique symbol;
 declare const typedFlowOutputsSymbol: unique symbol;
@@ -6217,6 +7554,391 @@ declare const runArgsSchema: z.ZodObject<{
  */
 type RunArgs = z.infer<typeof runArgsSchema>;
 //#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/flow/dead-letter-queue.d.ts
+/**
+ * Shape of the Dead Letter Queue service.
+ *
+ * Provides all operations for managing failed flow jobs including
+ * adding items, querying, retrying, and cleanup.
+ */
+interface DeadLetterQueueServiceShape {
+  /**
+   * Add a failed job to the DLQ with full failure context.
+   *
+   * @param job - The failed flow job
+   * @param error - The error that caused the failure
+   * @param retryPolicy - Optional retry policy (uses default if not provided)
+   * @returns The created DLQ item
+   */
+  add(job: FlowJob, error: UploadistaError, retryPolicy?: RetryPolicy): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Get a specific DLQ item by ID.
+   *
+   * @param itemId - The DLQ item ID
+   * @returns The DLQ item
+   */
+  get(itemId: string): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Get a DLQ item by ID, returning None if not found.
+   *
+   * @param itemId - The DLQ item ID
+   * @returns Option of the DLQ item
+   */
+  getOption(itemId: string): Effect.Effect<Option.Option<DeadLetterItem>, UploadistaError>;
+  /**
+   * Delete a DLQ item.
+   *
+   * @param itemId - The DLQ item ID to delete
+   */
+  delete(itemId: string): Effect.Effect<void, UploadistaError>;
+  /**
+   * List DLQ items with optional filtering and pagination.
+   *
+   * @param options - Filter and pagination options
+   * @returns List of items and total count
+   */
+  list(options?: DeadLetterListOptions): Effect.Effect<{
+    items: DeadLetterItem[];
+    total: number;
+  }, UploadistaError>;
+  /**
+   * Update a DLQ item.
+   *
+   * @param itemId - The DLQ item ID
+   * @param updates - Partial updates to apply
+   * @returns The updated item
+   */
+  update(itemId: string, updates: Partial<DeadLetterItem>): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Mark a DLQ item as being retried.
+   *
+   * @param itemId - The DLQ item ID
+   * @returns The updated item with status "retrying"
+   */
+  markRetrying(itemId: string): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Record a failed retry attempt.
+   *
+   * @param itemId - The DLQ item ID
+   * @param error - Error message from the failed retry
+   * @param durationMs - Duration of the retry attempt
+   * @returns The updated item
+   */
+  recordRetryFailure(itemId: string, error: string, durationMs: number): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Mark a DLQ item as resolved (successfully retried or manually resolved).
+   *
+   * @param itemId - The DLQ item ID
+   * @returns The updated item with status "resolved"
+   */
+  markResolved(itemId: string): Effect.Effect<DeadLetterItem, UploadistaError>;
+  /**
+   * Get items that are due for scheduled retry.
+   *
+   * @param limit - Maximum number of items to return
+   * @returns List of items ready for retry
+   */
+  getScheduledRetries(limit?: number): Effect.Effect<DeadLetterItem[], UploadistaError>;
+  /**
+   * Cleanup old DLQ items based on options.
+   *
+   * @param options - Cleanup criteria
+   * @returns Number of items deleted
+   */
+  cleanup(options?: DeadLetterCleanupOptions): Effect.Effect<DeadLetterCleanupResult, UploadistaError>;
+  /**
+   * Get DLQ statistics.
+   *
+   * @returns Aggregate statistics about the DLQ
+   */
+  getStats(): Effect.Effect<DeadLetterQueueStats, UploadistaError>;
+}
+declare const DeadLetterQueueService_base: Context.TagClass<DeadLetterQueueService, "DeadLetterQueueService", DeadLetterQueueServiceShape>;
+/**
+ * Effect-TS context tag for the Dead Letter Queue service.
+ *
+ * @example
+ * ```typescript
+ * const effect = Effect.gen(function* () {
+ *   const dlq = yield* DeadLetterQueueService;
+ *   const stats = yield* dlq.getStats();
+ *   console.log(`DLQ has ${stats.totalItems} items`);
+ * });
+ * ```
+ */
+declare class DeadLetterQueueService extends DeadLetterQueueService_base {
+  /**
+   * Access the DLQ service optionally (for integration in FlowServer).
+   * Returns Option.none if the service is not provided.
+   */
+  static optional: Effect.Effect<Option.Option<DeadLetterQueueServiceShape>, never, never>;
+}
+/**
+ * Creates the Dead Letter Queue service implementation.
+ *
+ * @returns Effect that creates the DLQ service
+ */
+declare function createDeadLetterQueueService(): Effect.Effect<DeadLetterQueueServiceShape, never, DeadLetterQueueKVStore>;
+/**
+ * Effect Layer that creates the DeadLetterQueueService.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const dlq = yield* DeadLetterQueueService;
+ *   const stats = yield* dlq.getStats();
+ *   return stats;
+ * }).pipe(
+ *   Effect.provide(deadLetterQueueService),
+ *   Effect.provide(deadLetterQueueKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const deadLetterQueueService: Layer.Layer<DeadLetterQueueService, never, DeadLetterQueueKVStore>;
+//#endregion
 //#region src/flow/utils/resolve-upload-metadata.d.ts
 type FileMetadata = UploadFile["metadata"];
 type ResolvedUploadMetadata = {
@@ -6227,5 +7949,202 @@ type ResolvedUploadMetadata = {
 };
 declare function resolveUploadMetadata(metadata: FileMetadata): ResolvedUploadMetadata;
 //#endregion
-export { VideoPluginShape as $, MiddlewareServiceLive as $n, TypedKvStore as $r, DocumentPluginLayer as $t, isOcrOutput as A, FlowEventNodeResponse as Ai, FlowServerShape as An, ValidationResult as Ar, brightnessTransformSchema as At, PluginLayer as B, uploadFileSchema as Bi, UploadStrategyNegotiator as Bn, DataStoreCapabilities as Br, transformImageParamsSchema as Bt, getFirstOutputByType as C, FlowEventFlowPause as Ci, inputDataSchema as Cn, STORAGE_OUTPUT_TYPE_ID as Cr, SharpenTransform as Ct, isFinalizeOperation as D, FlowEventNodeEnd as Di, FlowServer as Dn, FlowTypeRegistry as Dr, TransformationType as Dt, hasOutputOfType as E, FlowEventJobStart as Ei, FlowProviderShape as En, ocrOutputSchema as Er, Transformation as Et, RemoveBackgroundParams as F, ConditionValue as Fi, FlowJob as Fn, FlowExecutionResult as Fr, resizeTransformSchema as Ft, ZipPluginShape as G, createUploadServer as Gn, UploadFileDataStoresShape as Gr, OptimizeParams as Gt, ZipParams as H, UploadServer as Hn, DataStoreWriteOptions as Hr, watermarkTransformSchema as Ht, removeBackgroundParamsSchema as I, NodeType as Ii, FlowJobStatus as In, createFlowWithSchema as Ir, rotateTransformSchema as It, VirusScanPlugin as J, detectMimeType as Jn, isDataStore as Jr, ImageAiPlugin as Jt, ScanMetadata as K, uploadServer as Kn, UploadStrategy as Kr, optimizeParamsSchema as Kt, DescribeImageParams as L, createFlowNode as Li, FlowJobTask as Ln, getFlowData as Lr, sepiaTransformSchema as Lt, isUploadFile as M, FlowEventNodeStart as Mi, WaitUntilCallback as Mn, validateFlowInput as Mr, flipTransformSchema as Mt, isUploadOperation as N, ConditionField as Ni, createFlowServer as Nn, Flow as Nr, grayscaleTransformSchema as Nt, isImageDescriptionOutput as O, FlowEventNodeError as Oi, FlowServerLayer as On, NodeTypeCategory as Or, WatermarkTransform as Ot, isUrlOperation as P, ConditionOperator as Pi, flowServer as Pn, FlowData as Pr, logoTransformSchema as Pt, VideoPluginLayer as Q, MiddlewareService as Qn, KvStore as Qr, DocumentPlugin as Qt, describeImageParamsSchema as R, getNodeData as Ri, FlowJobTaskStatus as Rn, BufferedUploadFileDataStore as Rr, sharpenTransformSchema as Rt, filterOutputsByType as S, FlowEventFlowError as Si, createInputNode as Sn, OcrOutput as Sr, SepiaTransform as St, getSingleOutputByType as T, FlowEventJobEnd as Ti, FlowProvider as Tn, imageDescriptionOutputSchema as Tr, TransformImageParams as Tt, ZipPlugin as U, UploadServerOptions as Un, UploadFileDataStore as Ur, ResizeParams as Ut, ZipInput as V, UploadStrategyOptions as Vn, DataStoreConfig as Vr, transformationSchema as Vt, ZipPluginLayer as W, UploadServerShape as Wn, UploadFileDataStores as Wr, resizeParamsSchema as Wt, VirusScanPluginShape as X, MiddlewareContext as Xn, BaseKvStoreService as Xr, ImageAiPluginShape as Xt, VirusScanPluginLayer as Y, Middleware as Yn, BaseKvStore as Yr, ImageAiPluginLayer as Yt, VideoPlugin as Z, MiddlewareNext as Zn, FlowJobKVStore as Zr, DocumentMetadata as Zt, ExtractLayerService as _, waitingNodeExecution as _i, ParallelSchedulerConfig as _n, EventBroadcaster as _r, GrayscaleTransform as _t, FlowInputMap as a, createFlowEdge as ai, DocumentAiPlugin as an, FlowEventEmitter as ar, resizeVideoParamsSchema as at, FlowCondition as b, FlowEventFlowCancel as bi, InputData as bn, ImageDescriptionOutput as br, ResizeTransform as bt, FlowRequirements as c, FlowConfig as ci, OcrParams as cn, eventToMessageSerializer as cr, DescribeVideoMetadata as ct, TypedFlow as d, NodeConnectionValidator as di, OcrTaskType as dn, WebSocketConnection as dr, ImagePluginLayer as dt, UploadFileKVStore as ei, DocumentPluginShape as en, InputFile as er, TrimVideoParams as et, TypedFlowConfig as f, NodeExecutionResult as fi, CredentialProvider as fn, WebSocketMessage as fr, ImagePluginShape as ft, ExtractEffectRequirements as g, completeNodeExecution as gi, ParallelScheduler as gn, uploadEventSchema as gr, FlipTransform as gt, ExtractEffectError as h, TypedOutput as hi, ExecutionLevel as hn, UploadEventType as hr, ContrastTransform as ht, runArgsSchema as i, FlowEdge as ii, DocumentAiContext as in, EventEmitter as ir, ResizeVideoParams as it, isStorageOutput as j, FlowEventNodeResume as ji, FlowWaitUntil as jn, flowTypeRegistry as jr, contrastTransformSchema as jt, isInitOperation as k, FlowEventNodePause as ki, FlowServerOptions as kn, NodeTypeDefinition as kr, blurTransformSchema as kt, NodeDefinition as l, FlowNode as li, OcrResolution as ln, flowEventEmitter as lr, describeVideoMetadataSchema as lt, createFlow as m, TypeCompatibilityChecker as mi, CredentialProviderShape as mn, UploadEvent as mr, BrightnessTransform as mt, resolveUploadMetadata as n, jsonSerializer as ni, SplitPdfParams as nn, BaseEventEmitter as nr, TranscodeVideoParams as nt, FlowOutputMap as o, BuiltInTypedOutput as oi, DocumentAiPluginLayer as on, TypedEventEmitter as or, ExtractFrameVideoParams as ot, TypedFlowEdge as p, NodeTypeMap as pi, CredentialProviderLayer as pn, webSocketMessageSchema as pr, BlurTransform as pt, ScanResult as q, compareMimeTypes as qn, createDataStoreLayer as qr, ImageAiContext as qt, RunArgs as r, uploadFileKvStore as ri, SplitPdfResult as rn, BaseEventEmitterService as rr, transcodeVideoParamsSchema as rt, FlowPluginRequirements as s, CustomTypedOutput as si, DocumentAiPluginShape as sn, UploadEventEmitter as sr, extractFrameVideoParamsSchema as st, ResolvedUploadMetadata as t, flowJobKvStore as ti, MergePdfParams as tn, inputFileSchema as tr, trimVideoParamsSchema as tt, NodeDefinitionsRecord as u, FlowNodeData as ui, OcrResult as un, uploadEventEmitter as ur, ImagePlugin as ut, ExtractLayerServices as v, EventType as vi, TransformNodeConfig as vn, EventBroadcasterService as vr, LogoTransform as vt, getOutputByNodeId as w, FlowEventFlowStart as wi, inputNodeParamsSchema as wn, STREAMING_INPUT_TYPE_ID as wr, TextTransform as wt, createTypeGuard as x, FlowEventFlowEnd as xi, InputNodeParams as xn, OCR_OUTPUT_TYPE_ID as xr, RotateTransform as xt, ResolveEffect as y, FlowEvent as yi, createTransformNode as yn, IMAGE_DESCRIPTION_OUTPUT_TYPE_ID as yr, OverlayPosition as yt, Plugin as z, UploadFile as zi, NegotiatedStrategy as zn, DataStore as zr, textTransformSchema as zt };
-//# sourceMappingURL=index-BQ5luyME.d.cts.map
+//#region src/flow/utils/file-naming.d.ts
+/**
+ * Extracts the base name (without extension) from a filename.
+ *
+ * @param fileName - The full filename
+ * @returns The filename without extension
+ *
+ * @example
+ * ```typescript
+ * getBaseName("photo.jpg") // "photo"
+ * getBaseName("document.tar.gz") // "document.tar"
+ * getBaseName("noextension") // "noextension"
+ * ```
+ */
+declare function getBaseName(fileName: string): string;
+/**
+ * Extracts the extension (without dot) from a filename.
+ *
+ * @param fileName - The full filename
+ * @returns The extension without leading dot, or empty string if none
+ *
+ * @example
+ * ```typescript
+ * getExtension("photo.jpg") // "jpg"
+ * getExtension("document.tar.gz") // "gz"
+ * getExtension("noextension") // ""
+ * ```
+ */
+declare function getExtension(fileName: string): string;
+/**
+ * Builds a naming context from file and flow execution information.
+ *
+ * @param file - The UploadFile being processed
+ * @param flowContext - Flow execution context (flowId, jobId, nodeId, nodeType)
+ * @param extraVars - Additional variables to include (width, height, format, etc.)
+ * @returns Complete naming context for template interpolation
+ *
+ * @example
+ * ```typescript
+ * const context = buildNamingContext(
+ *   uploadFile,
+ *   { flowId: "flow-1", jobId: "job-1", nodeId: "resize-1", nodeType: "resize" },
+ *   { width: 800, height: 600 }
+ * );
+ * // context.baseName = "photo"
+ * // context.extension = "jpg"
+ * // context.width = 800
+ * // context.height = 600
+ * ```
+ */
+declare function buildNamingContext(file: UploadFile, flowContext: {
+  flowId: string;
+  jobId: string;
+  nodeId: string;
+  nodeType: string;
+}, extraVars?: Record<string, string | number | undefined>): NamingContext;
+/**
+ * Interpolates a mustache-style template with the given context.
+ *
+ * Uses micromustache for fast, secure template rendering.
+ * Unknown variables are preserved as-is (e.g., {{unknown}} stays {{unknown}}).
+ *
+ * @param pattern - Mustache-style template string
+ * @param context - Variables to interpolate
+ * @returns Interpolated string
+ *
+ * @example
+ * ```typescript
+ * interpolateFileName(
+ *   "{{baseName}}-{{width}}x{{height}}.{{extension}}",
+ *   { baseName: "photo", width: 800, height: 600, extension: "jpg" }
+ * );
+ * // Returns: "photo-800x600.jpg"
+ * ```
+ */
+declare function interpolateFileName(pattern: string, context: NamingContext): string;
+/**
+ * Applies file naming configuration to generate a new filename.
+ *
+ * Handles three modes:
+ * - No config: Returns original filename (backward compatible)
+ * - Auto mode: Appends auto-generated suffix based on node type
+ * - Custom mode: Uses template pattern or rename function
+ *
+ * On any error, falls back to the original filename to prevent flow failures.
+ *
+ * @param file - The UploadFile being processed
+ * @param context - Naming context with all available variables
+ * @param config - Optional naming configuration
+ * @returns The new filename (or original on error/no config)
+ *
+ * @example
+ * ```typescript
+ * // Auto mode
+ * applyFileNaming(file, context, {
+ *   mode: 'auto',
+ *   autoSuffix: (ctx) => `${ctx.width}x${ctx.height}`
+ * });
+ * // Returns: "photo-800x600.jpg"
+ *
+ * // Custom mode with template
+ * applyFileNaming(file, context, {
+ *   mode: 'custom',
+ *   pattern: '{{baseName}}-processed.{{extension}}'
+ * });
+ * // Returns: "photo-processed.jpg"
+ *
+ * // Custom mode with function
+ * applyFileNaming(file, context, {
+ *   mode: 'custom',
+ *   rename: (file, ctx) => `${ctx.flowId}-${ctx.fileName}`
+ * });
+ * // Returns: "flow-1-photo.jpg"
+ * ```
+ */
+declare function applyFileNaming(file: UploadFile, context: NamingContext, config?: FileNamingConfig): string;
+/**
+ * Validates a template pattern for common issues.
+ *
+ * Checks for:
+ * - Balanced braces
+ * - Non-empty pattern
+ * - Valid variable names
+ *
+ * @param pattern - Template pattern to validate
+ * @returns Object with isValid flag and optional error message
+ *
+ * @example
+ * ```typescript
+ * validatePattern("{{baseName}}.{{extension}}");
+ * // { isValid: true }
+ *
+ * validatePattern("{{baseName");
+ * // { isValid: false, error: "Unbalanced braces: missing closing }}" }
+ * ```
+ */
+declare function validatePattern(pattern: string): {
+  isValid: boolean;
+  error?: string;
+};
+/**
+ * List of available template variables for documentation and UI.
+ */
+declare const AVAILABLE_TEMPLATE_VARIABLES: readonly [{
+  readonly name: "baseName";
+  readonly description: "Filename without extension";
+  readonly example: "photo";
+}, {
+  readonly name: "extension";
+  readonly description: "File extension without dot";
+  readonly example: "jpg";
+}, {
+  readonly name: "fileName";
+  readonly description: "Full original filename";
+  readonly example: "photo.jpg";
+}, {
+  readonly name: "nodeType";
+  readonly description: "Type of processing node";
+  readonly example: "resize";
+}, {
+  readonly name: "nodeId";
+  readonly description: "Specific node instance ID";
+  readonly example: "resize-1";
+}, {
+  readonly name: "flowId";
+  readonly description: "Flow identifier";
+  readonly example: "flow-abc";
+}, {
+  readonly name: "jobId";
+  readonly description: "Execution job ID";
+  readonly example: "job-123";
+}, {
+  readonly name: "timestamp";
+  readonly description: "ISO 8601 processing time";
+  readonly example: "2024-01-15T10:30:00Z";
+}, {
+  readonly name: "width";
+  readonly description: "Output width (image/video)";
+  readonly example: "800";
+}, {
+  readonly name: "height";
+  readonly description: "Output height (image/video)";
+  readonly example: "600";
+}, {
+  readonly name: "format";
+  readonly description: "Output format";
+  readonly example: "webp";
+}, {
+  readonly name: "quality";
+  readonly description: "Quality setting";
+  readonly example: "80";
+}, {
+  readonly name: "pageNumber";
+  readonly description: "Page number (documents)";
+  readonly example: "1";
+}];
+//#endregion
+export { DescribeImageParams as $, KvStore as $a, BackoffStrategy as $i, FlowWaitUntil as $n, ImageDescriptionOutput as $r, sepiaTransformSchema as $t, NodeDefinition as A, ConditionField as Aa, createDataStoreLayer as Ai, CredentialProviderShape as An, HealthResponse as Ar, BrightnessTransform as At, getOutputByNodeId as B, makeKvCircuitBreakerStore as Ba, FlowCircuitBreakerFallback as Bi, ResolveEffect as Bn, UploadEventEmitter as Br, TextTransform as Bt, DeadLetterRetryAttempt as C, FlowEventJobStart as Ca, DataStoreCapabilities as Ci, DocumentAiPluginShape as Cn, inputFileSchema as Cr, extractFrameVideoParamsSchema as Ct, FlowOutputMap as D, FlowEventNodeResponse as Da, UploadFileDataStores as Di, OcrTaskType as Dn, DlqHealthSummary as Dr, ImagePluginLayer as Dt, FlowInputMap as E, FlowEventNodePause as Ea, UploadFileDataStore as Ei, OcrResult as En, DEFAULT_HEALTH_CHECK_CONFIG as Er, ImagePlugin as Et, createFlow as F, getNodeData as Fa, BuiltInTypedOutput as Fi, createTransformNode as Fn, BaseEventEmitter as Fr, OverlayPosition as Ft, isInitOperation as G, CircuitBreakerStats as Ga, NamingContext as Gi, inputDataSchema as Gn, WebSocketMessage as Gr, blurTransformSchema as Gt, hasOutputOfType as H, memoryCircuitBreakerStoreLayer as Ha, FlowDeadLetterQueueConfig as Hi, InputData as Hn, flowEventEmitter as Hr, Transformation as Ht, NarrowedTypedOutput as I, AllowRequestResult as Ia, CustomTypedOutput as Ii, ExtractEffectError as In, BaseEventEmitterService as Ir, ResizeTransform as It, isUploadFile as J, createInitialCircuitBreakerState as Ja, NodeTypeMap as Ji, FlowProviderShape as Jn, UploadEventType as Jr, flipTransformSchema as Jt, isOcrOutput as K, CircuitBreakerStore as Ka, NodeConnectionValidator as Ki, inputNodeParamsSchema as Kn, webSocketMessageSchema as Kr, brightnessTransformSchema as Kt, createTypeGuard as L, DistributedCircuitBreaker as La, FileNamingConfig as Li, ExtractEffectRequirements as Ln, EventEmitter as Lr, RotateTransform as Lt, TypedFlow as M, ConditionValue as Ma, FlowEdge as Mi, ParallelScheduler as Mn, HealthStatus as Mr, FlipTransform as Mt, TypedFlowConfig as N, NodeType as Na, createFlowEdge as Ni, ParallelSchedulerConfig as Nn, formatHealthAsText as Nr, GrayscaleTransform as Nt, FlowPluginRequirements as O, FlowEventNodeResume as Oa, UploadFileDataStoresShape as Oi, CredentialProvider as On, HealthCheckConfig as Or, ImagePluginShape as Ot, TypedFlowEdge as P, createFlowNode as Pa, AutoNamingSuffixGenerator as Pi, TransformNodeConfig as Pn, getHealthResponseFormat as Pr, LogoTransform as Pt, removeBackgroundParamsSchema as Q, FlowJobKVStore as Qa, waitingNodeExecution as Qi, FlowServerShape as Qn, IMAGE_DESCRIPTION_OUTPUT_TYPE_ID as Qr, rotateTransformSchema as Qt, filterOutputsByType as R, DistributedCircuitBreakerRegistry as Ra, FileNamingFunction as Ri, ExtractLayerService as Rn, FlowEventEmitter as Rr, SepiaTransform as Rt, DeadLetterRetryAllResult as S, FlowEventJobEnd as Sa, DataStore as Si, DocumentAiPluginLayer as Sn, InputFile as Sr, ExtractFrameVideoParams as St, runArgsSchema as T, FlowEventNodeError as Ta, DataStoreWriteOptions as Ti, OcrResolution as Tn, ComponentHealth as Tr, describeVideoMetadataSchema as Tt, isFinalizeOperation as U, CircuitBreakerStateData as Ua, FlowNode as Ui, InputNodeParams as Un, uploadEventEmitter as Ur, TransformationType as Ut, getSingleOutputByType as V, makeMemoryCircuitBreakerStore as Va, FlowConfig as Vi, FlowCondition as Vn, eventToMessageSerializer as Vr, TransformImageParams as Vt, isImageDescriptionOutput as W, CircuitBreakerStateValue as Wa, FlowNodeData as Wi, createInputNode as Wn, WebSocketConnection as Wr, WatermarkTransform as Wt, isUrlOperation as X, BaseKvStoreService as Xa, TypedOutput as Xi, FlowServerLayer as Xn, EventBroadcaster as Xr, logoTransformSchema as Xt, isUploadOperation as Y, BaseKvStore as Ya, TypeCompatibilityChecker as Yi, FlowServer as Yn, uploadEventSchema as Yr, grayscaleTransformSchema as Yt, RemoveBackgroundParams as Z, DeadLetterQueueKVStore as Za, completeNodeExecution as Zi, FlowServerOptions as Zn, EventBroadcasterService as Zr, resizeTransformSchema as Zt, DeadLetterItem as _, FlowEventFlowCancel as _a, FlowData as _i, MergePdfParams as _n, Middleware as _r, trimVideoParamsSchema as _t, getExtension as a, calculateBackoffDelay as aa, ocrOutputSchema as ai, ResizeParams as an, uploadFileKvStore as ao, FlowJobTask as ar, ZipPlugin as at, DeadLetterProcessResult as b, FlowEventFlowPause as ba, getFlowData as bi, DocumentAiContext as bn, MiddlewareService as br, ResizeVideoParams as bt, ResolvedUploadMetadata as c, DlqEvent as ca, OutputValidationResult as ci, optimizeParamsSchema as cn, CircuitBreakerConfig as co, UploadStrategyNegotiator as cr, ScanMetadata as ct, DeadLetterQueueServiceShape as d, FlowEventDlqItemAdded as da, InputTypeDefinition as di, ImageAiPluginLayer as dn, CircuitBreakerFallback as do, UploadServerOptions as dr, VirusScanPluginLayer as dt, DEFAULT_RETRY_POLICY as ea, OCR_OUTPUT_TYPE_ID as ei, sharpenTransformSchema as en, TypedKvStore as eo, WaitUntilCallback as er, describeImageParamsSchema as et, createDeadLetterQueueService as f, FlowEventDlqItemExhausted as fa, InputTypeRegistry as fi, ImageAiPluginShape as fn, CircuitBreakerState as fo, UploadServerShape as fr, VirusScanPluginShape as ft, DeadLetterError as g, FlowEventDlqRetrySuccess as ga, Flow as gi, DocumentPluginShape as gn, detectMimeType as gr, TrimVideoParams as gt, DeadLetterCleanupResult as h, FlowEventDlqRetryStart as ha, validateFlowInput as hi, DocumentPluginLayer as hn, compareMimeTypes as hr, VideoPluginShape as ht, getBaseName as i, RetryPolicy as ia, imageDescriptionOutputSchema as ii, watermarkTransformSchema as in, jsonSerializer as io, FlowJobStatus as ir, ZipParams as it, NodeDefinitionsRecord as j, ConditionOperator as ja, isDataStore as ji, ExecutionLevel as jn, HealthResponseFormat as jr, ContrastTransform as jt, FlowRequirements as k, FlowEventNodeStart as ka, UploadStrategy as ki, CredentialProviderLayer as kn, HealthComponents as kr, BlurTransform as kt, resolveUploadMetadata as l, EventType as la, outputTypeRegistry as li, ImageAiContext as ln, CircuitBreakerEvent as lo, UploadStrategyOptions as lr, ScanResult as lt, DeadLetterCleanupOptions as m, FlowEventDlqRetryFailed as ma, inputTypeRegistry as mi, DocumentPlugin as mn, uploadServer as mr, VideoPluginLayer as mt, applyFileNaming as n, FixedBackoff as na, STORAGE_OUTPUT_TYPE_ID as ni, transformImageParamsSchema as nn, deadLetterQueueKvStore as no, flowServer as nr, PluginLayer as nt, interpolateFileName as o, calculateExpirationDate as oa, OutputTypeDefinition as oi, resizeParamsSchema as on, UploadFile as oo, FlowJobTaskStatus as or, ZipPluginLayer as ot, deadLetterQueueService as p, FlowEventDlqItemResolved as pa, InputValidationResult as pi, DocumentMetadata as pn, DEFAULT_CIRCUIT_BREAKER_CONFIG as po, createUploadServer as pr, VideoPlugin as pt, isStorageOutput as q, CircuitBreakerStoreService as qa, NodeExecutionResult as qi, FlowProvider as qn, UploadEvent as qr, contrastTransformSchema as qt, buildNamingContext as r, ImmediateBackoff as ra, STREAMING_INPUT_TYPE_ID as ri, transformationSchema as rn, flowJobKvStore as ro, FlowJob as rr, ZipInput as rt, validatePattern as s, isErrorRetryable as sa, OutputTypeRegistry as si, OptimizeParams as sn, uploadFileSchema as so, NegotiatedStrategy as sr, ZipPluginShape as st, AVAILABLE_TEMPLATE_VARIABLES as t, ExponentialBackoff as ta, OcrOutput as ti, textTransformSchema as tn, UploadFileKVStore as to, createFlowServer as tr, Plugin as tt, DeadLetterQueueService as u, FlowEvent as ua, validateFlowOutput as ui, ImageAiPlugin as un, CircuitBreakerEventHandler as uo, UploadServer as ur, VirusScanPlugin as ut, DeadLetterItemStatus as v, FlowEventFlowEnd as va, FlowExecutionResult as vi, SplitPdfParams as vn, MiddlewareContext as vr, TranscodeVideoParams as vt, RunArgs as w, FlowEventNodeEnd as wa, DataStoreConfig as wi, OcrParams as wn, CircuitBreakerHealthSummary as wr, DescribeVideoMetadata as wt, DeadLetterQueueStats as x, FlowEventFlowStart as xa, BufferedUploadFileDataStore as xi, DocumentAiPlugin as xn, MiddlewareServiceLive as xr, resizeVideoParamsSchema as xt, DeadLetterListOptions as y, FlowEventFlowError as ya, createFlowWithSchema as yi, SplitPdfResult as yn, MiddlewareNext as yr, transcodeVideoParamsSchema as yt, getFirstOutputByType as z, kvCircuitBreakerStoreLayer as za, FlowCircuitBreakerConfig as zi, ExtractLayerServices as zn, TypedEventEmitter as zr, SharpenTransform as zt };
+//# sourceMappingURL=index-D7i4bgl3.d.mts.map