@lotiai/composer 0.2.0 → 0.2.1

package/dist/internal/dag-sync-workflow.js

@@ -0,0 +1,843 @@
+"use strict";
+/**
+ * DAG-based Workflow Engine with Compile-time Validation
+ *
+ * This module implements a directed acyclic graph (DAG) workflow system that:
+ * - Validates step dependencies at compile-time using TypeScript
+ * - Executes steps in parallel when dependencies allow
+ * - Uses topological sorting with batching for optimal performance
+ * - Supports workflow composition for modularity and reusability
+ *
+ * ## Core Concepts
+ *
+ * **Step**: A unit of work with declared inputs (needs) and outputs (provides)
+ * **Workflow**: A collection of steps with automatic dependency resolution
+ * **Bag**: The data container that flows through the workflow
+ *
+ * ## Execution Model
+ *
+ * The engine uses **batch-based parallel execution**:
+ * 1. **Dependency Analysis**: Builds a dependency graph using topological sorting
+ * 2. **Batch Formation**: Groups steps that can run simultaneously
+ * 3. **Parallel Execution**: Runs each batch with Promise.all()
+ * 4. **Dependency Tracking**: Uses indegree counters to trigger next batch
+ *
+ * ## Example Execution Flow
+ *
+ * Given workflow: [stepA, stepB, stepC, stepD]
+ * - stepA: needs [] → provides ["x"]
+ * - stepB: needs ["x"] → provides ["y"]
+ * - stepC: needs ["x"] → provides ["z"]
+ * - stepD: needs ["y", "z"] → provides ["result"]
+ *
+ * Execution batches:
+ * - Batch 1: [stepA] (sequential)
+ * - Batch 2: [stepB, stepC] (parallel - both need "x")
+ * - Batch 3: [stepD] (sequential - needs both "y" and "z")
+ *
+ * ## Workflow Composition
+ *
+ * Workflows can be composed using the `use()` helper to create modular, reusable components:
+ *
+ * ```typescript
+ * // Define a reusable child workflow
+ * const authWorkflow = createWorkflow<Bag>("authentication")
+ *   .requires("userId")
+ *   .build([validateUser, checkPermissions]);
+ *
+ * // Compose into parent workflow
+ * const mainWorkflow = createWorkflow<Bag>("main")
+ *   .requires("userId")
+ *   .build([
+ *     fetchUserData,      // Provides userId
+ *     use(authWorkflow),  // Reuses authentication logic
+ *     processRequest,     // Uses auth results
+ *   ]);
+ * ```
+ *
+ * **Key Composition Features:**
+ * - **Step Flattening**: Child workflow steps are merged into parent's dependency graph
+ * - **Maximum Parallelization**: Steps from different workflows can execute in the same batch
+ * - **Automatic Namespacing**: Child steps are prefixed as "childName.stepName" to prevent conflicts
+ * - **Dependency Propagation**: Child initial requirements become regular dependencies in parent
+ * - **Nested Composition**: Workflows can compose other composed workflows to any depth
+ * - **Observability Preservation**: SubWorkflow spans maintain logical boundaries in traces
+ *
+ * **Composition Benefits:**
+ * - Code reusability across different workflows
+ * - Easier testing of workflow components in isolation
+ * - Better organization of complex business logic
+ * - Maintains compile-time type safety across composition boundaries
+ *
+ * ## Compile-time Safety
+ *
+ * The type system validates:
+ * - All step dependencies are satisfied by previous steps or initial data
+ * - Required initial fields are provided at runtime
+ * - Clear error messages for missing dependencies
+ *
+ * ## Data Protection & Overwrite Prevention
+ *
+ * The engine enforces strict data integrity rules:
+ * - **Step-to-Step Protection**: Each field can have only one producer step (duplicate producers are rejected)
+ * - **Initial Data Protection**: Steps cannot overwrite fields provided in initial data
+ * - **Immutable Outputs**: Once a step produces a field, it cannot be modified by other steps
+ * - **Early Detection**: All conflicts are caught at workflow execution time, not during step execution
+ *
+ * ## Performance Characteristics
+ *
+ * - **Automatic Parallelization**: Steps run concurrently when safe
+ * - **Batch Synchronization**: All steps in a batch complete before next batch starts
+ * - **Zero Polling**: Event-driven execution using dependency counters
+ * - **Optimal Scheduling**: Steps execute as soon as dependencies are satisfied
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CHECKPOINT_TIMEOUT_MS = void 0;
+exports.use = use;
+exports.createWorkflow = createWorkflow;
+exports.runSyncWorkflow = runSyncWorkflow;
+const api_1 = require("@opentelemetry/api");
+const uuid_1 = require("uuid");
+const dag_sync_fanout_1 = require("./dag-sync-fanout");
+const defaults_1 = require("./defaults");
+const errors_1 = require("./errors");
+const observability_1 = require("./observability");
+const workflow_planning_1 = require("./workflow-planning");
+// ============================================================================
+// Checkpoint Types
+// ============================================================================
+/**
+ * Default timeout for checkpoints in milliseconds.
+ *
+ * Checkpoints are designed for fast early returns within HTTP timeout windows.
+ * The default of 30 seconds provides a reasonable window for initial step(s)
+ * to complete while leaving headroom before typical HTTP timeouts (60s).
+ */
+exports.DEFAULT_CHECKPOINT_TIMEOUT_MS = 30_000; // 30 seconds
+/**
+ * IMMUTABILITY PROTECTION FEATURE FLAG
+ *
+ * When enabled, all step outputs are deeply frozen before being merged into the shared bag.
+ * This prevents mutation bugs that can cause non-deterministic workflow behavior.
+ *
+ * ## What This Protects Against:
+ *
+ * 1. **Parallel batch mutations**: Two steps in the same batch mutating shared references
+ *    Example: Both steps call bag.identities.push(...) → race condition
+ *
+ * 2. **Downstream mutations**: A step mutates data it received from a previous step
+ *    Example: step.run((ctx, bag) => { bag.rules.sort(); ... }) → changes data for peers
+ *
+ * 3. **Post-return mutations**: A step keeps a reference and mutates it later
+ *    Example: setTimeout(() => myData.length = 0, 100) → corrupts bag after batch completes
+ *
+ * 4. **Array/nested mutations**: TypeScript's Readonly<> is shallow and can't prevent these
+ *    Example: bag.identities[0].name = "x" → compiles but violates immutability
+ *
+ * 5. **Third-party library side effects**: SDKs that mutate arguments in place
+ *    Example: someLibrary.normalize(bag.config) → unexpected mutations
+ *
+ * ## Why It's Feature-Flagged:
+ *
+ * Deep freeze has a performance cost (~0.5-10ms per output depending on object size).
+ * For workflows where steps do I/O (database, API calls), this overhead is negligible.
+ * For CPU-intensive workflows with large objects, it may be noticeable.
+ *
+ * Recommendation:
+ * - Enable in development/test to catch mutation bugs early
+ * - Enable in production unless profiling shows it's a bottleneck
+ * - If disabled in prod, ensure code reviews catch mutation patterns
+ *
+ * Deep freeze is now controlled by the `deepFreeze` option in ComposerConfig.
+ *
+ * TODO(nate): Add observability for cost of deep freeze + any runtime validation.
+ */
+/**
+ * Recursively freezes an object and all nested objects/arrays.
+ *
+ * This provides runtime immutability guarantees that TypeScript's type system cannot enforce.
+ * After deep freezing, any attempt to mutate the object or its nested properties will throw
+ * an error in strict mode or silently fail in non-strict mode.
+ *
+ * @param obj - The object to freeze
+ * @returns The frozen object (same reference, now immutable)
+ *
+ * Performance characteristics:
+ * - O(n) where n is the total number of nodes in the object graph
+ * - Typical cost: 0.5-10ms for objects with 100-1000 nodes
+ * - Skips already-frozen objects for efficiency
+ * - Handles null/undefined/primitives safely
+ */
+function deepFreeze(obj) {
+    // Skip primitives, null, undefined, and already-frozen objects
+    if (!obj || typeof obj !== "object" || Object.isFrozen(obj)) {
+        return obj;
+    }
+    // Freeze this level
+    Object.freeze(obj);
+    // Recursively freeze all nested values
+    for (const value of Object.values(obj)) {
+        deepFreeze(value);
+    }
+    return obj;
+}
+/**
+ * Runtime validation that ensures all step names are unique.
+ *
+ * Step names are used as primary keys in dependency maps (stepsByName, children, indegree).
+ * Duplicate names would cause silent overwrites in these maps, corrupting the DAG structure
+ * and leading to wrong execution order or missing dependencies.
+ *
+ * This function provides clear error messages that help developers identify which steps
+ * have conflicting names and where they appear in the workflow definition.
+ */
+function assertUniqueStepNames(steps) {
+    const seen = new Map(); // Track first occurrence index for better errors
+    steps.forEach((step, index) => {
+        const stepName = step.name;
+        if (seen.has(stepName)) {
+            const firstIndex = seen.get(stepName);
+            throw new Error(`Duplicate step name "${stepName}" found at positions ${firstIndex} and ${index}. ` +
+                `Step names must be unique within a workflow.\n\n` +
+                `💡 Fix: Rename one of the steps to have a unique name.`);
+        }
+        seen.set(stepName, index);
+    });
+}
+/**
+ * Helper function to find the first duplicate key in an array.
+ *
+ * Returns undefined if no duplicates exist, or the duplicated key if found.
+ */
+function findDuplicateKey(keys) {
+    const seen = new Set();
+    for (const key of keys) {
+        const keyStr = String(key);
+        if (seen.has(keyStr)) {
+            return keyStr;
+        }
+        seen.add(keyStr);
+    }
+    return undefined;
+}
+/**
+ * Runtime validation that ensures no duplicates exist in step needs/provides arrays.
+ *
+ * Duplicate needs cause deadlocks in the topological sort (indegree is incremented twice
+ * but only decremented once, so the step never reaches zero and never executes).
+ *
+ * Duplicate provides violate the semantic contract and make observability confusing,
+ * even though they don't break execution (the field only exists once in the return object).
+ */
+function assertNoDuplicatesInStepArrays(steps) {
+    for (const step of steps) {
+        const duplicateNeed = findDuplicateKey(step.needs);
+        if (duplicateNeed) {
+            throw new Error(`Step "${step.name}" lists "${duplicateNeed}" twice in "needs". ` +
+                `Each dependency should only be declared once.\n\n` +
+                `💡 Fix: Remove the duplicate "${duplicateNeed}" from the needs array.`);
+        }
+        const duplicateProvide = findDuplicateKey(step.provides);
+        if (duplicateProvide) {
+            throw new Error(`Step "${step.name}" lists "${duplicateProvide}" twice in "provides". ` +
+                `Each output field should only be declared once.\n\n` +
+                `💡 Fix: Remove the duplicate "${duplicateProvide}" from the provides array.`);
+        }
+    }
+}
+/**
+ * Composes a child workflow into a parent workflow.
+ *
+ * When building a workflow, use `use(childWorkflow)` to include all steps from the child.
+ * The steps will be:
+ * - Flattened into the parent's dependency graph for maximum parallelization
+ * - Automatically namespaced as "childWorkflowName.stepName" to prevent conflicts
+ * - Tracked with workflow provenance metadata for proper observability
+ *
+ * Any initial requirements from the child workflow become regular dependencies that
+ * must be satisfied by the parent's steps or initial data.
+ *
+ * Example:
+ * ```typescript
+ * const childWf = createWorkflow<Bag>("child").build([stepA, stepB]);
+ * const parentWf = createWorkflow<Bag>("parent").build([
+ *   stepX,
+ *   use(childWf),  // Includes stepA and stepB with proper namespacing
+ *   stepY,
+ * ]);
+ *
+ * ## Observability
+ *
+ * Composed workflows create SubWorkflow spans in traces, making it easy to see logical
+ * boundaries even though execution is flattened:
+ * ```
+ * Workflow: main
+ *   └─ Batch 1
+ *      └─ SubWorkflow: authentication
+ *         └─ Step: authentication.validateUser
+ * ```
+ */
+function use(workflow) {
+    return {
+        __composedWorkflow: true,
+        workflow,
+    };
+}
+function workflow(name, steps, requiredInitial, configuredValues, checkpoints) {
+    // Explicitly specify all 5 type parameters to ensure CheckpointNames is `never`
+    const wf = {
+        name,
+        steps,
+        ...(requiredInitial && requiredInitial.length > 0 ? { requiredInitial } : {}),
+        ...(configuredValues && Object.keys(configuredValues).length > 0 ? { configuredValues } : {}),
+        ...(checkpoints && checkpoints.length > 0 ? { checkpoints } : {}),
+    };
+    // Create a builder function that returns a new WorkflowBuilder with updated checkpoints
+    // The CheckpointNames type parameter is tracked at compile-time only; runtime uses currentCheckpoints
+    function createBuilder(currentWf, currentCheckpoints) {
+        // Implementation uses 'any' for internal assignment since TypeScript can't track
+        // the conditional types through Object.assign. The public interface types are correct.
+        const builder = {
+            ...currentWf,
+            checkpoint(checkpointName, options) {
+                // Validate checkpoint name is unique (runtime validation as safety net)
+                if (currentCheckpoints.some((cp) => cp.name === checkpointName)) {
+                    throw new Error(`Duplicate checkpoint name "${checkpointName}". Checkpoint names must be unique within a workflow.`);
+                }
+                // Extract step name from step reference
+                const stepName = options.afterStep.name;
+                // Validate step exists (supports both namespaced and unnamespaced)
+                // The TypeScript constraint S extends Steps[number] provides compile-time validation,
+                // but we still do runtime validation for composed workflows where step names get namespaced
+                const resolvedStepName = resolveStepName(steps, stepName);
+                if (!resolvedStepName) {
+                    const availableSteps = steps.map((s) => s.name).join(", ");
+                    throw new Error(`Checkpoint "${checkpointName}" references unknown step "${stepName}". ` +
+                        `Available steps: [${availableSteps}]`);
+                }
+                const newCheckpoint = {
+                    name: checkpointName,
+                    afterStep: resolvedStepName, // Use resolved (namespaced) name
+                    timeout: options.timeout,
+                };
+                const newCheckpoints = [...currentCheckpoints, newCheckpoint];
+                const newWf = {
+                    ...currentWf,
+                    checkpoints: newCheckpoints,
+                };
+                return createBuilder(newWf, newCheckpoints);
+            },
+            onError(handler) {
+                return {
+                    ...currentWf,
+                    checkpoints: currentCheckpoints.length > 0 ? currentCheckpoints : undefined,
+                    errorHandler: handler,
+                };
+            },
+        };
+        return builder;
+    }
+    // Explicitly pass 'never' as the type parameter since no checkpoints are defined yet
+    return createBuilder(wf, checkpoints ?? []);
+}
+/**
+ * Resolves a step name, handling both namespaced and unnamespaced names.
+ *
+ * - If `stepName` exactly matches a step, returns it as-is.
+ * - If `stepName` doesn't match but matches the suffix of a namespaced step
+ *   (e.g., "validateUser" matches "auth.validateUser"), returns the full namespaced name.
+ * - If multiple steps match the unnamespaced suffix, throws an error (ambiguous).
+ * - Returns null if no match is found.
+ */
+function resolveStepName(steps, stepName) {
+    // Direct match - return as-is
+    const directMatch = steps.find((s) => s.name === stepName);
+    if (directMatch) {
+        return directMatch.name;
+    }
+    // Try to find by suffix (unnamespaced name matching namespaced step)
+    const suffixMatches = steps.filter((s) => {
+        const parts = s.name.split(".");
+        const unnamespaced = parts[parts.length - 1];
+        return unnamespaced === stepName;
+    });
+    if (suffixMatches.length === 1) {
+        return suffixMatches[0].name;
+    }
+    if (suffixMatches.length > 1) {
+        const matchingNames = suffixMatches.map((s) => s.name).join(", ");
+        throw new Error(`Ambiguous step name "${stepName}" matches multiple steps: [${matchingNames}]. ` +
+            `Use the full namespaced name to specify which step.`);
+    }
+    return null;
+}
+/**
+ * Type guard to check if an item is a ComposedWorkflow marker.
+ */
+function isComposedWorkflow(item) {
+    return item && typeof item === "object" && item.__composedWorkflow === true;
+}
+/**
+ * Flattens a step array that may contain ComposedWorkflow markers.
+ *
+ * This function:
+ * - Recursively processes the array to handle nested composition
+ * - Namespaces steps as "workflowName.stepName" to prevent conflicts
+ * - Tracks workflow provenance in the workflowPath property
+ * - Returns a flat array of steps ready for execution
+ *
+ * @param items - Array of steps and/or ComposedWorkflow markers
+ * @param parentPath - The workflow path of the parent (for nested composition)
+ * @returns Flattened array of steps with namespacing and provenance
+ */
+function flattenSteps(items, parentPath = []) {
+    const result = [];
+    for (const item of items) {
+        if (isComposedWorkflow(item)) {
+            const childWorkflow = item.workflow;
+            const childPath = [...parentPath, childWorkflow.name];
+            // Recursively flatten child workflow's steps
+            const childSteps = flattenSteps(childWorkflow.steps, childPath);
+            // Namespace each step and set workflow path
+            for (const step of childSteps) {
+                // Build the namespaced name: if step already has path, preserve it
+                const namespacedName = step.workflowPath
+                    ? step.name // Already namespaced from nested composition
+                    : `${childWorkflow.name}.${step.name}`;
+                // For workflow path: if step already has one from nested composition,
+                // it starts with the child workflow's name, so we need to prepend the parent path
+                let workflowPath;
+                if (step.workflowPath && step.workflowPath.length > 0) {
+                    // Step already has a path from being in a composed child workflow
+                    // Prepend parent path (excluding the child workflow name since it's already in step.workflowPath)
+                    workflowPath = [...parentPath, ...step.workflowPath];
+                }
+                else {
+                    // Step is directly in this child workflow
+                    workflowPath = childPath;
+                }
+                result.push({
+                    ...step,
+                    name: namespacedName,
+                    workflowPath,
+                });
+            }
+        }
+        else {
+            // Regular step - add as-is
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * Creates a workflow builder with compile-time dependency validation.
+ *
+ * This builder provides three modes:
+ * 1. build() - for workflows that don't require initial data
+ * 2. requires(fields).build() - for workflows that need the caller to provide specific fields
+ * 3. configure(configuration).requires(fields).build() - for workflows that need the bag
+ *    configured with specific values, as well as initial values provided at runtime
+ *
+ * The compile-time validation works by:
+ * - Analyzing the step dependencies using recursive conditional types
+ * - If validation fails, injecting an error property that causes a compile error
+ * - If validation passes, allowing the workflow to be created normally
+ *
+ * Usage:
+ *   // No initial data required
+ *   const wf1 = createWorkflow<Bag>("my-workflow").build([stepA, stepB]);
+ *
+ *   // Requires 'promptText' to be provided at runtime
+ *   const wf2 = createWorkflow<Bag>("prompt-workflow").requires("promptText").build([stepA, stepB]);
+ *
+ *   // Sets lotiContentType to "prompt_media" and requires 'promptText' to be
+ *   provided at runtime.
+ *   const wf3 = createWorkflow<Bag>("configured-prompt-workflow")
+ *     .configure({ lotiContentType: "prompt_media" })
+ *     .requires("promptText")
+ *     .build([stepA, stepB]);
+ */
+function createWorkflow(name) {
+    return {
+        // Build workflow without required initial fields
+        build(steps) {
+            const flattenedSteps = flattenSteps(steps, [name]);
+            assertUniqueStepNames(flattenedSteps);
+            assertNoDuplicatesInStepArrays(flattenedSteps);
+            return workflow(name, flattenedSteps, undefined);
+        },
+        // Allow specifying initial fields that will be provided at runtime (rest parameters)
+        requires(...fields) {
+            return {
+                // Build workflow with required initial fields
+                build(steps) {
+                    const flattenedSteps = flattenSteps(steps, [name]);
+                    assertUniqueStepNames(flattenedSteps);
+                    assertNoDuplicatesInStepArrays(flattenedSteps);
+                    return workflow(name, flattenedSteps, fields);
+                },
+            };
+        },
+        configure(configuration) {
+            return {
+                build(steps) {
+                    const flattenedSteps = flattenSteps(steps, [name]);
+                    assertUniqueStepNames(flattenedSteps);
+                    assertNoDuplicatesInStepArrays(flattenedSteps);
+                    return workflow(name, flattenedSteps, undefined, configuration);
+                },
+                // Exclude ConfigKeys to prevent requiring fields that are already configured
+                requires(...fields) {
+                    return {
+                        build(steps) {
+                            const flattenedSteps = flattenSteps(steps, [name]);
+                            assertUniqueStepNames(flattenedSteps);
+                            assertNoDuplicatesInStepArrays(flattenedSteps);
+                            return workflow(name, flattenedSteps, fields, configuration);
+                        },
+                    };
+                },
+            };
+        },
+    };
+}
+// Implementation
+async function runSyncWorkflow(wf, initialData, contextProvider, logger, enableDeepFreeze) {
+    // Resolve defaults for optional parameters
+    const log = logger ?? defaults_1.defaultLogger;
+    const deepFreeze_ = enableDeepFreeze ?? false;
+    // Generate workflowId for observability tracking
+    const workflowId = (0, uuid_1.v7)();
+    // Initialize bag outside try block so it's accessible in catch block
+    const configuredValues = (wf.configuredValues ?? {});
+    const bag = {
+        ...initialData,
+        ...configuredValues,
+    };
+    // Start workflow observability, catching any initialization errors
+    let workflowHandle;
+    try {
+        workflowHandle = (0, observability_1.startWorkflowObservability)(workflowId, wf, initialData, log);
+    }
+    catch (observabilityError) {
+        // Observability initialization failed - return error without throwing
+        const error = observabilityError instanceof Error
+            ? observabilityError
+            : new Error(String(observabilityError));
+        return {
+            bag: bag,
+            error: new errors_1.WorkflowStepError({
+                workflowId,
+                stepName: "__observability_init__",
+                batchNumber: 0,
+                originalError: error,
+                bagState: bag,
+                workflowPath: [],
+            }),
+        };
+    }
+    // Track execution context for enhanced error logging
+    const executionContext = {
+        stepName: undefined,
+        stepNumber: undefined,
+        totalSteps: wf.steps.length,
+        batchNumber: 0,
+        stepStartTime: undefined,
+    };
+    try {
+        // === PHASE 1: VALIDATION & PLANNING ===
+        // Validate that all step names are unique (defense-in-depth for dynamically constructed workflows)
+        assertUniqueStepNames(wf.steps);
+        // Validate that no step has duplicate entries in needs/provides arrays
+        assertNoDuplicatesInStepArrays(wf.steps);
+        // Plan workflow execution using topological sort
+        // This validates dependencies, detects cycles, and organizes steps into parallel execution batches
+        const initialFields = new Set([
+            ...Object.keys(configuredValues),
+            ...Object.keys(initialData ?? {}),
+        ]);
+        const plan = (0, workflow_planning_1.planWorkflowBatches)([...wf.steps], initialFields);
+        // === PHASE 2: EXECUTE BATCHES ===
+        // Each batch contains steps that can run in parallel
+        for (let batchIndex = 0; batchIndex < plan.batches.length; batchIndex++) {
+            const batch = plan.batches[batchIndex]; // Safe: within bounds check
+            const batchNumber = batchIndex + 1;
+            // Update execution context for current batch
+            executionContext.batchNumber = batchNumber;
+            // Start batch observability
+            const batchHandle = (0, observability_1.startBatchObservability)(workflowHandle, batchNumber, batch.map((step) => step.name));
+            // Execute all steps in this batch in parallel using allSettled
+            // This ensures all steps complete (even if some fail) so we can:
+            // 1. Collect outputs from successful steps
+            // 2. Aggregate all failures into a single WorkflowBatchError
+            const settledResults = await Promise.allSettled(batch.map(async (step) => {
+                // Update execution context for current step
+                executionContext.stepName = step.name;
+                executionContext.stepNumber =
+                    wf.steps.findIndex((workflowStep) => workflowStep.name === step.name) + 1; // 1-based indexing
+                executionContext.stepStartTime = Date.now();
+                // Start step observability
+                const stepHandle = (0, observability_1.startStepObservability)(workflowHandle, batchHandle, step);
+                // Create context via beforeStep hook if provider exists
+                let ctx;
+                if (contextProvider) {
+                    ctx = await contextProvider.beforeStep(step.name);
+                }
+                let stepError;
+                try {
+                    let stepOutput;
+                    if ((0, dag_sync_fanout_1.isFanOutStep)(step)) {
+                        stepOutput = await executeFanOut(step.__fanOut, step.name, bag, contextProvider, log, deepFreeze_);
+                    }
+                    else {
+                        // Build input object with only the fields this step needs
+                        const stepInput = step.needs.reduce((inputAcc, neededField) => {
+                            inputAcc[neededField] = bag[neededField];
+                            return inputAcc;
+                        }, {});
+                        // Freeze the step input if immutability protection is enabled
+                        // This prevents steps from modifying their input bag
+                        if (deepFreeze_) {
+                            Object.freeze(stepInput);
+                        }
+                        const syncRuntime = {
+                            heartbeat: () => { },
+                            getHeartbeatDetails: () => undefined,
+                        };
+                        // Object.assign preserves context identity and prototype chain when ctx is
+                        // a class instance, so afterStep receives the same object the step mutated.
+                        // Falls back to spread when ctx is undefined (no context provider).
+                        const stepCtx = ctx != null && typeof ctx === "object"
+                            ? Object.assign(ctx, syncRuntime)
+                            : syncRuntime;
+                        // Execute the step within the OTel step context for proper span hierarchy
+                        stepOutput = (await api_1.context.with(stepHandle.stepContext, () => step.run(stepCtx, stepInput)));
+                    }
+                    // End step observability - success
+                    (0, observability_1.endStepObservability)(stepHandle, {
+                        success: true,
+                        outputFields: Object.keys(stepOutput),
+                    });
+                    return { stepName: step.name, output: stepOutput };
+                }
+                catch (error) {
+                    // Wrap error with workflow context
+                    stepError = error instanceof Error ? error : new Error(String(error));
+                    const workflowError = new errors_1.WorkflowStepError({
+                        workflowId: workflowId,
+                        stepName: step.name,
+                        batchNumber,
+                        originalError: stepError,
+                        bagState: bag,
+                        workflowPath: step.workflowPath,
+                    });
+                    // End step observability - error
+                    (0, observability_1.endStepObservability)(stepHandle, {
+                        success: false,
+                        error: workflowError,
+                    });
+                    throw workflowError;
+                }
+                finally {
+                    // Call afterStep hook for cleanup if provider exists.
+                    // Wrapped in try/catch to prevent cleanup errors (e.g., EM flush failures)
+                    // from swallowing the original step error. The step's business logic error
+                    // is more important to surface than infrastructure cleanup errors.
+                    if (contextProvider && ctx !== undefined) {
+                        try {
+                            await contextProvider.afterStep(ctx, stepError);
+                        }
+                        catch (cleanupError) {
+                            log.error("afterStep cleanup failed", {
+                                stepName: step.name,
+                                workflowId,
+                                cleanupError: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+                                originalStepError: stepError?.message,
+                            });
+                        }
+                    }
+                }
+            }));
+            // Separate fulfilled and rejected results
+            const fulfilled = settledResults.filter((r) => r.status === "fulfilled");
+            const rejected = settledResults.filter((r) => r.status === "rejected");
+            // First, merge successful step outputs into the bag
+            // This ensures the bag has all available data even if some steps failed
+            for (const result of fulfilled) {
+                const { output } = result.value;
+                if (deepFreeze_) {
+                    for (const [key, value] of Object.entries(output)) {
+                        bag[key] = deepFreeze(value);
+                    }
+                }
+                else {
+                    Object.assign(bag, output);
+                }
+            }
+            // If any steps failed, aggregate into WorkflowBatchError
+            if (rejected.length > 0) {
+                const stepErrors = rejected.map((r) => r.reason);
+                // End batch observability - error
+                (0, observability_1.endBatchObservability)(batchHandle, {
+                    success: false,
+                    error: stepErrors[0], // Primary error for observability (safe: length > 0)
+                });
+                throw new errors_1.WorkflowBatchError({
+                    errors: stepErrors,
+                    bagState: bag,
+                    batchNumber,
+                    workflowId,
+                });
+            }
+            // End batch observability - success
+            (0, observability_1.endBatchObservability)(batchHandle, {
+                success: true,
+                outputFields: fulfilled.flatMap((r) => Object.keys(r.value.output)),
+            });
+        }
+        // End workflow observability - success
+        (0, observability_1.endWorkflowObservability)(workflowHandle, {
+            success: true,
+            batchCount: plan.batches.length,
+            outputFields: Object.keys(bag),
+        }, executionContext, bag);
+        return {
+            bag: bag,
+            error: undefined,
+        };
+    }
+    catch (error) {
+        // End workflow observability - error
+        (0, observability_1.endWorkflowObservability)(workflowHandle, {
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error)),
+        }, executionContext, bag);
+        // Cast bag for return type
+        const resultBag = bag;
+        // Invoke error handler if present
+        if (wf.errorHandler &&
+            (error instanceof errors_1.WorkflowStepError || error instanceof errors_1.WorkflowBatchError)) {
+            // Get context for error handler
+            let ctx;
+            if (contextProvider) {
+                try {
+                    ctx = await contextProvider.beforeStep("__errorHandler__");
+                }
+                catch (contextError) {
+                    // If we can't create context, proceed without it
+                    log.warn("Failed to create context for error handler", {
+                        workflowId,
+                        contextError: contextError instanceof Error ? contextError.message : String(contextError),
+                    });
+                }
+            }
+            try {
+                // Handler returns Error | undefined
+                // - undefined = handled, no error to propagate
+                // - Error = propagate that error (possibly transformed)
+                const handlerResult = await wf.errorHandler(ctx, bag, error);
+                // Clean up context if we created one
+                if (contextProvider && ctx !== undefined) {
+                    try {
+                        await contextProvider.afterStep(ctx, undefined);
+                    }
+                    catch (cleanupError) {
+                        log.error("afterStep cleanup failed for error handler", {
+                            workflowId,
+                            cleanupError: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+                        });
+                    }
+                }
+                // Return based on handler result
+                return {
+                    bag: resultBag,
+                    error: handlerResult, // undefined = handled, Error = propagate
+                };
+            }
+            catch (handlerError) {
+                // Handler threw unexpectedly - wrap both errors
+                // Clean up context if we created one
+                if (contextProvider && ctx !== undefined) {
+                    try {
+                        await contextProvider.afterStep(ctx, handlerError instanceof Error ? handlerError : undefined);
+                    }
+                    catch (cleanupError) {
+                        log.error("afterStep cleanup failed for error handler", {
+                            workflowId,
+                            cleanupError: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+                        });
+                    }
+                }
+                // Handler failed due to its own error (e.g., DB failure during cleanup)
+                return {
+                    bag: resultBag,
+                    error: new errors_1.WorkflowErrorHandlerFailure({
+                        originalError: error,
+                        handlerError: handlerError instanceof Error ? handlerError : new Error(String(handlerError)),
+                        workflowId,
+                    }),
+                };
+            }
+        }
+        // No handler - return original error
+        return {
+            bag: resultBag,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * Executes a FanOut step using the lane-based concurrency pattern.
+ *
+ * 1. Calls mapInput to produce child workflow inputs from the current bag
+ * 2. Spawns min(concurrency, N) async lanes that pull work from a shared index
+ * 3. Each lane runs child workflows via runSyncWorkflow, collecting results
+ * 4. After all lanes complete, separates successes from failures
+ * 5. If all children succeed, calls aggregateResults to produce the step output
+ * 6. If any children fail, throws AggregateError containing child errors
+ *    (compatible with extractErrorCandidates via .errors[])
+ */
+async function executeFanOut(metadata, fanOutName, currentBag, contextProvider, logger, enableDeepFreeze) {
+    const { childWorkflow, mapInput, aggregateResults, concurrency } = metadata;
+    const inputs = mapInput(currentBag);
+    if (inputs.length === 0) {
+        return aggregateResults([]);
+    }
+    const laneCount = Math.min(concurrency, inputs.length);
+    const results = new Array(inputs.length);
+    let nextIndex = 0;
+    const lane = async () => {
+        while (true) {
+            const index = nextIndex++;
+            if (index >= inputs.length)
+                break;
+            // Cast: type safety is enforced at the fanOut() factory level, not here
+            const childResult = await runSyncWorkflow(childWorkflow, inputs[index], contextProvider, logger, enableDeepFreeze);
+            if (childResult.error) {
+                results[index] = { error: childResult.error };
+            }
+            else {
+                results[index] = { bag: childResult.bag };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: laneCount }, () => lane()));
+    const errors = [];
+    const successfulBags = [];
+    for (const result of results) {
+        if (!result)
+            continue;
+        if ("error" in result) {
+            errors.push(result.error);
+        }
+        else {
+            successfulBags.push(result.bag);
+        }
+    }
+    if (errors.length > 0) {
+        throw new AggregateError(errors, `FanOut "${fanOutName}": ${errors.length} of ${inputs.length} child workflow(s) failed`);
+    }
+    return aggregateResults(successfulBags);
+}
+//# sourceMappingURL=dag-sync-workflow.js.map