@doclo/flows 0.1.2

package/dist/index.js

@@ -0,0 +1,2534 @@
+import {
+  simpleSchema
+} from "./chunk-USCWPTGU.js";
+
+// src/index.ts
+import { runPipeline as runPipeline4 } from "@doclo/core";
+import { parseNode as parseNode2, extractNode as extractNode2 } from "@doclo/nodes";
+
+// src/flow-builder.ts
+import {
+  runPipeline,
+  FlowExecutionError,
+  aggregateMetrics,
+  getNodeTypeName,
+  validateNodeConnection,
+  canStartForEachItemFlow,
+  getValidForEachStarters,
+  getProviderById,
+  validateFlowInputFormat
+} from "@doclo/core";
+import { shouldSkipValidation } from "@doclo/core/runtime/env";
+import { output as createOutputNode } from "@doclo/nodes";
+import {
+  mergeConfig,
+  shouldSample,
+  TraceContextManager,
+  generateExecutionId,
+  executeHook,
+  buildStepAttributes,
+  generateSpanId
+} from "@doclo/core/observability";
+function isSingleFlowResult(result) {
+  return "output" in result && "artifacts" in result;
+}
+function normalizeFlowInput(input) {
+  if (input == null) {
+    return input;
+  }
+  if (typeof input === "object" && (input.base64 || input.url)) {
+    return input;
+  }
+  if (typeof input === "string") {
+    if (input.startsWith("data:")) {
+      return { base64: input };
+    }
+    if (input.startsWith("http://") || input.startsWith("https://")) {
+      return { url: input };
+    }
+    return { base64: input };
+  }
+  return input;
+}
+var Flow = class {
+  steps = [];
+  observability;
+  metadata;
+  inputValidation;
+  traceContextManager;
+  currentExecution;
+  constructor(options) {
+    if (options?.observability) {
+      this.observability = mergeConfig(options.observability);
+      this.traceContextManager = new TraceContextManager(this.observability);
+    }
+    if (options?.metadata) {
+      this.metadata = options.metadata;
+    }
+    if (options?.inputValidation) {
+      this.inputValidation = options.inputValidation;
+    }
+  }
+  /**
+   * Set accepted input formats for this flow (fluent API).
+   * Validates input format before flow execution begins.
+   *
+   * @param formats - List of accepted MIME types (e.g., ['application/pdf', 'image/jpeg'])
+   * @returns This flow instance for chaining
+   *
+   * @example
+   * ```typescript
+   * const pdfOnlyFlow = createFlow()
+   *   .acceptFormats(['application/pdf'])
+   *   .step('parse', parse({ provider }))
+   *   .build();
+   *
+   * // Throws FlowInputValidationError if input is not a PDF
+   * await pdfOnlyFlow.run({ base64: jpegBase64 });
+   * ```
+   */
+  acceptFormats(formats) {
+    this.inputValidation = { acceptedFormats: formats };
+    return this;
+  }
+  /**
+   * Add a sequential step to the flow
+   */
+  step(id, node2, name) {
+    this.steps.push({
+      type: "step",
+      id,
+      name,
+      node: node2
+    });
+    return this;
+  }
+  /**
+   * Add a conditional step that chooses a node based on input data
+   *
+   * IMPORTANT: Conditionals must return a NODE, not a promise or executed flow.
+   * The SDK will execute the returned node for you.
+   *
+   * The condition function receives the full wrapped data (e.g., { input, quality })
+   * but the returned node should accept the unwrapped input (e.g., just FlowInput).
+   * The SDK automatically unwraps the data before passing it to the selected node.
+   *
+   * ✅ CORRECT - Return a node (declarative):
+   * ```typescript
+   * .step('qualify', qualify({ provider, levels: ['low', 'medium', 'high'] }))
+   * .conditional('parse', (data) => {
+   *   // data is { input: FlowInput, quality: string }
+   *   if (data.quality === 'high') {
+   *     return parse({ provider: fastProvider });  // Return the node
+   *   }
+   *   return parse({ provider: accurateProvider }); // Return the node
+   * })
+   * ```
+   *
+   * ❌ INCORRECT - Do NOT return a promise (imperative):
+   * ```typescript
+   * .conditional('parse', (data) => {
+   *   // This will throw an error!
+   *   return createFlow()
+   *     .step('parse', parse({ provider }))
+   *     .build()
+   *     .run(data.input)  // ❌ Don't call .run() here!
+   *     .then(r => r.output);
+   * })
+   * ```
+   *
+   * 🆕 NEW - Access previous step outputs via context:
+   * ```typescript
+   * .step('categorize', categorize({ provider, categories }))
+   * .conditional('parse', (data) => parse({ provider }))
+   * .conditional('extract', (data, context) => {
+   *   // Access category from earlier step via context.artifacts
+   *   const category = context?.artifacts.categorize?.category;
+   *   return extract({ provider, schema: SCHEMAS[category] });
+   * })
+   * ```
+   *
+   * Use the declarative pattern (return nodes) for consistent flow execution,
+   * proper error tracking, and accurate metrics collection.
+   */
+  conditional(id, condition, name) {
+    this.steps.push({
+      type: "conditional",
+      id,
+      name,
+      condition
+    });
+    return this;
+  }
+  /**
+   * Process each item from previous step (which must return an array) with a child flow
+   * Each item is processed in parallel as its own isolated run
+   */
+  forEach(id, childFlow, name) {
+    this.steps.push({
+      type: "forEach",
+      id,
+      name,
+      childFlow
+    });
+    return this;
+  }
+  /**
+   * Add an explicit output node to mark which data to return from the flow
+   *
+   * By default, flows return the output of the last step. Use output nodes to:
+   * - Return data from earlier steps
+   * - Return multiple named outputs
+   * - Transform outputs before returning
+   *
+   * @param config - Output configuration
+   * @returns Flow with output node added
+   *
+   * @example
+   * // Single output
+   * .output({ name: 'invoice_data' })
+   *
+   * // Select specific source
+   * .output({ name: 'result', source: 'step2' })
+   *
+   * // Multiple outputs
+   * .step('extract1', extract({ provider, schema1 }))
+   * .output({ name: 'summary', source: 'extract1' })
+   * .step('extract2', extract({ provider, schema2 }))
+   * .output({ name: 'details', source: 'extract2' })
+   */
+  output(config) {
+    const name = config?.name?.trim();
+    const stepId = name || this.generateOutputStepId();
+    this.steps.push({
+      type: "step",
+      id: stepId,
+      node: createOutputNode({
+        ...config,
+        name: stepId
+        // Ensure name matches step ID
+      })
+    });
+    return this;
+  }
+  /**
+   * Get current execution context
+   *
+   * Returns null if not currently executing.
+   */
+  getExecutionContext() {
+    return this.currentExecution ?? null;
+  }
+  /**
+   * Get current trace context
+   *
+   * Returns null if not currently executing or observability not configured.
+   */
+  getTraceContext() {
+    return this.traceContextManager?.getTraceContext() ?? null;
+  }
+  /**
+   * Set a custom attribute on the current execution
+   *
+   * Custom attributes appear in execution context and can be accessed by hooks.
+   */
+  setCustomAttribute(key, value) {
+    if (this.currentExecution) {
+      this.currentExecution.customAttributes[key] = value;
+    }
+  }
+  /**
+   * Record a custom metric for the current execution
+   *
+   * Custom metrics appear in execution context and can be accessed by hooks.
+   */
+  recordMetric(name, value, unit) {
+    if (this.currentExecution) {
+      this.currentExecution.customMetrics.push({
+        name,
+        value,
+        unit,
+        timestamp: Date.now()
+      });
+    }
+  }
+  /**
+   * Build and return the executable flow
+   */
+  build() {
+    return {
+      run: async (input, callbacks) => {
+        return this.execute(input, callbacks);
+      },
+      validate: () => {
+        return this.validate();
+      }
+    };
+  }
+  /**
+   * Generate a unique step ID for unnamed output nodes
+   * Prevents duplicate IDs when multiple .output() calls without names
+   */
+  generateOutputStepId() {
+    let counter = 0;
+    let candidateId = "output";
+    while (this.steps.some((step) => step.id === candidateId)) {
+      counter++;
+      candidateId = `output_${counter}`;
+    }
+    return candidateId;
+  }
+  /**
+   * Validate the flow configuration
+   */
+  validate() {
+    const errors = [];
+    const warnings = [];
+    if (this.steps.length === 0) {
+      errors.push({
+        stepId: "<flow>",
+        stepIndex: -1,
+        stepType: "flow",
+        message: "Flow has no steps. Add at least one step using .step(), .conditional(), or .forEach()"
+      });
+    }
+    for (let stepIndex = 0; stepIndex < this.steps.length; stepIndex++) {
+      const step = this.steps[stepIndex];
+      const duplicateIndex = this.steps.findIndex((s, i) => i !== stepIndex && s.id === step.id);
+      if (duplicateIndex !== -1) {
+        errors.push({
+          stepId: step.id,
+          stepIndex,
+          stepType: step.type,
+          message: `Duplicate step ID "${step.id}" found at indices ${stepIndex} and ${duplicateIndex}`
+        });
+      }
+      if (step.type === "step") {
+        if (!step.node) {
+          errors.push({
+            stepId: step.id,
+            stepIndex,
+            stepType: step.type,
+            message: "Step node is missing. Use parse(), qualify(), categorize(), extract(), or split()"
+          });
+        }
+      } else if (step.type === "conditional") {
+        if (!step.condition || typeof step.condition !== "function") {
+          errors.push({
+            stepId: step.id,
+            stepIndex,
+            stepType: step.type,
+            message: "Conditional must have a condition function"
+          });
+        }
+      } else if (step.type === "forEach") {
+        if (!step.childFlow || typeof step.childFlow !== "function") {
+          errors.push({
+            stepId: step.id,
+            stepIndex,
+            stepType: step.type,
+            message: "forEach must have a childFlow function"
+          });
+        }
+        if (stepIndex === 0) {
+          warnings.push(`forEach step "${step.id}" at index ${stepIndex} is the first step - ensure input is an array`);
+        }
+      }
+      if (!step.id || step.id.trim() === "") {
+        errors.push({
+          stepId: "<empty>",
+          stepIndex,
+          stepType: step.type,
+          message: "Step ID cannot be empty"
+        });
+      }
+    }
+    if (!shouldSkipValidation()) {
+      this.validateTypeCompatibility(errors, warnings);
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+  /**
+   * Validate type compatibility between consecutive steps
+   */
+  validateTypeCompatibility(errors, warnings) {
+    for (let i = 0; i < this.steps.length - 1; i++) {
+      const currentStep = this.steps[i];
+      const nextStep = this.steps[i + 1];
+      if (currentStep.type === "step" && nextStep.type === "step") {
+        const sourceType = getNodeTypeName(currentStep.node);
+        const targetType = getNodeTypeName(nextStep.node);
+        if (!sourceType || !targetType) {
+          continue;
+        }
+        const forEachEnabled = false;
+        const validation = validateNodeConnection(sourceType, targetType, forEachEnabled);
+        if (!validation.valid) {
+          errors.push({
+            stepId: currentStep.id,
+            stepIndex: i,
+            stepType: currentStep.type,
+            message: `Invalid connection: ${sourceType} \u2192 ${targetType}. ${validation.reason || "Types incompatible"}`
+          });
+          if (validation.suggestions && validation.suggestions.length > 0) {
+            warnings.push(`Suggestions for step "${currentStep.id}":`);
+            validation.suggestions.forEach((s) => warnings.push(`  ${s}`));
+          }
+        } else if (validation.warning) {
+          warnings.push(`Step "${currentStep.id}" \u2192 "${nextStep.id}": ${validation.warning}`);
+        }
+      }
+      if (currentStep.type === "step" && nextStep.type === "forEach") {
+        const sourceType = getNodeTypeName(currentStep.node);
+        if (sourceType) {
+          const sourceInfo = currentStep.node.__meta;
+          const outputsArray = sourceInfo?.outputsArray;
+          const isArrayOutput = typeof outputsArray === "function" ? outputsArray(null) : outputsArray;
+          if (!isArrayOutput) {
+            warnings.push(
+              `forEach step "${nextStep.id}" requires array input. Previous step "${currentStep.id}" (${sourceType}) may not output an array. Ensure ${sourceType} is configured to output an array (e.g., parse with chunked:true).`
+            );
+          }
+          if (nextStep.childFlow && typeof nextStep.childFlow === "function") {
+            try {
+              const childFlowInstance = nextStep.childFlow(null);
+              const childSteps = childFlowInstance.steps;
+              if (childSteps && Array.isArray(childSteps) && childSteps.length > 0) {
+                const firstStep = childSteps[0];
+                if (firstStep.type === "step") {
+                  const firstNodeType = getNodeTypeName(firstStep.node);
+                  if (firstNodeType) {
+                    const validation = canStartForEachItemFlow(sourceType, firstNodeType);
+                    if (!validation.valid) {
+                      errors.push({
+                        stepId: nextStep.id,
+                        stepIndex: i + 1,
+                        stepType: "forEach",
+                        message: `Invalid forEach itemFlow starter: ${validation.reason || `${firstNodeType} cannot start forEach itemFlow after ${sourceType}`}`
+                      });
+                      if (validation.suggestions && validation.suggestions.length > 0) {
+                        warnings.push(`Suggestions for forEach "${nextStep.id}":`);
+                        validation.suggestions.forEach((s) => warnings.push(`  ${s}`));
+                      }
+                    }
+                  }
+                } else if (firstStep.type === "forEach") {
+                  if (sourceType === "split") {
+                    errors.push({
+                      stepId: nextStep.id,
+                      stepIndex: i + 1,
+                      stepType: "forEach",
+                      message: "Invalid forEach itemFlow: Cannot nest forEach operations. Split nodes cannot appear in forEach itemFlow."
+                    });
+                  }
+                }
+              }
+            } catch (error) {
+              warnings.push(
+                `forEach step "${nextStep.id}": Unable to validate itemFlow structure. Ensure the first node in itemFlow is compatible with ${sourceType} output. Valid starters: ${getValidForEachStarters(sourceType).join(", ")}`
+              );
+            }
+          }
+        }
+      }
+    }
+    this.checkEfficiencyPatterns(warnings);
+  }
+  /**
+   * Check for inefficient flow patterns and add warnings.
+   *
+   * Detects patterns like:
+   * - parse() → extract(raw-document-provider): The extract provider ignores parse output
+   */
+  checkEfficiencyPatterns(warnings) {
+    for (let i = 0; i < this.steps.length - 1; i++) {
+      const current = this.steps[i];
+      const next = this.steps[i + 1];
+      if (current.type !== "step" || next.type !== "step") continue;
+      const currNodeType = getNodeTypeName(current.node);
+      const nextNodeType = getNodeTypeName(next.node);
+      if (currNodeType === "parse" && nextNodeType === "extract") {
+        const extractProvider = this.getProviderFromNode(next.node);
+        if (extractProvider) {
+          const metadata = getProviderById(extractProvider);
+          if (metadata?.inputRequirements?.inputType === "raw-document") {
+            warnings.push(
+              `Efficiency warning: Step "${current.id}" (parse) output may be ignored. "${metadata.name}" processes raw documents directly, not parsed text. Consider: (1) Remove the parse step, or (2) Use an LLM provider for extraction that can use parsed text.`
+            );
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Extract provider ID from a node definition.
+   * Returns undefined if provider cannot be determined.
+   */
+  getProviderFromNode(node2) {
+    const config = node2.__meta?.config;
+    if (config?.provider) {
+      if (typeof config.provider === "string") {
+        return config.provider;
+      }
+      if (typeof config.provider === "object") {
+        return config.provider.id ?? config.provider.name;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Execute the flow with optional progress callbacks
+   */
+  async execute(input, callbacks) {
+    const flowStartTime = Date.now();
+    const artifacts = {};
+    const metrics = [];
+    const completedSteps = [];
+    const outputs = {};
+    let lastNonOutputData = null;
+    let executionId;
+    let traceContext;
+    let sampled = false;
+    if (this.observability) {
+      sampled = shouldSample(this.observability);
+      if (this.traceContextManager && sampled) {
+        traceContext = this.traceContextManager.initialize(sampled);
+      }
+      const execIdGenerator = this.observability.generateExecutionId ?? generateExecutionId;
+      executionId = execIdGenerator();
+      this.currentExecution = {
+        flowId: "flow",
+        // TODO: Add flowId to Flow class
+        executionId,
+        startTime: flowStartTime,
+        status: "running",
+        customAttributes: {},
+        customMetrics: []
+      };
+      if (sampled && traceContext) {
+        const flowStartContext = {
+          flowId: "flow",
+          // TODO: Add flowId
+          flowVersion: "0.0.1",
+          executionId,
+          timestamp: flowStartTime,
+          input,
+          config: {},
+          // TODO: Capture flow config
+          metadata: this.metadata,
+          sdkVersion: "0.0.1",
+          observabilityVersion: this.observability.observabilityVersion ?? "1.0.0",
+          traceContext
+        };
+        await executeHook(this.observability.onFlowStart, {
+          hookName: "onFlowStart",
+          config: this.observability,
+          context: flowStartContext
+        });
+      }
+    }
+    let currentData = normalizeFlowInput(input);
+    if (this.inputValidation?.acceptedFormats?.length) {
+      const dataUrl = currentData?.base64 || currentData?.url;
+      if (dataUrl) {
+        validateFlowInputFormat(dataUrl, this.inputValidation.acceptedFormats);
+      }
+    }
+    try {
+      for (let stepIndex = 0; stepIndex < this.steps.length; stepIndex++) {
+        const step = this.steps[stepIndex];
+        const stepStartTime = Date.now();
+        const stepSpanId = this.traceContextManager && sampled ? generateSpanId() : void 0;
+        callbacks?.onStepStart?.(step.id, stepIndex, step.type);
+        if (this.observability && sampled && traceContext && executionId && stepSpanId) {
+          const stepStartContext = {
+            flowId: "flow",
+            executionId,
+            stepId: step.id,
+            stepIndex,
+            stepType: step.node?.key ?? step.type,
+            stepName: step.name ?? step.id,
+            timestamp: stepStartTime,
+            provider: void 0,
+            // Will be populated from step config if available
+            model: void 0,
+            config: {},
+            input: currentData,
+            isConsensusEnabled: false,
+            // TODO: Check step config for consensus
+            isRetry: false,
+            metadata: this.metadata,
+            traceContext,
+            spanId: stepSpanId
+          };
+          await executeHook(this.observability.onStepStart, {
+            hookName: "onStepStart",
+            config: this.observability,
+            context: stepStartContext
+          });
+        }
+        try {
+          if (step.type === "step") {
+            const isOutputNode = step.node?.__meta?.isOutputNode === true;
+            const outputName = step.node?.__meta?.outputName?.trim() || step.id;
+            let result2;
+            if (isOutputNode) {
+              const ctx = {
+                stepId: step.id,
+                artifacts,
+                emit: (k, v) => {
+                  artifacts[k] = v;
+                },
+                metrics: { push: (m) => metrics.push(m) },
+                observability: this.observability && sampled ? {
+                  config: this.observability,
+                  flowId: "flow",
+                  executionId,
+                  stepId: step.id,
+                  stepIndex,
+                  traceContext,
+                  metadata: this.metadata
+                } : void 0
+              };
+              const outputData = await step.node.run(currentData, ctx);
+              result2 = { output: outputData, artifacts: {}, metrics: [] };
+              outputs[outputName] = outputData;
+              artifacts[step.id] = outputData;
+              completedSteps.push(step.id);
+              const stepDuration = Date.now() - stepStartTime;
+              callbacks?.onStepComplete?.(step.id, stepIndex, step.type, stepDuration);
+              if (this.observability && sampled && traceContext && executionId && stepSpanId) {
+                const stepEndContext = {
+                  flowId: "flow",
+                  executionId,
+                  stepId: step.id,
+                  stepIndex,
+                  timestamp: Date.now(),
+                  startTime: stepStartTime,
+                  duration: stepDuration,
+                  output: outputData,
+                  usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+                  cost: 0,
+                  metricKind: "prep",
+                  // Output nodes are prep steps (no API call)
+                  otelAttributes: buildStepAttributes({
+                    stepType: step.node?.key ?? step.type
+                  }),
+                  metadata: this.metadata,
+                  traceContext,
+                  spanId: stepSpanId
+                };
+                await executeHook(this.observability.onStepEnd, {
+                  hookName: "onStepEnd",
+                  config: this.observability,
+                  context: stepEndContext
+                });
+              }
+              currentData = lastNonOutputData !== null ? lastNonOutputData : currentData;
+            } else {
+              result2 = await runPipeline([step.node], currentData, this.observability && sampled ? {
+                config: this.observability,
+                flowId: "flow",
+                executionId,
+                stepId: step.id,
+                stepIndex,
+                traceContext,
+                metadata: this.metadata
+              } : {
+                // Always pass stepId for metrics tracking, even without observability
+                stepId: step.id
+              });
+              artifacts[step.id] = result2.output;
+              metrics.push(...result2.metrics);
+              completedSteps.push(step.id);
+              const stepDuration = Date.now() - stepStartTime;
+              callbacks?.onStepComplete?.(step.id, stepIndex, step.type, stepDuration);
+              if (this.observability && sampled && traceContext && executionId && stepSpanId) {
+                const leafMetrics = result2.metrics.filter((m) => m.metadata?.kind === "leaf");
+                const wrapperMetric = result2.metrics.find((m) => m.metadata?.kind === "wrapper");
+                const stepLeafMetrics = result2.metrics.filter(
+                  (m) => m.configStepId === step.id && m.metadata?.kind === "leaf"
+                );
+                const isConsensus = stepLeafMetrics.length > 1;
+                const stepOwnLeafMetric = isConsensus ? void 0 : stepLeafMetrics[0];
+                const hasOtherChildMetrics = result2.metrics.some((m) => m.configStepId !== step.id);
+                const hasChildMetrics = isConsensus || hasOtherChildMetrics || leafMetrics.length > 1;
+                let metricKind;
+                let ownDuration;
+                let ownCost;
+                let ownInputTokens;
+                let ownOutputTokens;
+                let ownCacheCreationTokens;
+                let ownCacheReadTokens;
+                if (isConsensus) {
+                  metricKind = "wrapper";
+                  ownDuration = wrapperMetric?.metadata?.overheadMs ?? 0;
+                  ownCost = 0;
+                  ownInputTokens = 0;
+                  ownOutputTokens = 0;
+                  ownCacheCreationTokens = void 0;
+                  ownCacheReadTokens = void 0;
+                } else if (stepOwnLeafMetric) {
+                  metricKind = hasOtherChildMetrics ? "wrapper" : "leaf";
+                  ownDuration = stepOwnLeafMetric.ms ?? 0;
+                  ownCost = stepOwnLeafMetric.costUSD ?? 0;
+                  ownInputTokens = stepOwnLeafMetric.inputTokens ?? 0;
+                  ownOutputTokens = stepOwnLeafMetric.outputTokens ?? 0;
+                  ownCacheCreationTokens = stepOwnLeafMetric.cacheCreationInputTokens;
+                  ownCacheReadTokens = stepOwnLeafMetric.cacheReadInputTokens;
+                } else if (wrapperMetric || hasChildMetrics) {
+                  metricKind = "wrapper";
+                  ownDuration = wrapperMetric?.metadata?.overheadMs ?? 0;
+                  ownCost = 0;
+                  ownInputTokens = 0;
+                  ownOutputTokens = 0;
+                  ownCacheCreationTokens = void 0;
+                  ownCacheReadTokens = void 0;
+                } else {
+                  metricKind = "prep";
+                  ownDuration = stepDuration;
+                  ownCost = 0;
+                  ownInputTokens = 0;
+                  ownOutputTokens = 0;
+                  ownCacheCreationTokens = void 0;
+                  ownCacheReadTokens = void 0;
+                }
+                const firstMetric = result2.metrics.length > 0 ? result2.metrics[0] : void 0;
+                const stepEndContext = {
+                  flowId: "flow",
+                  executionId,
+                  stepId: step.id,
+                  stepIndex,
+                  timestamp: Date.now(),
+                  startTime: stepStartTime,
+                  duration: ownDuration,
+                  output: result2.output,
+                  usage: {
+                    inputTokens: ownInputTokens,
+                    outputTokens: ownOutputTokens,
+                    totalTokens: ownInputTokens + ownOutputTokens,
+                    cacheCreationInputTokens: ownCacheCreationTokens,
+                    cacheReadInputTokens: ownCacheReadTokens
+                  },
+                  cost: ownCost,
+                  metricKind,
+                  otelAttributes: buildStepAttributes({
+                    stepType: step.node?.key ?? step.type,
+                    provider: firstMetric?.provider,
+                    model: firstMetric?.model,
+                    inputTokens: ownInputTokens,
+                    outputTokens: ownOutputTokens
+                  }),
+                  metadata: this.metadata,
+                  traceContext,
+                  spanId: stepSpanId
+                };
+                await executeHook(this.observability.onStepEnd, {
+                  hookName: "onStepEnd",
+                  config: this.observability,
+                  context: stepEndContext
+                });
+              }
+              lastNonOutputData = result2.output;
+              const hasNextStep = stepIndex < this.steps.length - 1;
+              const nextStep = hasNextStep ? this.steps[stepIndex + 1] : null;
+              const shouldUnwrap = hasNextStep && nextStep?.type === "step" && result2.output && typeof result2.output === "object" && "input" in result2.output;
+              if (shouldUnwrap) {
+                currentData = result2.output.input;
+              } else {
+                currentData = result2.output;
+              }
+            }
+          } else if (step.type === "conditional") {
+            const context = {
+              artifacts: { ...artifacts },
+              metrics: [...metrics]
+            };
+            const node2 = step.condition(currentData, context);
+            if (!node2 || typeof node2 !== "object" || !node2.key || typeof node2.run !== "function") {
+              throw new Error(
+                `Conditional step "${step.id}" must return a node (e.g., parse(), categorize(), extract()). Got: ${typeof node2}${node2 && typeof node2 === "object" ? ` with keys: ${Object.keys(node2).join(", ")}` : ""}. 
+
+A valid node must have 'key' and 'run' properties.
+
+Incorrect: .conditional('step', () => flow.run(...).then(r => r.output))
+Correct: .conditional('step', () => parse({ provider }))`
+              );
+            }
+            const nodeInput = currentData && typeof currentData === "object" && "input" in currentData ? currentData.input : currentData;
+            const result2 = await runPipeline([node2], nodeInput, this.observability && sampled ? {
+              config: this.observability,
+              flowId: "flow",
+              executionId,
+              stepId: step.id,
+              stepIndex,
+              traceContext,
+              metadata: this.metadata
+            } : void 0);
+            artifacts[step.id] = result2.output;
+            metrics.push(...result2.metrics);
+            completedSteps.push(step.id);
+            const stepDuration = Date.now() - stepStartTime;
+            callbacks?.onStepComplete?.(step.id, stepIndex, step.type, stepDuration);
+            if (this.observability && sampled && traceContext && executionId && stepSpanId) {
+              const leafMetrics = result2.metrics.filter((m) => m.metadata?.kind === "leaf");
+              const wrapperMetric = result2.metrics.find((m) => m.metadata?.kind === "wrapper");
+              const stepLeafMetrics = result2.metrics.filter(
+                (m) => m.configStepId === step.id && m.metadata?.kind === "leaf"
+              );
+              const isConsensus = stepLeafMetrics.length > 1;
+              const stepOwnLeafMetric = isConsensus ? void 0 : stepLeafMetrics[0];
+              const hasOtherChildMetrics = result2.metrics.some((m) => m.configStepId !== step.id);
+              const hasChildMetrics = isConsensus || hasOtherChildMetrics || leafMetrics.length > 1;
+              let metricKind;
+              let ownDuration;
+              let ownCost;
+              let ownInputTokens;
+              let ownOutputTokens;
+              let ownCacheCreationTokens;
+              let ownCacheReadTokens;
+              if (isConsensus) {
+                metricKind = "wrapper";
+                ownDuration = wrapperMetric?.metadata?.overheadMs ?? 0;
+                ownCost = 0;
+                ownInputTokens = 0;
+                ownOutputTokens = 0;
+                ownCacheCreationTokens = void 0;
+                ownCacheReadTokens = void 0;
+              } else if (stepOwnLeafMetric) {
+                metricKind = hasOtherChildMetrics ? "wrapper" : "leaf";
+                ownDuration = stepOwnLeafMetric.ms ?? 0;
+                ownCost = stepOwnLeafMetric.costUSD ?? 0;
+                ownInputTokens = stepOwnLeafMetric.inputTokens ?? 0;
+                ownOutputTokens = stepOwnLeafMetric.outputTokens ?? 0;
+                ownCacheCreationTokens = stepOwnLeafMetric.cacheCreationInputTokens;
+                ownCacheReadTokens = stepOwnLeafMetric.cacheReadInputTokens;
+              } else if (wrapperMetric || hasChildMetrics) {
+                metricKind = "wrapper";
+                ownDuration = wrapperMetric?.metadata?.overheadMs ?? 0;
+                ownCost = 0;
+                ownInputTokens = 0;
+                ownOutputTokens = 0;
+                ownCacheCreationTokens = void 0;
+                ownCacheReadTokens = void 0;
+              } else {
+                metricKind = "prep";
+                ownDuration = stepDuration;
+                ownCost = 0;
+                ownInputTokens = 0;
+                ownOutputTokens = 0;
+                ownCacheCreationTokens = void 0;
+                ownCacheReadTokens = void 0;
+              }
+              const firstMetric = result2.metrics.length > 0 ? result2.metrics[0] : void 0;
+              const stepEndContext = {
+                flowId: "flow",
+                executionId,
+                stepId: step.id,
+                stepIndex,
+                timestamp: Date.now(),
+                startTime: stepStartTime,
+                duration: ownDuration,
+                output: result2.output,
+                usage: {
+                  inputTokens: ownInputTokens,
+                  outputTokens: ownOutputTokens,
+                  totalTokens: ownInputTokens + ownOutputTokens,
+                  cacheCreationInputTokens: ownCacheCreationTokens,
+                  cacheReadInputTokens: ownCacheReadTokens
+                },
+                cost: ownCost,
+                metricKind,
+                otelAttributes: buildStepAttributes({
+                  stepType: "conditional",
+                  provider: firstMetric?.provider,
+                  model: firstMetric?.model,
+                  inputTokens: ownInputTokens,
+                  outputTokens: ownOutputTokens
+                }),
+                metadata: this.metadata,
+                traceContext,
+                spanId: stepSpanId
+              };
+              await executeHook(this.observability.onStepEnd, {
+                hookName: "onStepEnd",
+                config: this.observability,
+                context: stepEndContext
+              });
+            }
+            lastNonOutputData = result2.output;
+            currentData = result2.output;
+          } else if (step.type === "forEach") {
+            if (!Array.isArray(currentData)) {
+              throw new Error(`forEach step "${step.id}" requires array input, got ${typeof currentData}`);
+            }
+            const items = currentData;
+            const batchId = executionId ? `${executionId}-batch-${stepIndex}` : `batch-${stepIndex}`;
+            const batchStartTime = Date.now();
+            if (this.observability && sampled && traceContext && executionId) {
+              const batchStartContext = {
+                flowId: "flow",
+                executionId,
+                batchId,
+                stepId: step.id,
+                totalItems: items.length,
+                timestamp: batchStartTime,
+                metadata: this.metadata,
+                traceContext
+              };
+              await executeHook(this.observability.onBatchStart, {
+                hookName: "onBatchStart",
+                config: this.observability,
+                context: batchStartContext
+              });
+            }
+            const results = await Promise.allSettled(
+              items.map(async (item, itemIndex) => {
+                const itemStartTime = Date.now();
+                const itemSpanId = this.traceContextManager && sampled ? generateSpanId() : void 0;
+                if (this.observability && sampled && traceContext && executionId) {
+                  const batchItemContext = {
+                    flowId: "flow",
+                    executionId,
+                    batchId,
+                    stepId: step.id,
+                    itemIndex,
+                    totalItems: items.length,
+                    timestamp: itemStartTime,
+                    item,
+                    metadata: this.metadata,
+                    traceContext
+                  };
+                  await executeHook(this.observability.onBatchItemStart, {
+                    hookName: "onBatchItemStart",
+                    config: this.observability,
+                    context: batchItemContext
+                  });
+                }
+                try {
+                  const childFlow = step.childFlow(item);
+                  const builtFlow = childFlow.build();
+                  const flowInput = item && typeof item === "object" && "input" in item ? item.input : item;
+                  const result2 = await builtFlow.run(flowInput);
+                  let itemResult;
+                  if ("results" in result2 && Array.isArray(result2.results)) {
+                    const aggregatedMetrics = (result2.results || []).flatMap((r) => r && r.metrics || []);
+                    const aggregatedArtifacts = (result2.results || []).map((r) => r && r.artifacts);
+                    itemResult = {
+                      output: (result2.results || []).map((r) => r && r.output),
+                      metrics: aggregatedMetrics,
+                      artifacts: aggregatedArtifacts
+                    };
+                  } else {
+                    const flowResult = result2;
+                    itemResult = {
+                      output: flowResult.output,
+                      metrics: flowResult.metrics || [],
+                      artifacts: flowResult.artifacts || {}
+                    };
+                  }
+                  if (this.observability && sampled && traceContext && executionId) {
+                    const batchItemEndContext = {
+                      flowId: "flow",
+                      executionId,
+                      batchId,
+                      stepId: step.id,
+                      itemIndex,
+                      totalItems: items.length,
+                      item,
+                      timestamp: Date.now(),
+                      duration: Date.now() - itemStartTime,
+                      result: itemResult.output,
+                      status: "success",
+                      metadata: this.metadata,
+                      traceContext
+                    };
+                    await executeHook(this.observability.onBatchItemEnd, {
+                      hookName: "onBatchItemEnd",
+                      config: this.observability,
+                      context: batchItemEndContext
+                    });
+                  }
+                  return itemResult;
+                } catch (error) {
+                  console.error("[forEach error]", error);
+                  if (this.observability && sampled && traceContext && executionId) {
+                    const batchItemEndContext = {
+                      flowId: "flow",
+                      executionId,
+                      batchId,
+                      stepId: step.id,
+                      itemIndex,
+                      totalItems: items.length,
+                      item,
+                      timestamp: Date.now(),
+                      duration: Date.now() - itemStartTime,
+                      result: null,
+                      status: "failed",
+                      error: error instanceof Error ? error : new Error(String(error)),
+                      metadata: this.metadata,
+                      traceContext
+                    };
+                    await executeHook(this.observability.onBatchItemEnd, {
+                      hookName: "onBatchItemEnd",
+                      config: this.observability,
+                      context: batchItemEndContext
+                    });
+                  }
+                  return {
+                    output: null,
+                    error: error.message || String(error),
+                    metrics: [],
+                    artifacts: {}
+                  };
+                }
+              })
+            );
+            const flowResults = results.map((result2, index) => {
+              if (result2.status === "fulfilled") {
+                return result2.value;
+              } else {
+                return {
+                  output: null,
+                  error: result2.reason,
+                  metrics: [],
+                  artifacts: {}
+                };
+              }
+            });
+            artifacts[step.id] = flowResults.map((r) => r.artifacts);
+            metrics.push(...flowResults.flatMap((r) => r.metrics));
+            completedSteps.push(step.id);
+            const successfulCount = flowResults.filter((r) => !r.error).length;
+            const failedCount = flowResults.filter((r) => r.error).length;
+            if (this.observability && sampled && traceContext && executionId) {
+              const batchEndContext = {
+                flowId: "flow",
+                executionId,
+                batchId,
+                stepId: step.id,
+                timestamp: Date.now(),
+                startTime: batchStartTime,
+                duration: Date.now() - batchStartTime,
+                totalItems: items.length,
+                successfulItems: successfulCount,
+                failedItems: failedCount,
+                results: flowResults.map((r) => r.output),
+                metadata: this.metadata,
+                traceContext
+              };
+              await executeHook(this.observability.onBatchEnd, {
+                hookName: "onBatchEnd",
+                config: this.observability,
+                context: batchEndContext
+              });
+            }
+            const stepDuration = Date.now() - stepStartTime;
+            callbacks?.onStepComplete?.(step.id, stepIndex, step.type, stepDuration);
+            return {
+              results: flowResults,
+              metrics,
+              aggregated: aggregateMetrics(metrics),
+              artifacts
+            };
+          }
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          callbacks?.onStepError?.(step.id, stepIndex, step.type, err);
+          if (this.observability && sampled && traceContext && executionId && stepSpanId) {
+            const stepErrorTime = Date.now();
+            const stepErrorContext = {
+              flowId: "flow",
+              executionId,
+              stepId: step.id,
+              stepIndex,
+              timestamp: stepErrorTime,
+              startTime: stepStartTime,
+              duration: stepErrorTime - stepStartTime,
+              error: err,
+              errorCode: err.code,
+              willRetry: false,
+              // TODO: Determine if will retry
+              metadata: this.metadata,
+              traceContext,
+              spanId: stepSpanId
+            };
+            await executeHook(this.observability.onStepError, {
+              hookName: "onStepError",
+              config: this.observability,
+              context: stepErrorContext
+            });
+          }
+          const completedStepsStr = completedSteps.length > 0 ? `
+  Completed steps: ${completedSteps.join(" \u2192 ")}` : "\n  No steps completed before failure";
+          const artifactsStr = Object.keys(artifacts).length > 0 ? `
+  Partial results available in: ${Object.keys(artifacts).join(", ")}` : "";
+          throw new FlowExecutionError(
+            `Flow execution failed at step "${step.id}" (index ${stepIndex}, type: ${step.type})
+  Error: ${err.message}` + completedStepsStr + artifactsStr,
+            step.id,
+            stepIndex,
+            step.type,
+            completedSteps,
+            err,
+            artifacts
+            // Include partial artifacts for debugging
+          );
+        }
+      }
+      const hasOutputNodes = Object.keys(outputs).length > 0;
+      let result;
+      if (hasOutputNodes) {
+        const outputCount = Object.keys(outputs).length;
+        if (outputCount === 1) {
+          const singleOutput = Object.values(outputs)[0];
+          result = {
+            output: singleOutput,
+            outputs,
+            metrics,
+            aggregated: aggregateMetrics(metrics),
+            artifacts
+          };
+        } else {
+          result = {
+            output: outputs,
+            // For backward compatibility, set output to outputs
+            outputs,
+            metrics,
+            aggregated: aggregateMetrics(metrics),
+            artifacts
+          };
+        }
+      } else {
+        result = {
+          output: currentData,
+          metrics,
+          aggregated: aggregateMetrics(metrics),
+          artifacts
+        };
+      }
+      if (this.observability && sampled && traceContext && executionId) {
+        const flowEndTime = Date.now();
+        const aggregated = aggregateMetrics(metrics);
+        const flowStats = {
+          stepsTotal: this.steps.length,
+          stepsCompleted: completedSteps.length,
+          stepsFailed: 0,
+          totalTokens: aggregated.totalInputTokens + aggregated.totalOutputTokens,
+          totalCost: aggregated.totalCostUSD
+        };
+        const flowEndContext = {
+          flowId: "flow",
+          executionId,
+          timestamp: flowEndTime,
+          startTime: flowStartTime,
+          duration: flowEndTime - flowStartTime,
+          output: result.output,
+          stats: flowStats,
+          metadata: this.metadata,
+          traceContext
+        };
+        await executeHook(this.observability.onFlowEnd, {
+          hookName: "onFlowEnd",
+          config: this.observability,
+          context: flowEndContext
+        });
+        if (this.currentExecution) {
+          this.currentExecution.status = "completed";
+        }
+      }
+      return result;
+    } catch (error) {
+      if (this.observability && sampled && traceContext && executionId) {
+        const flowErrorTime = Date.now();
+        const aggregated = aggregateMetrics(metrics);
+        const flowStats = {
+          stepsTotal: this.steps.length,
+          stepsCompleted: completedSteps.length,
+          stepsFailed: 1,
+          totalTokens: aggregated.totalInputTokens + aggregated.totalOutputTokens,
+          totalCost: aggregated.totalCostUSD
+        };
+        const failedStepIndex = completedSteps.length;
+        const flowErrorContext = {
+          flowId: "flow",
+          executionId,
+          timestamp: flowErrorTime,
+          startTime: flowStartTime,
+          duration: flowErrorTime - flowStartTime,
+          error,
+          errorCode: error.code,
+          failedAtStepIndex: failedStepIndex,
+          partialStats: flowStats,
+          metadata: this.metadata,
+          traceContext
+        };
+        await executeHook(this.observability.onFlowError, {
+          hookName: "onFlowError",
+          config: this.observability,
+          context: flowErrorContext
+        });
+        if (this.currentExecution) {
+          this.currentExecution.status = "failed";
+        }
+      }
+      throw error;
+    }
+  }
+};
+function createFlow(options) {
+  return new Flow(options);
+}
+
+// src/index.ts
+import { parse as parse2, split as split3, categorize as categorize3, extract as extract2, chunk, combine, trigger as trigger2 } from "@doclo/nodes";
+
+// src/flow-registry.ts
+var FLOW_REGISTRY = /* @__PURE__ */ new Map();
+function registerFlow(id, builder) {
+  if (FLOW_REGISTRY.has(id)) {
+    console.warn(`[Flow Registry] Overwriting existing flow: ${id}`);
+  }
+  FLOW_REGISTRY.set(id, builder);
+}
+function getFlow(id) {
+  return FLOW_REGISTRY.get(id);
+}
+function hasFlow(id) {
+  return FLOW_REGISTRY.has(id);
+}
+function unregisterFlow(id) {
+  return FLOW_REGISTRY.delete(id);
+}
+function clearRegistry() {
+  FLOW_REGISTRY.clear();
+}
+function listFlows() {
+  return Array.from(FLOW_REGISTRY.keys());
+}
+function getFlowCount() {
+  return FLOW_REGISTRY.size;
+}
+
+// src/serialization.ts
+import { parse, extract, split as split2, categorize as categorize2, trigger, output } from "@doclo/nodes";
+
+// src/composite-nodes.ts
+import { categorize, split } from "@doclo/nodes";
+function parseProviderName(name) {
+  const colonIndex = name.indexOf(":");
+  if (colonIndex === -1) {
+    return { provider: name, model: "unknown" };
+  }
+  return {
+    provider: name.substring(0, colonIndex),
+    model: name.substring(colonIndex + 1)
+  };
+}
+function parseRef(refString) {
+  if (!refString) return null;
+  const atIndex = refString.indexOf("@");
+  if (atIndex === -1) {
+    return { id: refString, version: void 0 };
+  }
+  return {
+    id: refString.substring(0, atIndex),
+    version: refString.substring(atIndex + 1)
+  };
+}
+function flattenMetrics(childMetrics, prefix) {
+  return childMetrics.map((m) => ({
+    ...m,
+    step: `${prefix}.${m.step}`,
+    // @ts-ignore - Add metadata for nested metrics (not in official type but works at runtime)
+    nested: true
+  }));
+}
+function createConditionalCompositeNode(config) {
+  const { stepId, categorizeConfig, branches, providers, flows } = config;
+  return {
+    key: "conditional-composite",
+    run: async (input, ctx) => {
+      const t0 = Date.now();
+      let selectedCategory;
+      let phase = "categorize";
+      try {
+        const categorizeNode = categorize({
+          ...categorizeConfig,
+          provider: providers[categorizeConfig.providerRef],
+          categories: categorizeConfig.categories || Object.keys(branches)
+        });
+        const categorizeT0 = Date.now();
+        const categorizeCostTracker = [];
+        const categorizeCtx = {
+          stepId,
+          // Use composite step's ID so categorize metric is attributed to this step
+          metrics: { push: (m) => categorizeCostTracker.push(m) },
+          artifacts: ctx?.artifacts ?? {},
+          emit: ctx?.emit ?? (() => {
+          }),
+          // No-op if emit not provided
+          observability: ctx?.observability
+        };
+        const categorizeResult = await categorizeNode.run(input, categorizeCtx);
+        selectedCategory = categorizeResult.category;
+        categorizeCostTracker.forEach((m) => ctx?.metrics?.push(m));
+        if (ctx?.emit) {
+          ctx.emit(`${stepId}:category`, selectedCategory);
+        }
+        phase = "branch";
+        if (!branches[selectedCategory]) {
+          throw new Error(
+            `No branch defined for category "${selectedCategory}". Available branches: ${Object.keys(branches).join(", ")}`
+          );
+        }
+        const branchFlowDef = resolveBranchFlow(branches[selectedCategory], flows);
+        const branchFlow = buildFlowFromConfig(
+          branchFlowDef,
+          providers,
+          flows,
+          ctx?.observability?.config ? {
+            observability: ctx.observability.config,
+            metadata: {
+              ...ctx.observability?.metadata,
+              parentNode: stepId,
+              phase: "branch",
+              category: selectedCategory
+            }
+          } : void 0
+        );
+        const branchT0 = Date.now();
+        const branchResultRaw = await branchFlow.run(input);
+        if (!isSingleFlowResult(branchResultRaw)) {
+          throw new Error("Branch flow returned batch result instead of single result");
+        }
+        const branchResult = branchResultRaw;
+        if (ctx?.metrics && branchResult.metrics) {
+          const branchMetrics = flattenMetrics(
+            branchResult.metrics,
+            `${stepId}.branch.${selectedCategory}`
+          );
+          branchMetrics.forEach((m) => ctx.metrics.push(m));
+        }
+        if (ctx?.emit) {
+          ctx.emit(`${stepId}:branchOutput`, branchResult.output);
+          ctx.emit(`${stepId}:branchArtifacts`, branchResult.artifacts);
+        }
+        const categorizeCost = categorizeCostTracker.reduce((sum, m) => sum + (m.costUSD ?? 0), 0);
+        const branchCost = branchResult.metrics ? branchResult.metrics.reduce((sum, m) => sum + (m.costUSD ?? 0), 0) : 0;
+        const aggregateCost = categorizeCost + branchCost;
+        const totalMs = Date.now() - t0;
+        const categorizeMs = categorizeCostTracker.reduce((sum, m) => sum + (m.ms ?? 0), 0);
+        const branchMs = branchResult.metrics ? branchResult.metrics.reduce((sum, m) => sum + (m.ms ?? 0), 0) : 0;
+        const overheadMs = totalMs - categorizeMs - branchMs;
+        if (ctx?.metrics) {
+          const provider = providers[categorizeConfig.providerRef];
+          const { provider: providerName, model } = parseProviderName(provider.name ?? "");
+          const promptRefData = parseRef(categorizeConfig.promptRef);
+          const wrapperMetric = {
+            step: stepId,
+            configStepId: ctx.stepId,
+            startMs: t0,
+            provider: providerName,
+            model,
+            ms: totalMs,
+            costUSD: aggregateCost,
+            // Total cost from categorize + branch
+            attemptNumber: 1,
+            // Composite wrappers don't retry, always 1
+            metadata: {
+              kind: "wrapper",
+              // Distinguish wrapper from leaf metrics
+              type: "conditional",
+              rollup: true,
+              // Duration includes child work
+              overheadMs,
+              // Pure wrapper overhead (flow orchestration)
+              category: selectedCategory,
+              branchStepCount: branchResult.metrics?.length || 0,
+              branchFlowId: typeof branches[selectedCategory] === "object" && "flowRef" in branches[selectedCategory] ? branches[selectedCategory].flowRef : "inline",
+              // Include prompt metadata if available
+              ...promptRefData && {
+                promptId: promptRefData.id,
+                ...promptRefData.version && { promptVersion: promptRefData.version }
+              }
+            }
+          };
+          ctx.metrics.push(wrapperMetric);
+        }
+        return branchResult.output;
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (ctx?.metrics) {
+          ctx.metrics.push({
+            step: stepId,
+            configStepId: ctx.stepId,
+            startMs: t0,
+            ms: Date.now() - t0,
+            costUSD: 0,
+            attemptNumber: 1,
+            // @ts-ignore - Add error field
+            error: err.message,
+            metadata: {
+              kind: "wrapper",
+              type: "conditional",
+              failed: true,
+              category: selectedCategory,
+              failedPhase: phase
+            }
+          });
+        }
+        throw new Error(
+          `Conditional step "${stepId}" failed (${selectedCategory ? `category: ${selectedCategory}, ` : ""}phase: ${phase}): ` + err.message
+        );
+      }
+    }
+  };
+}
+function createForEachCompositeNode(config) {
+  const { stepId, splitConfig, itemFlow, providers, flows } = config;
+  return {
+    key: "forEach-composite",
+    run: async (input, ctx) => {
+      const t0 = Date.now();
+      let items;
+      let phase = "split";
+      try {
+        const splitNode = split({
+          provider: providers[splitConfig.providerRef],
+          ...splitConfig
+        });
+        const splitT0 = Date.now();
+        const splitCostTracker = [];
+        const splitCtx = {
+          stepId,
+          // Use composite step's ID for attribution
+          metrics: { push: (m) => splitCostTracker.push(m) },
+          artifacts: ctx?.artifacts ?? {},
+          emit: ctx?.emit ?? (() => {
+          }),
+          // No-op if emit not provided
+          observability: ctx?.observability
+        };
+        const splitResult = await splitNode.run(input, splitCtx);
+        items = splitResult;
+        splitCostTracker.forEach((m) => ctx?.metrics?.push(m));
+        if (!Array.isArray(items)) {
+          throw new Error(
+            `Split node did not return an array. Got: ${typeof items}`
+          );
+        }
+        if (ctx?.emit) {
+          ctx.emit(`${stepId}:itemCount`, items.length);
+        }
+        phase = "forEach";
+        const itemFlowDef = resolveBranchFlow(itemFlow, flows);
+        const itemFlowResults = [];
+        const results = await Promise.allSettled(
+          items.map(async (item, index) => {
+            const flow = buildFlowFromConfig(
+              itemFlowDef,
+              providers,
+              flows,
+              ctx?.observability?.config ? {
+                observability: ctx.observability.config,
+                metadata: {
+                  ...ctx.observability?.metadata,
+                  parentNode: stepId,
+                  phase: "forEach",
+                  itemIndex: index,
+                  totalItems: items.length
+                }
+              } : void 0
+            );
+            const itemT0 = Date.now();
+            const resultRaw = await flow.run(item.input);
+            if (!isSingleFlowResult(resultRaw)) {
+              throw new Error("Item flow returned batch result instead of single result");
+            }
+            const result = resultRaw;
+            itemFlowResults.push(result);
+            if (ctx?.metrics && result.metrics) {
+              const itemMetrics = flattenMetrics(
+                result.metrics,
+                `${stepId}.item[${index}]`
+              );
+              itemMetrics.forEach((m) => ctx.metrics.push(m));
+            }
+            return result.output;
+          })
+        );
+        const successCount = results.filter((r) => r.status === "fulfilled").length;
+        const failureCount = results.filter((r) => r.status === "rejected").length;
+        const splitCost = splitCostTracker.reduce((sum, m) => sum + (m.costUSD ?? 0), 0);
+        const itemsCost = itemFlowResults.reduce((sum, result) => {
+          const itemCost = result.metrics ? result.metrics.reduce((s, m) => s + (m.costUSD ?? 0), 0) : 0;
+          return sum + itemCost;
+        }, 0);
+        const aggregateCost = splitCost + itemsCost;
+        const totalMs = Date.now() - t0;
+        const splitMs = splitCostTracker.reduce((sum, m) => sum + (m.ms ?? 0), 0);
+        const itemsMs = itemFlowResults.reduce((sum, result) => {
+          const itemMs = result.metrics ? result.metrics.reduce((s, m) => s + (m.ms ?? 0), 0) : 0;
+          return sum + itemMs;
+        }, 0);
+        const overheadMs = totalMs - splitMs - itemsMs;
+        if (ctx?.emit) {
+          ctx.emit(`${stepId}:results`, results);
+          ctx.emit(`${stepId}:successCount`, successCount);
+          ctx.emit(`${stepId}:failureCount`, failureCount);
+        }
+        if (ctx?.metrics) {
+          const provider = providers[splitConfig.providerRef];
+          const { provider: providerName, model } = parseProviderName(provider.name ?? "");
+          const schemaRefData = parseRef(splitConfig.schemaRef);
+          ctx.metrics.push({
+            step: stepId,
+            configStepId: ctx.stepId,
+            startMs: t0,
+            provider: providerName,
+            model,
+            ms: totalMs,
+            costUSD: aggregateCost,
+            // Total cost from split + all items
+            attemptNumber: 1,
+            // Composite wrappers don't retry, always 1
+            metadata: {
+              kind: "wrapper",
+              // Distinguish wrapper from leaf metrics
+              type: "forEach",
+              rollup: true,
+              // Duration includes child work
+              overheadMs,
+              // Pure wrapper overhead (flow orchestration)
+              itemCount: items.length,
+              successCount,
+              failureCount,
+              itemFlowId: typeof itemFlow === "object" && "flowRef" in itemFlow ? itemFlow.flowRef : "inline",
+              // Include schema metadata if available
+              ...schemaRefData && {
+                schemaId: schemaRefData.id,
+                ...schemaRefData.version && { schemaVersion: schemaRefData.version }
+              }
+            }
+          });
+        }
+        return results;
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (ctx?.metrics) {
+          ctx.metrics.push({
+            step: stepId,
+            configStepId: ctx.stepId,
+            startMs: t0,
+            ms: Date.now() - t0,
+            costUSD: 0,
+            attemptNumber: 1,
+            // @ts-ignore - Add error field
+            error: err.message,
+            metadata: {
+              kind: "wrapper",
+              type: "forEach",
+              failed: true,
+              itemCount: items?.length,
+              failedPhase: phase
+            }
+          });
+        }
+        throw new Error(
+          `ForEach step "${stepId}" failed (${items ? `itemCount: ${items.length}, ` : ""}phase: ${phase}): ` + err.message
+        );
+      }
+    }
+  };
+}
+function resolveBranchFlow(flowOrRef, flows) {
+  if (typeof flowOrRef === "object" && flowOrRef !== null && "flowRef" in flowOrRef) {
+    const flowRef = flowOrRef.flowRef;
+    if (!flows[flowRef]) {
+      throw new Error(
+        `Flow reference "${flowRef}" not found in registry. Available flows: ${Object.keys(flows).join(", ")}`
+      );
+    }
+    return flows[flowRef];
+  }
+  return flowOrRef;
+}
+
+// src/serialization.ts
+function extractNodeMetadata(node2) {
+  return null;
+}
+var FlowSerializationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FlowSerializationError";
+  }
+};
+function isFlowReference(value) {
+  return typeof value === "object" && value !== null && "flowRef" in value && typeof value.flowRef === "string";
+}
+function resolveFlowReference(flowOrRef, flows) {
+  if (isFlowReference(flowOrRef)) {
+    if (!flows) {
+      throw new FlowSerializationError(
+        `Flow reference "${flowOrRef.flowRef}" found but no flow registry provided`
+      );
+    }
+    const resolvedFlow = flows[flowOrRef.flowRef];
+    if (!resolvedFlow) {
+      throw new FlowSerializationError(
+        `Flow reference "${flowOrRef.flowRef}" not found in registry. Available flows: ${Object.keys(flows).join(", ")}`
+      );
+    }
+    return resolvedFlow;
+  }
+  return flowOrRef;
+}
+function buildFlowFromConfig(flowDef, providers, flows, options) {
+  if (flowDef.version !== "1.0.0") {
+    throw new FlowSerializationError(`Unsupported flow version: ${flowDef.version}`);
+  }
+  const mergedOptions = {
+    ...options,
+    inputValidation: flowDef.inputValidation ?? options?.inputValidation
+  };
+  let flow = createFlow(mergedOptions);
+  for (const step of flowDef.steps) {
+    if (step.type === "step") {
+      const node2 = createNodeFromConfig(step.nodeType, step.config, providers, flows);
+      flow = flow.step(step.id, node2, step.name);
+    } else if (step.type === "conditional") {
+      const node2 = createConditionalCompositeNode({
+        stepId: step.id,
+        categorizeConfig: step.config,
+        branches: step.branches,
+        providers,
+        flows: flows || {}
+      });
+      flow = flow.step(step.id, node2, step.name);
+    } else if (step.type === "forEach") {
+      const node2 = createForEachCompositeNode({
+        stepId: step.id,
+        splitConfig: step.config,
+        itemFlow: step.itemFlow,
+        providers,
+        flows: flows || {}
+      });
+      flow = flow.step(step.id, node2, step.name);
+    } else {
+      const exhaustiveCheck = step;
+      throw new FlowSerializationError(`Unknown step type: ${exhaustiveCheck.type}`);
+    }
+  }
+  return flow.build();
+}
+function getByPath(obj, path) {
+  return path.reduce((current, key) => {
+    if (current && typeof current === "object" && key in current) {
+      return current[key];
+    }
+    return void 0;
+  }, obj);
+}
+function createInputMapper(mappingConfig) {
+  return (input, context) => {
+    switch (mappingConfig.type) {
+      case "passthrough":
+        return input;
+      case "unwrap":
+        if (input && typeof input === "object" && "input" in input) {
+          return input.input;
+        }
+        return input;
+      case "artifact": {
+        const pathParts = mappingConfig.path.split(".");
+        return getByPath(context.artifacts, pathParts);
+      }
+      case "merge": {
+        const pathParts = mappingConfig.artifactPath.split(".");
+        const artifactValue = getByPath(context.artifacts, pathParts);
+        if (typeof input === "object" && input !== null && typeof artifactValue === "object" && artifactValue !== null) {
+          return { ...input, ...artifactValue };
+        }
+        return input;
+      }
+      case "construct": {
+        const result = {};
+        for (const [fieldName, fieldMapping] of Object.entries(mappingConfig.fields)) {
+          switch (fieldMapping.source) {
+            case "input":
+              if (fieldMapping.path) {
+                const pathParts = fieldMapping.path.split(".");
+                result[fieldName] = getByPath(input, pathParts);
+              } else {
+                result[fieldName] = input;
+              }
+              break;
+            case "artifact": {
+              const pathParts = fieldMapping.path.split(".");
+              result[fieldName] = getByPath(context.artifacts, pathParts);
+              break;
+            }
+            case "literal":
+              result[fieldName] = fieldMapping.value;
+              break;
+          }
+        }
+        return result;
+      }
+      default:
+        return input;
+    }
+  };
+}
+function hasProviderRef(config) {
+  return "providerRef" in config && typeof config.providerRef === "string";
+}
+function createNodeFromConfig(nodeType, config, providers, flows) {
+  if (nodeType === "trigger") {
+    const cfg = config;
+    if (!flows || !flows[cfg.flowRef]) {
+      throw new FlowSerializationError(
+        `Flow "${cfg.flowRef}" not found in flow registry. Available flows: ${flows ? Object.keys(flows).join(", ") : "none"}`
+      );
+    }
+    const overrideProviders = {};
+    if (cfg.providerOverrides) {
+      for (const [childRef, parentRef] of Object.entries(cfg.providerOverrides)) {
+        if (!providers[parentRef]) {
+          throw new FlowSerializationError(
+            `Provider "${parentRef}" not found in provider registry. Available providers: ${Object.keys(providers).join(", ")}`
+          );
+        }
+        overrideProviders[childRef] = providers[parentRef];
+      }
+    }
+    const flowBuilder = flows[cfg.flowRef];
+    return trigger({
+      flow: flowBuilder,
+      flowId: cfg.flowRef,
+      providers: Object.keys(overrideProviders).length > 0 ? overrideProviders : void 0,
+      mapInput: cfg.inputMapping ? createInputMapper(cfg.inputMapping) : void 0,
+      mergeMetrics: cfg.mergeMetrics,
+      timeout: cfg.timeout
+    });
+  }
+  if (nodeType === "output") {
+    const cfg = config;
+    return output({
+      name: cfg.name,
+      source: cfg.source,
+      transform: cfg.transform,
+      fields: cfg.fields
+    });
+  }
+  if (!hasProviderRef(config)) {
+    throw new FlowSerializationError(
+      `Config for node type "${nodeType}" is missing providerRef`
+    );
+  }
+  const provider = providers[config.providerRef];
+  if (!provider) {
+    throw new FlowSerializationError(
+      `Provider "${config.providerRef}" not found in registry. Available providers: ${Object.keys(providers).join(", ")}`
+    );
+  }
+  switch (nodeType) {
+    case "parse": {
+      const cfg = config;
+      return parse({
+        provider,
+        consensus: cfg.consensus
+      });
+    }
+    case "extract": {
+      const cfg = config;
+      return extract({
+        provider,
+        schema: cfg.schema,
+        consensus: cfg.consensus,
+        reasoning: cfg.reasoning
+      });
+    }
+    case "split": {
+      const cfg = config;
+      return split2({
+        provider,
+        schemas: cfg.schemas,
+        includeOther: cfg.includeOther,
+        consensus: cfg.consensus
+      });
+    }
+    case "categorize": {
+      const cfg = config;
+      return categorize2({
+        provider,
+        categories: cfg.categories,
+        consensus: cfg.consensus
+      });
+    }
+    default:
+      throw new FlowSerializationError(`Unknown node type: ${nodeType}`);
+  }
+}
+function defineFlowConfig(config) {
+  return {
+    version: "1.0.0",
+    ...config
+  };
+}
+
+// src/validation.ts
+import { isDebugValidation } from "@doclo/core/runtime/env";
+function validateJSONSchemaStructure(schema, depth = 0) {
+  const MAX_DEPTH = 50;
+  if (depth > MAX_DEPTH) {
+    return `Schema nesting depth exceeds maximum (${MAX_DEPTH})`;
+  }
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return "Schema must be an object";
+  }
+  const schemaObj = schema;
+  if (!schemaObj.type || typeof schemaObj.type !== "string") {
+    return 'Schema missing "type" property';
+  }
+  const validTypes = ["object", "array", "string", "number", "integer", "boolean", "null"];
+  if (!validTypes.includes(schemaObj.type)) {
+    return `Invalid schema type: "${schemaObj.type}". Must be one of: ${validTypes.join(", ")}`;
+  }
+  if (schemaObj.type === "object") {
+    if (schemaObj.properties && typeof schemaObj.properties !== "object") {
+      return "Schema properties must be an object";
+    }
+    if (schemaObj.required && !Array.isArray(schemaObj.required)) {
+      return "Schema required must be an array";
+    }
+    if (schemaObj.properties && typeof schemaObj.properties === "object" && !Array.isArray(schemaObj.properties)) {
+      const properties = schemaObj.properties;
+      for (const [propName, propSchema] of Object.entries(properties)) {
+        const propError = validateJSONSchemaStructure(propSchema, depth + 1);
+        if (propError) {
+          return `Invalid schema for property "${propName}": ${propError}`;
+        }
+      }
+    }
+  }
+  if (schemaObj.type === "array") {
+    if (!schemaObj.items) {
+      return 'Array schema missing "items" property';
+    }
+    const itemsError = validateJSONSchemaStructure(schemaObj.items, depth + 1);
+    if (itemsError) {
+      return `Invalid array items schema: ${itemsError}`;
+    }
+  }
+  return null;
+}
+function calculateFlowNestingDepth(flow, currentDepth = 1) {
+  let maxDepth = currentDepth + 1;
+  for (const step of flow.steps) {
+    let stepDepth = currentDepth + 2;
+    if (step.type === "conditional") {
+      const conditionalStep = step;
+      if (conditionalStep.branches) {
+        for (const branchFlowOrRef of Object.values(conditionalStep.branches)) {
+          if ("flowRef" in branchFlowOrRef) {
+            maxDepth = Math.max(maxDepth, stepDepth + 3);
+          } else {
+            const branchDepth = calculateFlowNestingDepth(branchFlowOrRef, stepDepth + 2);
+            maxDepth = Math.max(maxDepth, branchDepth);
+          }
+        }
+      }
+    } else if (step.type === "forEach") {
+      const forEachStep = step;
+      if (forEachStep.itemFlow) {
+        const itemFlowOrRef = forEachStep.itemFlow;
+        if ("flowRef" in itemFlowOrRef) {
+          maxDepth = Math.max(maxDepth, stepDepth + 2);
+        } else {
+          const itemDepth = calculateFlowNestingDepth(itemFlowOrRef, stepDepth + 1);
+          maxDepth = Math.max(maxDepth, itemDepth);
+        }
+      }
+    } else {
+      const config = step.config;
+      let configDepth = stepDepth + 1;
+      if ("schema" in config && config.schema) {
+        configDepth += 4;
+      }
+      if ("schemas" in config && config.schemas) {
+        configDepth += 4;
+      }
+      maxDepth = Math.max(maxDepth, configDepth);
+    }
+  }
+  return maxDepth;
+}
+function validateFlow(flowDef, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const opts = {
+    checkProviders: true,
+    checkSchemas: true,
+    checkVersion: true,
+    ...options
+  };
+  if (opts.checkVersion) {
+    if (!flowDef.version) {
+      errors.push({
+        type: "version_mismatch",
+        message: "Flow definition missing version field"
+      });
+    } else if (flowDef.version !== "1.0.0") {
+      errors.push({
+        type: "version_mismatch",
+        message: `Unsupported flow version: ${flowDef.version}. Expected: 1.0.0`,
+        details: { version: flowDef.version }
+      });
+    }
+  }
+  if (!flowDef.steps || !Array.isArray(flowDef.steps)) {
+    errors.push({
+      type: "invalid_config",
+      message: "Flow definition missing or invalid steps array"
+    });
+    return { valid: false, errors, warnings };
+  }
+  if (flowDef.steps.length === 0) {
+    warnings.push({
+      type: "best_practice",
+      message: "Flow has no steps defined"
+    });
+  }
+  const nestingDepth = calculateFlowNestingDepth(flowDef);
+  if (nestingDepth > 14) {
+    errors.push({
+      type: "invalid_config",
+      message: `Flow nesting depth (${nestingDepth} levels) exceeds recommended maximum (14 levels). This will cause issues with Convex and other databases with 16-level JSON nesting limits. Consider using flow references (flowRef) to reduce nesting depth.`,
+      details: { nestingDepth, limit: 14 }
+    });
+  } else if (nestingDepth > 12) {
+    warnings.push({
+      type: "performance",
+      message: `Flow nesting depth (${nestingDepth} levels) is approaching the database limit (16 levels). Consider using flow references to reduce complexity.`,
+      details: { nestingDepth, warningThreshold: 12 }
+    });
+  }
+  for (const step of flowDef.steps) {
+    const stepId = step.id || "unknown";
+    if (!step.type) {
+      errors.push({
+        type: "invalid_config",
+        stepId,
+        message: "Step missing type field"
+      });
+      continue;
+    }
+    if (step.type === "conditional") {
+      const conditionalStep = step;
+      if (!conditionalStep.branches || typeof conditionalStep.branches !== "object") {
+        errors.push({
+          type: "invalid_config",
+          stepId,
+          message: "Conditional step missing or invalid branches field"
+        });
+      } else {
+        for (const [category, branchFlowOrRef] of Object.entries(conditionalStep.branches)) {
+          if ("flowRef" in branchFlowOrRef) {
+            const flowRef = branchFlowOrRef.flowRef;
+            if (typeof flowRef !== "string" || flowRef.trim() === "") {
+              errors.push({
+                type: "invalid_config",
+                stepId: `${stepId}.${category}`,
+                message: `Branch "${category}": flowRef must be a non-empty string`
+              });
+            }
+          } else {
+            const branchResult = validateFlow(branchFlowOrRef, options);
+            for (const error of branchResult.errors) {
+              errors.push({
+                ...error,
+                stepId: `${stepId}.${category}`,
+                message: `Branch "${category}": ${error.message}`
+              });
+            }
+            for (const warning of branchResult.warnings) {
+              warnings.push({
+                ...warning,
+                stepId: `${stepId}.${category}`,
+                message: `Branch "${category}": ${warning.message}`
+              });
+            }
+          }
+        }
+      }
+    } else if (step.type === "forEach") {
+      const forEachStep = step;
+      if (!forEachStep.itemFlow) {
+        errors.push({
+          type: "invalid_config",
+          stepId,
+          message: "ForEach step missing itemFlow field"
+        });
+      } else {
+        const itemFlowOrRef = forEachStep.itemFlow;
+        if ("flowRef" in itemFlowOrRef) {
+          const flowRef = itemFlowOrRef.flowRef;
+          if (typeof flowRef !== "string" || flowRef.trim() === "") {
+            errors.push({
+              type: "invalid_config",
+              stepId: `${stepId}.itemFlow`,
+              message: `itemFlow: flowRef must be a non-empty string`
+            });
+          }
+        } else {
+          const itemResult = validateFlow(itemFlowOrRef, options);
+          for (const error of itemResult.errors) {
+            errors.push({
+              ...error,
+              stepId: `${stepId}.itemFlow`,
+              message: `Item flow: ${error.message}`
+            });
+          }
+          for (const warning of itemResult.warnings) {
+            warnings.push({
+              ...warning,
+              stepId: `${stepId}.itemFlow`,
+              message: `Item flow: ${warning.message}`
+            });
+          }
+        }
+      }
+    }
+    const validNodeTypes = ["parse", "extract", "split", "categorize", "trigger", "output"];
+    if (!step.nodeType || !validNodeTypes.includes(step.nodeType)) {
+      errors.push({
+        type: "invalid_config",
+        stepId,
+        message: `Invalid node type: ${step.nodeType}. Must be one of: ${validNodeTypes.join(", ")}`,
+        details: { nodeType: step.nodeType }
+      });
+      continue;
+    }
+    if (!step.config) {
+      errors.push({
+        type: "invalid_config",
+        stepId,
+        message: "Step missing config field"
+      });
+      continue;
+    }
+    const config = step.config;
+    const hasProviderRef2 = (cfg) => {
+      return "providerRef" in cfg && typeof cfg.providerRef === "string";
+    };
+    if (step.nodeType !== "trigger" && step.nodeType !== "output") {
+      if (!hasProviderRef2(config)) {
+        errors.push({
+          type: "missing_provider",
+          stepId,
+          message: "Step config missing providerRef"
+        });
+      } else if (opts.checkProviders && opts.providers) {
+        if (!opts.providers[config.providerRef]) {
+          errors.push({
+            type: "missing_provider",
+            stepId,
+            message: `Provider "${config.providerRef}" not found in registry`,
+            details: {
+              providerRef: config.providerRef,
+              availableProviders: Object.keys(opts.providers)
+            }
+          });
+        }
+      }
+    }
+    if (opts.checkSchemas) {
+      switch (step.nodeType) {
+        case "extract": {
+          const cfg = config;
+          if (!cfg.schema) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Extract node missing schema"
+            });
+          } else {
+            const schemaError = validateJSONSchemaStructure(cfg.schema);
+            if (schemaError) {
+              errors.push({
+                type: "invalid_schema",
+                stepId,
+                message: `Invalid JSON schema: ${schemaError}`,
+                details: { schema: cfg.schema }
+              });
+            }
+          }
+          if (cfg.reasoning) {
+            if (cfg.reasoning.effort && !["low", "medium", "high"].includes(cfg.reasoning.effort)) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: `Invalid reasoning effort: ${cfg.reasoning.effort}. Must be: low, medium, or high`
+              });
+            }
+          }
+          break;
+        }
+        case "split": {
+          const cfg = config;
+          if (!cfg.schemas) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Split node missing schemas"
+            });
+          } else if (typeof cfg.schemas !== "object") {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Split node schemas must be an object"
+            });
+          } else {
+            for (const [schemaName, schema] of Object.entries(cfg.schemas)) {
+              const schemaError = validateJSONSchemaStructure(schema);
+              if (schemaError) {
+                errors.push({
+                  type: "invalid_schema",
+                  stepId,
+                  message: `Invalid JSON schema for "${schemaName}": ${schemaError}`,
+                  details: { schemaName, schema }
+                });
+              }
+            }
+            if (Object.keys(cfg.schemas).length === 0) {
+              warnings.push({
+                type: "best_practice",
+                stepId,
+                message: "Split node has no schemas defined"
+              });
+            }
+          }
+          break;
+        }
+        case "categorize": {
+          const cfg = config;
+          if (!cfg.categories) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Categorize node missing categories"
+            });
+          } else if (!Array.isArray(cfg.categories)) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Categorize node categories must be an array"
+            });
+          } else if (cfg.categories.length === 0) {
+            warnings.push({
+              type: "best_practice",
+              stepId,
+              message: "Categorize node has no categories defined"
+            });
+          }
+          break;
+        }
+        case "trigger": {
+          const cfg = config;
+          if (!cfg.flowRef) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Trigger node missing flowRef"
+            });
+          }
+          if (cfg.providerOverrides) {
+            if (typeof cfg.providerOverrides !== "object") {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: "Trigger node providerOverrides must be an object"
+              });
+            } else if (opts.checkProviders && opts.providers) {
+              for (const [childRef, parentRef] of Object.entries(cfg.providerOverrides)) {
+                if (!opts.providers[parentRef]) {
+                  errors.push({
+                    type: "missing_provider",
+                    stepId,
+                    message: `Provider override "${parentRef}" not found in registry`,
+                    details: {
+                      childRef,
+                      parentRef,
+                      availableProviders: Object.keys(opts.providers)
+                    }
+                  });
+                }
+              }
+            }
+          }
+          if (cfg.inputMapping) {
+            if (!cfg.inputMapping.type) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: "Trigger node inputMapping missing type field"
+              });
+            } else {
+              const validMappingTypes = ["passthrough", "unwrap", "artifact", "merge", "construct"];
+              if (!validMappingTypes.includes(cfg.inputMapping.type)) {
+                errors.push({
+                  type: "invalid_config",
+                  stepId,
+                  message: `Invalid inputMapping type: ${cfg.inputMapping.type}. Must be one of: ${validMappingTypes.join(", ")}`
+                });
+              }
+              if (cfg.inputMapping.type === "artifact" && !("path" in cfg.inputMapping)) {
+                errors.push({
+                  type: "invalid_config",
+                  stepId,
+                  message: 'Trigger node inputMapping type "artifact" requires path field'
+                });
+              }
+              if (cfg.inputMapping.type === "merge" && !("artifactPath" in cfg.inputMapping)) {
+                errors.push({
+                  type: "invalid_config",
+                  stepId,
+                  message: 'Trigger node inputMapping type "merge" requires artifactPath field'
+                });
+              }
+              if (cfg.inputMapping.type === "construct" && !("fields" in cfg.inputMapping)) {
+                errors.push({
+                  type: "invalid_config",
+                  stepId,
+                  message: 'Trigger node inputMapping type "construct" requires fields object'
+                });
+              }
+            }
+          }
+          if (cfg.timeout !== void 0) {
+            if (typeof cfg.timeout !== "number" || cfg.timeout <= 0) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: "Trigger node timeout must be a positive number"
+              });
+            }
+          }
+          if (cfg.mergeMetrics !== void 0 && typeof cfg.mergeMetrics !== "boolean") {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Trigger node mergeMetrics must be a boolean"
+            });
+          }
+          break;
+        }
+        case "output": {
+          const cfg = config;
+          if (cfg.transform) {
+            const validTransforms = ["first", "last", "merge", "pick"];
+            if (!validTransforms.includes(cfg.transform)) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: `Invalid output transform: ${cfg.transform}. Must be one of: ${validTransforms.join(", ")}`
+              });
+            }
+            if (cfg.transform === "pick" && (!cfg.fields || cfg.fields.length === 0)) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: 'Output transform "pick" requires fields array'
+              });
+            }
+          }
+          if (cfg.fields && !Array.isArray(cfg.fields)) {
+            errors.push({
+              type: "invalid_config",
+              stepId,
+              message: "Output fields must be an array"
+            });
+          }
+          if (cfg.source) {
+            if (typeof cfg.source !== "string" && !Array.isArray(cfg.source)) {
+              errors.push({
+                type: "invalid_config",
+                stepId,
+                message: "Output source must be a string or array of strings"
+              });
+            } else if (Array.isArray(cfg.source) && cfg.source.length === 0) {
+              warnings.push({
+                type: "best_practice",
+                stepId,
+                message: "Output source array is empty"
+              });
+            }
+          }
+          break;
+        }
+      }
+      if ("consensus" in config && config.consensus) {
+        const consensus = config.consensus;
+        if (!consensus.runs || consensus.runs < 1) {
+          errors.push({
+            type: "invalid_config",
+            stepId,
+            message: "Consensus runs must be >= 1"
+          });
+        }
+        if (consensus.strategy && !["majority", "unanimous"].includes(consensus.strategy)) {
+          errors.push({
+            type: "invalid_config",
+            stepId,
+            message: `Invalid consensus strategy: ${consensus.strategy}. Must be: majority or unanimous`
+          });
+        }
+        if (consensus.onTie && !["random", "fail", "retry"].includes(consensus.onTie)) {
+          errors.push({
+            type: "invalid_config",
+            stepId,
+            message: `Invalid consensus onTie: ${consensus.onTie}. Must be: random, fail, or retry`
+          });
+        }
+        if (consensus.runs > 1) {
+          warnings.push({
+            type: "performance",
+            stepId,
+            message: `Consensus with ${consensus.runs} runs will execute the step ${consensus.runs} times`
+          });
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateFlowOrThrow(flowDef, options = {}) {
+  const result = validateFlow(flowDef, options);
+  if (!result.valid) {
+    const errorMessages = result.errors.map(
+      (e) => e.stepId ? `[${e.stepId}] ${e.message}` : e.message
+    ).join("\n");
+    throw new Error(`Flow validation failed:
+${errorMessages}`);
+  }
+  if (result.warnings.length > 0 && isDebugValidation()) {
+    console.warn("[Flow Validation] Warnings:");
+    for (const warning of result.warnings) {
+      const prefix = warning.stepId ? `[${warning.stepId}]` : "";
+      console.warn(`  ${prefix} ${warning.message}`);
+    }
+  }
+}
+
+// src/index.ts
+import { bufferToDataUri, bufferToBase64 } from "@doclo/core";
+
+// src/multi-provider-flow.ts
+import { runPipeline as runPipeline2 } from "@doclo/core";
+import { parseNode, extractNode } from "@doclo/nodes";
+import { buildLLMProvider } from "@doclo/providers-llm";
+function buildMultiProviderFlow(opts) {
+  const parse3 = parseNode({ ocr: opts.ocr });
+  const coreLLMProvider = buildLLMProvider({
+    providers: opts.llmConfigs,
+    maxRetries: opts.maxRetries ?? 2,
+    retryDelay: opts.retryDelay ?? 1e3,
+    useExponentialBackoff: true,
+    circuitBreakerThreshold: opts.circuitBreakerThreshold ?? 3
+  });
+  const mkPrompt = (ir) => `Extract JSON matching the schema fields: vessel, port, quantity_mt.
+Document (first page preview):
+${ir.pages[0]?.lines.slice(0, 50).map((l) => l.text).join("\n")}`;
+  const extract3 = extractNode({
+    llm: coreLLMProvider,
+    schema: simpleSchema,
+    makePrompt: mkPrompt
+  });
+  return {
+    async run(input) {
+      const parsed = await runPipeline2([parse3], input);
+      const ir = parsed.output;
+      const result = await runPipeline2([extract3], ir);
+      return {
+        ir,
+        output: result.output,
+        metrics: [...parsed.metrics, ...result.metrics],
+        artifacts: {
+          parse: parsed.artifacts.parse,
+          extract: result.artifacts.extract
+        }
+      };
+    }
+  };
+}
+
+// src/vlm-direct-flow.ts
+import { runPipeline as runPipeline3 } from "@doclo/core";
+import { node } from "@doclo/core";
+import { buildLLMProvider as buildLLMProvider2 } from "@doclo/providers-llm";
+function buildVLMDirectFlow(opts) {
+  const coreLLMProvider = buildLLMProvider2({
+    providers: opts.llmConfigs,
+    maxRetries: opts.maxRetries ?? 2,
+    retryDelay: opts.retryDelay ?? 1e3,
+    useExponentialBackoff: true,
+    circuitBreakerThreshold: opts.circuitBreakerThreshold ?? 3
+  });
+  const vlmExtract = node(
+    "vlm_extract",
+    async (input, ctx) => {
+      const t0 = Date.now();
+      const prompt = {
+        text: `You are a document data extraction expert. Extract the following fields from this maritime document:
+- vessel: The vessel/ship name
+- port: The port name or location
+- quantity_mt: The quantity in metric tons (MT)
+
+Return ONLY a JSON object with these fields. Use null if a field is not found.`
+      };
+      let isPDF = false;
+      if (input.url) {
+        isPDF = input.url.endsWith(".pdf") || input.url.toLowerCase().includes(".pdf");
+      } else if (input.base64) {
+        isPDF = input.base64.startsWith("data:application/pdf");
+      }
+      if (isPDF) {
+        prompt.pdfs = [];
+        if (input.url) {
+          if (input.url.startsWith("data:")) {
+            const base64Data = input.url.replace(/^data:application\/pdf;base64,/, "");
+            prompt.pdfs.push({ base64: base64Data });
+          } else {
+            prompt.pdfs.push({ url: input.url });
+          }
+        } else if (input.base64) {
+          const base64Data = input.base64.startsWith("data:") ? input.base64.replace(/^data:application\/pdf;base64,/, "") : input.base64;
+          prompt.pdfs.push({ base64: base64Data });
+        }
+      } else {
+        prompt.images = [];
+        if (input.url) {
+          if (input.url.startsWith("data:")) {
+            const base64Data = input.url.replace(/^data:image\/[^;]+;base64,/, "");
+            const mimeType = input.url.match(/^data:(image\/[^;]+);/)?.[1] || "image/jpeg";
+            prompt.images.push({ base64: base64Data, mimeType });
+          } else {
+            prompt.images.push({ url: input.url, mimeType: "image/jpeg" });
+          }
+        } else if (input.base64) {
+          const base64Data = input.base64.startsWith("data:") ? input.base64.replace(/^data:image\/[^;]+;base64,/, "") : input.base64;
+          const mimeType = input.base64.startsWith("data:") ? input.base64.match(/^data:(image\/[^;]+);/)?.[1] || "image/jpeg" : "image/jpeg";
+          prompt.images.push({ base64: base64Data, mimeType });
+        }
+      }
+      const { json, costUSD, inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens } = await coreLLMProvider.completeJson({
+        prompt,
+        schema: simpleSchema
+      });
+      ctx.metrics.push({
+        step: "vlm_extract",
+        startMs: t0,
+        provider: coreLLMProvider.name,
+        model: "unknown",
+        ms: Date.now() - t0,
+        costUSD,
+        inputTokens,
+        outputTokens,
+        cacheCreationInputTokens,
+        cacheReadInputTokens,
+        attemptNumber: 1,
+        metadata: { kind: "leaf" }
+      });
+      return json;
+    }
+  );
+  return {
+    async run(input) {
+      const result = await runPipeline3([vlmExtract], input);
+      return {
+        output: result.output,
+        metrics: result.metrics,
+        artifacts: {
+          vlm_extract: result.artifacts.vlm_extract
+        }
+      };
+    }
+  };
+}
+
+// src/index.ts
+function buildTwoProviderFlow(opts) {
+  const parse3 = parseNode2({ ocr: opts.ocr });
+  const mkPrompt = (ir) => `Extract JSON matching the schema fields: vessel, port, quantity_mt.
+Document (first page preview):
+${ir.pages[0]?.lines.slice(0, 50).map((l) => l.text).join("\n")}`;
+  const extractA = extractNode2({ llm: opts.llmA, schema: simpleSchema, makePrompt: mkPrompt });
+  const extractB = extractNode2({ llm: opts.llmB, schema: simpleSchema, makePrompt: mkPrompt });
+  return {
+    async run(input) {
+      const parsed = await runPipeline4([parse3], input);
+      const ir = parsed.output;
+      const [resA, resB] = await Promise.all([
+        runPipeline4([extractA], ir),
+        runPipeline4([extractB], ir)
+      ]);
+      return {
+        ir,
+        outputA: resA.output,
+        outputB: resB.output,
+        metrics: [...parsed.metrics, ...resA.metrics, ...resB.metrics],
+        artifacts: {
+          parse: parsed.artifacts.parse,
+          extractA: resA.artifacts.extract,
+          extractB: resB.artifacts.extract
+        }
+      };
+    }
+  };
+}
+export {
+  FLOW_REGISTRY,
+  FlowSerializationError,
+  bufferToBase64,
+  bufferToDataUri,
+  buildFlowFromConfig,
+  buildMultiProviderFlow,
+  buildTwoProviderFlow,
+  buildVLMDirectFlow,
+  categorize3 as categorize,
+  chunk,
+  clearRegistry,
+  combine,
+  createConditionalCompositeNode,
+  createFlow,
+  createForEachCompositeNode,
+  defineFlowConfig,
+  extract2 as extract,
+  extractNodeMetadata,
+  getFlow,
+  getFlowCount,
+  hasFlow,
+  isFlowReference,
+  listFlows,
+  parse2 as parse,
+  registerFlow,
+  resolveFlowReference,
+  simpleSchema,
+  split3 as split,
+  trigger2 as trigger,
+  unregisterFlow,
+  validateFlow,
+  validateFlowOrThrow
+};
+//# sourceMappingURL=index.js.map