@gravito/flux 3.0.0 → 3.0.2

package/dist/chunk-WAPZDXSX.cjs

@@ -0,0 +1,3486 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6; var _class7; var _class8;
+
+var _chunkYXBEYVGYcjs = require('./chunk-YXBEYVGY.cjs');
+
+// src/errors.ts
+var FluxErrorCode = /* @__PURE__ */ ((FluxErrorCode2) => {
+  FluxErrorCode2["WORKFLOW_NOT_FOUND"] = "WORKFLOW_NOT_FOUND";
+  FluxErrorCode2["WORKFLOW_INVALID_INPUT"] = "WORKFLOW_INVALID_INPUT";
+  FluxErrorCode2["WORKFLOW_DEFINITION_CHANGED"] = "WORKFLOW_DEFINITION_CHANGED";
+  FluxErrorCode2["WORKFLOW_NAME_MISMATCH"] = "WORKFLOW_NAME_MISMATCH";
+  FluxErrorCode2["INVALID_STATE_TRANSITION"] = "INVALID_STATE_TRANSITION";
+  FluxErrorCode2["WORKFLOW_NOT_SUSPENDED"] = "WORKFLOW_NOT_SUSPENDED";
+  FluxErrorCode2["INVALID_STEP_INDEX"] = "INVALID_STEP_INDEX";
+  FluxErrorCode2["STEP_TIMEOUT"] = "STEP_TIMEOUT";
+  FluxErrorCode2["STEP_NOT_FOUND"] = "STEP_NOT_FOUND";
+  FluxErrorCode2["CONCURRENT_MODIFICATION"] = "CONCURRENT_MODIFICATION";
+  FluxErrorCode2["EMPTY_WORKFLOW"] = "EMPTY_WORKFLOW";
+  FluxErrorCode2["NO_RECOVERY_ACTION"] = "NO_RECOVERY_ACTION";
+  FluxErrorCode2["INVALID_JSON_POINTER"] = "INVALID_JSON_POINTER";
+  FluxErrorCode2["INVALID_PATH_TRAVERSAL"] = "INVALID_PATH_TRAVERSAL";
+  FluxErrorCode2["CANNOT_REPLACE_ROOT"] = "CANNOT_REPLACE_ROOT";
+  FluxErrorCode2["CANNOT_REMOVE_ROOT"] = "CANNOT_REMOVE_ROOT";
+  return FluxErrorCode2;
+})(FluxErrorCode || {});
+var FluxError = class extends Error {
+  /**
+   * Creates a new FluxError.
+   *
+   * @param message - Human-readable error description.
+   * @param code - Machine-readable error code.
+   * @param context - Additional metadata related to the error.
+   */
+  constructor(message, code, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "FluxError";
+  }
+};
+function workflowNotFound(id) {
+  return new FluxError(`Workflow not found: ${id}`, "WORKFLOW_NOT_FOUND" /* WORKFLOW_NOT_FOUND */, {
+    workflowId: id
+  });
+}
+function invalidStateTransition(from, to) {
+  return new FluxError(
+    `Invalid state transition: ${from} \u2192 ${to}`,
+    "INVALID_STATE_TRANSITION" /* INVALID_STATE_TRANSITION */,
+    { from, to }
+  );
+}
+function invalidInput(workflowName) {
+  return new FluxError(
+    `Invalid input for workflow "${workflowName}"`,
+    "WORKFLOW_INVALID_INPUT" /* WORKFLOW_INVALID_INPUT */,
+    { workflowName }
+  );
+}
+function workflowNameMismatch(expected, received) {
+  return new FluxError(
+    `Workflow name mismatch: ${received} !== ${expected}`,
+    "WORKFLOW_NAME_MISMATCH" /* WORKFLOW_NAME_MISMATCH */,
+    { expected, received }
+  );
+}
+function workflowDefinitionChanged() {
+  return new FluxError(
+    "Workflow definition changed; operation is not safe",
+    "WORKFLOW_DEFINITION_CHANGED" /* WORKFLOW_DEFINITION_CHANGED */
+  );
+}
+function workflowNotSuspended(status) {
+  return new FluxError(
+    `Workflow is not suspended (status: ${status})`,
+    "WORKFLOW_NOT_SUSPENDED" /* WORKFLOW_NOT_SUSPENDED */,
+    { status }
+  );
+}
+function stepNotFound(step) {
+  return new FluxError(`Step not found: ${step}`, "STEP_NOT_FOUND" /* STEP_NOT_FOUND */, { step });
+}
+function invalidStepIndex(index) {
+  return new FluxError(`Invalid step index: ${index}`, "INVALID_STEP_INDEX" /* INVALID_STEP_INDEX */, { index });
+}
+function emptyWorkflow(workflowName) {
+  return new FluxError(`Workflow "${workflowName}" has no steps`, "EMPTY_WORKFLOW" /* EMPTY_WORKFLOW */, {
+    workflowName
+  });
+}
+function noRecoveryAction(stepName) {
+  return new FluxError(
+    `No recovery action registered for step: ${stepName}`,
+    "NO_RECOVERY_ACTION" /* NO_RECOVERY_ACTION */,
+    { stepName }
+  );
+}
+function invalidJsonPointer(path) {
+  return new FluxError(`Invalid JSON Pointer: ${path}`, "INVALID_JSON_POINTER" /* INVALID_JSON_POINTER */, {
+    path
+  });
+}
+function invalidPathTraversal(segment, current) {
+  return new FluxError(
+    `Cannot access property '${segment}' on ${current}`,
+    "INVALID_PATH_TRAVERSAL" /* INVALID_PATH_TRAVERSAL */,
+    { segment, currentType: typeof current }
+  );
+}
+function cannotReplaceRoot() {
+  return new FluxError("Cannot replace root object", "CANNOT_REPLACE_ROOT" /* CANNOT_REPLACE_ROOT */);
+}
+function cannotRemoveRoot() {
+  return new FluxError("Cannot remove root object", "CANNOT_REMOVE_ROOT" /* CANNOT_REMOVE_ROOT */);
+}
+
+// src/builder/WorkflowBuilder.ts
+var WorkflowBuilder = (_class = class {
+  
+  
+  __init() {this._steps = []}
+  
+  __init2() {this._parallelGroupCounter = 0}
+  /**
+   * Initializes a new workflow builder with a unique name.
+   * @param name - The identifier for this workflow definition.
+   */
+  constructor(name) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);
+    this._name = name;
+  }
+  /**
+   * Defines the expected input type for the workflow.
+   * This is a type-only operation that enables compile-time safety for subsequent steps.
+   * @returns A builder instance with the specified input type.
+   */
+  input() {
+    return this;
+  }
+  /**
+   * Defines the structure of the shared data object used across steps.
+   * @returns A builder instance with the specified data type.
+   */
+  data() {
+    return this;
+  }
+  /**
+   * Sets the semantic version of this workflow definition.
+   * @param v - A semantic version string (e.g., "1.0.0", "2.1.0").
+   * @returns The builder instance for chaining.
+   */
+  version(v) {
+    this._version = v;
+    return this;
+  }
+  /**
+   * Attaches a runtime validator for the workflow input.
+   * @param validator - A type guard function to verify input integrity.
+   * @returns The builder instance for chaining.
+   */
+  validate(validator) {
+    this._validateInput = validator;
+    return this;
+  }
+  /**
+   * Adds a standard processing step to the workflow.
+   * Standard steps are subject to compensation if the workflow fails later.
+   *
+   * @param name - Unique name for the step.
+   * @param handler - The business logic to execute.
+   * @param options - Optional execution configuration.
+   * @returns The builder instance for chaining.
+   */
+  step(name, handler, options) {
+    this._steps.push({
+      name,
+      handler,
+      retries: _optionalChain([options, 'optionalAccess', _2 => _2.retries]),
+      timeout: _optionalChain([options, 'optionalAccess', _3 => _3.timeout]),
+      when: _optionalChain([options, 'optionalAccess', _4 => _4.when]),
+      compensate: _optionalChain([options, 'optionalAccess', _5 => _5.compensate]),
+      commit: false
+    });
+    return this;
+  }
+  /**
+   * Adds multiple steps that execute in parallel.
+   * All steps in a parallel group will run concurrently and must all succeed before proceeding.
+   *
+   * @param steps - Array of step configurations to execute in parallel.
+   * @returns The builder instance for chaining.
+   *
+   * @example
+   * ```typescript
+   * workflow.stepParallel([
+   *   { name: 'fetch-user', handler: async (ctx) => { ctx.data.user = await getUser() } },
+   *   { name: 'fetch-orders', handler: async (ctx) => { ctx.data.orders = await getOrders() } },
+   *   { name: 'fetch-profile', handler: async (ctx) => { ctx.data.profile = await getProfile() } }
+   * ])
+   * ```
+   */
+  stepParallel(steps) {
+    if (steps.length === 0) {
+      return this;
+    }
+    const groupId = `parallel-${this._parallelGroupCounter++}`;
+    for (const stepConfig of steps) {
+      this._steps.push({
+        name: stepConfig.name,
+        handler: stepConfig.handler,
+        retries: _nullishCoalesce(stepConfig.retries, () => ( _optionalChain([stepConfig, 'access', _6 => _6.options, 'optionalAccess', _7 => _7.retries]))),
+        timeout: _nullishCoalesce(stepConfig.timeout, () => ( _optionalChain([stepConfig, 'access', _8 => _8.options, 'optionalAccess', _9 => _9.timeout]))),
+        when: _nullishCoalesce(stepConfig.when, () => ( _optionalChain([stepConfig, 'access', _10 => _10.options, 'optionalAccess', _11 => _11.when]))),
+        compensate: _nullishCoalesce(stepConfig.compensate, () => ( _optionalChain([stepConfig, 'access', _12 => _12.options, 'optionalAccess', _13 => _13.compensate]))),
+        commit: false,
+        parallelGroup: groupId
+      });
+    }
+    return this;
+  }
+  /**
+   * Adds a "commit" step that represents a permanent side-effect.
+   * Commit steps are intended for operations that should not be rolled back
+   * or re-executed during certain replay scenarios.
+   *
+   * @param name - Unique name for the step.
+   * @param handler - The side-effect logic to execute.
+   * @param options - Optional execution configuration (compensation is not allowed).
+   * @returns The builder instance for chaining.
+   */
+  commit(name, handler, options) {
+    this._steps.push({
+      name,
+      handler,
+      retries: _optionalChain([options, 'optionalAccess', _14 => _14.retries]),
+      timeout: _optionalChain([options, 'optionalAccess', _15 => _15.timeout]),
+      when: _optionalChain([options, 'optionalAccess', _16 => _16.when]),
+      commit: true
+    });
+    return this;
+  }
+  /**
+   * Finalizes the workflow definition.
+   * @returns A complete workflow blueprint ready for execution.
+   * @throws Error if the workflow has no steps defined.
+   */
+  build() {
+    if (this._steps.length === 0) {
+      throw emptyWorkflow(this._name);
+    }
+    return {
+      name: this._name,
+      version: this._version,
+      steps: [...this._steps],
+      validateInput: this._validateInput
+    };
+  }
+  /**
+   * Generates a structural description of the workflow for introspection.
+   * @returns A descriptor containing step metadata.
+   */
+  describe() {
+    const steps = this._steps.map((step) => ({
+      name: step.name,
+      commit: Boolean(step.commit),
+      retries: step.retries,
+      timeout: step.timeout,
+      hasCondition: Boolean(step.when)
+    }));
+    return {
+      name: this._name,
+      version: this._version,
+      steps
+    };
+  }
+  /** The name of the workflow being built. */
+  get name() {
+    return this._name;
+  }
+  /** The number of steps currently defined in the workflow. */
+  get stepCount() {
+    return this._steps.length;
+  }
+}, _class);
+function createWorkflow(name) {
+  return new WorkflowBuilder(name);
+}
+
+// src/engine/BatchExecutor.ts
+var Semaphore = (_class2 = class {
+  constructor(max) {;_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);
+    this.max = max;
+  }
+  __init3() {this.current = 0}
+  __init4() {this.queue = []}
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    await new Promise((resolve) => {
+      this.queue.push(() => {
+        this.current++;
+        resolve();
+      });
+    });
+  }
+  release() {
+    this.current--;
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    }
+  }
+}, _class2);
+var BatchExecutor = class {
+  constructor(engine) {
+    this.engine = engine;
+  }
+  /**
+   * Execute a workflow for multiple inputs with controlled concurrency.
+   *
+   * @param workflow - The workflow definition or builder to execute.
+   * @param inputs - Array of inputs, one per workflow execution.
+   * @param options - Execution options (concurrency, error handling, etc.).
+   * @returns Batch result containing all individual execution results.
+   */
+  async execute(workflow, inputs, options) {
+    const startTime = Date.now();
+    const concurrency = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _17 => _17.concurrency]), () => ( 10));
+    const continueOnError = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _18 => _18.continueOnError]), () => ( true));
+    const semaphore = new Semaphore(concurrency);
+    const results = new Array(inputs.length);
+    let succeeded = 0;
+    let failed = 0;
+    let completed = 0;
+    let shouldStop = false;
+    const executeOne = async (input, index) => {
+      if (_optionalChain([options, 'optionalAccess', _19 => _19.signal, 'optionalAccess', _20 => _20.aborted]) || shouldStop) {
+        results[index] = {
+          index,
+          input,
+          result: null,
+          error: new Error("Execution aborted"),
+          success: false
+        };
+        failed++;
+        completed++;
+        _optionalChain([options, 'optionalAccess', _21 => _21.onProgress, 'optionalCall', _22 => _22(completed, inputs.length, results[index])]);
+        return;
+      }
+      await semaphore.acquire();
+      try {
+        if (_optionalChain([options, 'optionalAccess', _23 => _23.signal, 'optionalAccess', _24 => _24.aborted]) || shouldStop) {
+          results[index] = {
+            index,
+            input,
+            result: null,
+            error: new Error("Execution aborted"),
+            success: false
+          };
+          failed++;
+        } else {
+          const result = await this.engine.execute(
+            workflow,
+            input
+          );
+          const success = result.status === "completed";
+          results[index] = {
+            index,
+            input,
+            result,
+            error: result.error,
+            success
+          };
+          if (success) {
+            succeeded++;
+          } else {
+            failed++;
+            if (!continueOnError) {
+              shouldStop = true;
+            }
+          }
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        results[index] = {
+          index,
+          input,
+          result: null,
+          error: err,
+          success: false
+        };
+        failed++;
+        if (!continueOnError) {
+          shouldStop = true;
+        }
+      } finally {
+        semaphore.release();
+        completed++;
+        _optionalChain([options, 'optionalAccess', _25 => _25.onProgress, 'optionalCall', _26 => _26(completed, inputs.length, results[index])]);
+      }
+    };
+    await Promise.all(inputs.map((input, index) => executeOne(input, index)));
+    return {
+      total: inputs.length,
+      succeeded,
+      failed,
+      results,
+      duration: Date.now() - startTime
+    };
+  }
+  /**
+   * Execute different workflows in a single batch.
+   *
+   * Unlike `execute()`, this method allows each item in the batch to use a different
+   * workflow definition, enabling heterogeneous batch processing.
+   *
+   * @param items - Array of workflow/input pairs to execute.
+   * @param options - Execution options (concurrency, error handling, etc.).
+   * @returns Batch result containing all individual execution results.
+   */
+  async executeMany(items, options) {
+    const startTime = Date.now();
+    const concurrency = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _27 => _27.concurrency]), () => ( 10));
+    const continueOnError = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _28 => _28.continueOnError]), () => ( true));
+    const semaphore = new Semaphore(concurrency);
+    const results = new Array(items.length);
+    let succeeded = 0;
+    let failed = 0;
+    let completed = 0;
+    let shouldStop = false;
+    const executeOne = async (item, index) => {
+      if (_optionalChain([options, 'optionalAccess', _29 => _29.signal, 'optionalAccess', _30 => _30.aborted]) || shouldStop) {
+        results[index] = {
+          index,
+          input: item.input,
+          result: null,
+          error: new Error("Execution aborted"),
+          success: false
+        };
+        failed++;
+        completed++;
+        _optionalChain([options, 'optionalAccess', _31 => _31.onProgress, 'optionalCall', _32 => _32(completed, items.length, results[index])]);
+        return;
+      }
+      await semaphore.acquire();
+      try {
+        if (_optionalChain([options, 'optionalAccess', _33 => _33.signal, 'optionalAccess', _34 => _34.aborted]) || shouldStop) {
+          results[index] = {
+            index,
+            input: item.input,
+            result: null,
+            error: new Error("Execution aborted"),
+            success: false
+          };
+          failed++;
+        } else {
+          const result = await this.engine.execute(item.workflow, item.input);
+          const success = result.status === "completed";
+          results[index] = {
+            index,
+            input: item.input,
+            result,
+            error: result.error,
+            success
+          };
+          if (success) {
+            succeeded++;
+          } else {
+            failed++;
+            if (!continueOnError) {
+              shouldStop = true;
+            }
+          }
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        results[index] = {
+          index,
+          input: item.input,
+          result: null,
+          error: err,
+          success: false
+        };
+        failed++;
+        if (!continueOnError) {
+          shouldStop = true;
+        }
+      } finally {
+        semaphore.release();
+        completed++;
+        _optionalChain([options, 'optionalAccess', _35 => _35.onProgress, 'optionalCall', _36 => _36(completed, items.length, results[index])]);
+      }
+    };
+    await Promise.all(items.map((item, index) => executeOne(item, index)));
+    return {
+      total: items.length,
+      succeeded,
+      failed,
+      results,
+      duration: Date.now() - startTime
+    };
+  }
+};
+
+// src/core/ContextManager.ts
+function generateId() {
+  return crypto.randomUUID();
+}
+var ContextManager = class {
+  /**
+   * Initializes a fresh workflow context with a pending status and empty history.
+   *
+   * @param name - The human-readable identifier for the workflow type.
+   * @param input - The initial data required to start the workflow.
+   * @param stepCount - Total number of steps defined in the workflow for history pre-allocation.
+   * @returns A new WorkflowContext instance.
+   *
+   * @example
+   * ```typescript
+   * const ctx = manager.create('signup', { email: 'user@example.com' }, 3);
+   * ```
+   */
+  create(name, input, stepCount) {
+    const history = Array.from({ length: stepCount }, (_, _i) => ({
+      name: "",
+      status: "pending",
+      retries: 0
+    }));
+    return {
+      id: generateId(),
+      name,
+      input,
+      data: {},
+      status: "pending",
+      currentStep: 0,
+      history,
+      version: 1
+    };
+  }
+  /**
+   * Reconstructs a workflow context from a previously persisted state.
+   *
+   * Used for resuming suspended workflows or replaying failed ones from a specific point.
+   *
+   * @param state - The persisted state object.
+   * @returns A hydrated WorkflowContext ready for execution.
+   *
+   * @example
+   * ```typescript
+   * const state = await storage.load(id);
+   * const ctx = manager.restore(state);
+   * ```
+   */
+  restore(state) {
+    return {
+      id: state.id,
+      name: state.name,
+      input: state.input,
+      data: { ...state.data },
+      status: state.status,
+      currentStep: state.currentStep,
+      history: state.history.map((h) => ({ ...h })),
+      version: state.version || 1
+    };
+  }
+  /**
+   * Converts a runtime context into a serializable state for persistence.
+   *
+   * Captures the current progress, data, and execution history.
+   *
+   * @param ctx - The active workflow context.
+   * @returns A serializable WorkflowState object.
+   *
+   * @example
+   * ```typescript
+   * const state = manager.toState(ctx);
+   * await storage.save(state);
+   * ```
+   */
+  toState(ctx) {
+    return {
+      id: ctx.id,
+      name: ctx.name,
+      status: ctx.status,
+      input: ctx.input,
+      data: { ...ctx.data },
+      currentStep: ctx.currentStep,
+      history: ctx.history.map((h) => ({ ...h })),
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date(),
+      version: ctx.version
+    };
+  }
+  /**
+   * Updates the overall status of the workflow.
+   *
+   * @param ctx - The current context.
+   * @param status - The new status to apply.
+   * @returns A new context instance with the updated status.
+   *
+   * @example
+   * ```typescript
+   * const runningCtx = manager.updateStatus(ctx, 'running');
+   * ```
+   */
+  updateStatus(ctx, status) {
+    return {
+      ...ctx,
+      status
+    };
+  }
+  /**
+   * Increments the current step pointer.
+   *
+   * @param ctx - The current context.
+   * @returns A new context instance pointing to the next step.
+   *
+   * @example
+   * ```typescript
+   * const nextStepCtx = manager.advanceStep(ctx);
+   * console.log(nextStepCtx.currentStep); // ctx.currentStep + 1
+   * ```
+   */
+  advanceStep(ctx) {
+    return {
+      ...ctx,
+      currentStep: ctx.currentStep + 1
+    };
+  }
+  /**
+   * Assigns a name to a specific step in the execution history.
+   *
+   * Useful for tracking which step is currently being executed or has been completed.
+   *
+   * @param ctx - The current context.
+   * @param index - The index of the step in the history array.
+   * @param name - The name to assign to the step.
+   * @returns A new context instance with the updated history.
+   *
+   * @example
+   * ```typescript
+   * const namedCtx = manager.setStepName(ctx, 0, 'validate-user');
+   * console.log(namedCtx.history[0].name); // 'validate-user'
+   * ```
+   */
+  setStepName(ctx, index, name) {
+    if (!ctx.history[index]) {
+      return ctx;
+    }
+    const history = [...ctx.history];
+    history[index] = { ...history[index], name };
+    return {
+      ...ctx,
+      history
+    };
+  }
+};
+
+// src/core/StateMachine.ts
+var TRANSITIONS = {
+  pending: ["running", "failed"],
+  running: ["paused", "completed", "failed", "suspended", "rolling_back"],
+  paused: ["running", "failed"],
+  suspended: ["running", "failed"],
+  rolling_back: ["rolled_back", "failed", "compensation_failed"],
+  rolled_back: ["pending"],
+  // allow retry from scratch
+  completed: [],
+  // terminal state
+  failed: ["pending"],
+  // allow retry
+  compensation_failed: ["pending"]
+  // allow retry even if compensation failed
+};
+var StateMachine = (_class3 = class extends EventTarget {constructor(...args2) { super(...args2); _class3.prototype.__init5.call(this); }
+  __init5() {this._status = "pending"}
+  /**
+   * The current operational status of the workflow.
+   */
+  get status() {
+    return this._status;
+  }
+  /**
+   * Evaluates if a transition to the specified status is valid from the current state.
+   *
+   * @param to - The target status to check.
+   * @returns True if the transition is permitted by the transition map.
+   *
+   * @example
+   * ```typescript
+   * if (sm.canTransition('completed')) {
+   *   sm.transition('completed');
+   * }
+   * ```
+   */
+  canTransition(to) {
+    return TRANSITIONS[this._status].includes(to);
+  }
+  /**
+   * Moves the workflow to a new status if the transition is valid.
+   *
+   * @param to - The target status.
+   * @throws {Error} If the transition is illegal according to the defined rules.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   sm.transition('completed');
+   * } catch (e) {
+   *   // Handle invalid transition
+   * }
+   * ```
+   */
+  transition(to) {
+    if (!this.canTransition(to)) {
+      throw invalidStateTransition(this._status, to);
+    }
+    const from = this._status;
+    this._status = to;
+    this.dispatchEvent(
+      new CustomEvent("transition", {
+        detail: { from, to }
+      })
+    );
+  }
+  /**
+   * Overrides the current status without validation.
+   *
+   * This should only be used during workflow restoration from persisted storage
+   * or when replaying history where the state is already known to be valid.
+   *
+   * @param status - The status to force set.
+   *
+   * @example
+   * ```typescript
+   * // Restore state from database
+   * sm.forceStatus(storedState.status);
+   * ```
+   */
+  forceStatus(status) {
+    this._status = status;
+  }
+  /**
+   * Determines if the workflow has reached a state where no further execution is possible.
+   *
+   * @returns True if the status is 'completed', 'failed', or 'rolled_back'.
+   *
+   * @example
+   * ```typescript
+   * if (sm.isTerminal()) {
+   *   console.log('Workflow finished');
+   * }
+   * ```
+   */
+  isTerminal() {
+    return this._status === "completed" || this._status === "failed" || this._status === "rolled_back" || this._status === "compensation_failed";
+  }
+  /**
+   * Checks if the workflow is in a state that allows for execution or resumption.
+   *
+   * @returns True if the workflow can be started or resumed.
+   *
+   * @example
+   * ```typescript
+   * if (sm.canExecute()) {
+   *   await engine.run();
+   * }
+   * ```
+   */
+  canExecute() {
+    return this._status === "pending" || this._status === "paused" || this._status === "suspended";
+  }
+}, _class3);
+
+// src/orbit/CronTrigger.ts
+var _cronparser = require('cron-parser');
+var CronTrigger = (_class4 = class {
+  /**
+   * Creates a new CronTrigger instance.
+   *
+   * @param engine - The Flux engine to use for executing scheduled workflows.
+   */
+  constructor(engine) {;_class4.prototype.__init6.call(this);_class4.prototype.__init7.call(this);_class4.prototype.__init8.call(this);
+    this.engine = engine;
+  }
+  __init6() {this.schedules = /* @__PURE__ */ new Map()}
+  __init7() {this.timers = /* @__PURE__ */ new Map()}
+  __init8() {this.running = false}
+  /**
+   * Starts the scheduler.
+   */
+  start() {
+    if (this.running) {
+      return;
+    }
+    this.running = true;
+    this.refreshAll();
+  }
+  /**
+   * Stops the scheduler and clears all timers.
+   */
+  stop() {
+    this.running = false;
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+  }
+  /**
+   * Adds a new schedule or updates an existing one.
+   *
+   * @param options - The schedule configuration.
+   */
+  addSchedule(options) {
+    this.schedules.set(options.id, options);
+    if (this.running) {
+      this.refreshSchedule(options.id);
+    }
+  }
+  /**
+   * Removes a schedule.
+   *
+   * @param id - The ID of the schedule to remove.
+   */
+  removeSchedule(id) {
+    this.schedules.delete(id);
+    const timer = this.timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+    }
+  }
+  /**
+   * Refreshes all active schedules.
+   * @private
+   */
+  refreshAll() {
+    for (const id of this.schedules.keys()) {
+      this.refreshSchedule(id);
+    }
+  }
+  /**
+   * Calculates the next execution time and sets a timer for a specific schedule.
+   *
+   * @param id - The ID of the schedule to refresh.
+   * @private
+   */
+  refreshSchedule(id) {
+    const schedule = this.schedules.get(id);
+    if (!schedule || schedule.enabled === false) {
+      return;
+    }
+    const existingTimer = this.timers.get(id);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+    try {
+      const interval = _cronparser.CronExpressionParser.parse(schedule.cron);
+      const nextDate = interval.next().toDate();
+      const delay = nextDate.getTime() - Date.now();
+      if (delay <= 0) {
+        const timer2 = setTimeout(() => this.refreshSchedule(id), 1e3);
+        this.timers.set(id, timer2);
+        return;
+      }
+      const timer = setTimeout(async () => {
+        if (!this.running) {
+          return;
+        }
+        try {
+          await this.engine.execute(schedule.workflow, schedule.input);
+        } catch (error) {
+          console.error(`[CronTrigger] Failed to execute scheduled workflow "${id}":`, error);
+        } finally {
+          if (this.running && this.schedules.has(id)) {
+            this.refreshSchedule(id);
+          }
+        }
+      }, delay);
+      this.timers.set(id, timer);
+    } catch (error) {
+      console.error(`[CronTrigger] Invalid cron expression for schedule "${id}":`, error);
+    }
+  }
+  /**
+   * Lists all registered schedules.
+   * @returns An array of schedule configurations.
+   */
+  listSchedules() {
+    return Array.from(this.schedules.values());
+  }
+}, _class4);
+
+// src/storage/MemoryStorage.ts
+var MemoryStorage = (_class5 = class {constructor() { _class5.prototype.__init9.call(this); }
+  __init9() {this.store = /* @__PURE__ */ new Map()}
+  /**
+   * Stores a workflow state in the internal Map.
+   *
+   * Automatically updates the `updatedAt` timestamp to reflect the current time.
+   *
+   * @param state - The workflow state to persist.
+   * @throws {Error} If the state object is invalid or cannot be stored.
+   */
+  async save(state) {
+    this.store.set(state.id, {
+      ...state,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /**
+   * Retrieves a workflow state by its ID from the internal Map.
+   *
+   * @param id - The unique identifier of the workflow.
+   * @returns The workflow state if found, otherwise null.
+   */
+  async load(id) {
+    return _nullishCoalesce(this.store.get(id), () => ( null));
+  }
+  /**
+   * Filters and returns workflow states stored in memory.
+   *
+   * Supports filtering by name and status, and provides basic pagination.
+   * Results are sorted by creation date in descending order.
+   *
+   * @param filter - Criteria for filtering and paginating results.
+   * @returns An array of matching workflow states.
+   */
+  async list(filter) {
+    let results = Array.from(this.store.values());
+    if (_optionalChain([filter, 'optionalAccess', _37 => _37.name])) {
+      results = results.filter((s) => s.name === filter.name);
+    }
+    if (_optionalChain([filter, 'optionalAccess', _38 => _38.status])) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      results = results.filter((s) => statuses.includes(s.status));
+    }
+    if (_optionalChain([filter, 'optionalAccess', _39 => _39.version])) {
+      results = results.filter((s) => s.definitionVersion === filter.version);
+    }
+    results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+    if (_optionalChain([filter, 'optionalAccess', _40 => _40.offset])) {
+      results = results.slice(filter.offset);
+    }
+    if (_optionalChain([filter, 'optionalAccess', _41 => _41.limit])) {
+      results = results.slice(0, filter.limit);
+    }
+    return results;
+  }
+  /**
+   * Removes a workflow state from the internal Map.
+   *
+   * @param id - The unique identifier of the workflow to delete.
+   */
+  async delete(id) {
+    this.store.delete(id);
+  }
+  /**
+   * Initializes the memory storage.
+   *
+   * This is a no-op for MemoryStorage but satisfies the WorkflowStorage interface.
+   */
+  async init() {
+  }
+  /**
+   * Clears all stored workflow states and resets the storage.
+   */
+  async close() {
+    this.store.clear();
+  }
+  /**
+   * Returns the total number of workflow states currently stored in memory.
+   *
+   * Useful for assertions in test environments.
+   *
+   * @returns The number of entries in the store.
+   */
+  size() {
+    return this.store.size;
+  }
+}, _class5);
+
+// src/core/executionUpdater.ts
+function updateStepExecution(execution, updates) {
+  return {
+    ...execution,
+    ...updates
+  };
+}
+
+// src/core/StepExecutor.ts
+var StepExecutor = class {
+  
+  
+  
+  /**
+   * Creates a new StepExecutor with global defaults.
+   *
+   * @param options - Configuration for default behavior and lifecycle hooks.
+   */
+  constructor(options = {}) {
+    this.defaultRetries = _nullishCoalesce(options.defaultRetries, () => ( 3));
+    this.defaultTimeout = _nullishCoalesce(options.defaultTimeout, () => ( 3e4));
+    this.onRetry = options.onRetry;
+  }
+  /**
+   * Executes a step definition against a workflow context.
+   *
+   * This method performs the following sequence:
+   * 1. Evaluates the `when` condition (if present).
+   * 2. Initiates the execution loop with retries.
+   * 3. Enforces timeouts for each attempt.
+   * 4. Handles suspension signals (`flux_wait`).
+   * 5. Updates the execution history record.
+   *
+   * @param step - The definition of the step to execute.
+   * @param ctx - The current workflow context.
+   * @param execution - The current execution record for this step.
+   * @returns The result of the execution and the updated execution record.
+   *
+   * @throws {Error} If the step handler throws an unrecoverable error or times out.
+   *
+   * @example
+   * ```typescript
+   * const { result, execution } = await executor.execute(
+   *   stepDefinition,
+   *   currentContext,
+   *   currentExecution
+   * );
+   *
+   * if (!result.success) {
+   *   console.error(result.error);
+   * }
+   * ```
+   */
+  async execute(step, ctx, execution) {
+    const maxRetries = _nullishCoalesce(step.retries, () => ( this.defaultRetries));
+    const timeout = _nullishCoalesce(step.timeout, () => ( this.defaultTimeout));
+    const startTime = Date.now();
+    let currentExecution = execution;
+    if (step.when && !step.when(ctx)) {
+      currentExecution = updateStepExecution(currentExecution, { status: "skipped" });
+      return {
+        result: {
+          success: true,
+          duration: 0
+        },
+        execution: currentExecution
+      };
+    }
+    currentExecution = updateStepExecution(currentExecution, {
+      status: "running",
+      startedAt: /* @__PURE__ */ new Date()
+    });
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      currentExecution = updateStepExecution(currentExecution, { retries: attempt });
+      try {
+        const result = await this.executeWithTimeout(step.handler, ctx, timeout);
+        if (result && typeof result === "object" && "__kind" in result && result.__kind === "flux_wait") {
+          const duration3 = Date.now() - startTime;
+          currentExecution = updateStepExecution(currentExecution, {
+            status: "suspended",
+            waitingFor: result.signal,
+            suspendedAt: /* @__PURE__ */ new Date(),
+            duration: duration3
+          });
+          return {
+            result: {
+              success: true,
+              suspended: true,
+              waitingFor: result.signal,
+              duration: duration3
+            },
+            execution: currentExecution
+          };
+        }
+        const duration2 = Date.now() - startTime;
+        currentExecution = updateStepExecution(currentExecution, {
+          status: "completed",
+          completedAt: /* @__PURE__ */ new Date(),
+          duration: duration2
+        });
+        return {
+          result: {
+            success: true,
+            duration: duration2
+          },
+          execution: currentExecution
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < maxRetries) {
+          await _optionalChain([this, 'access', _42 => _42.onRetry, 'optionalCall', _43 => _43(step, ctx, lastError, attempt + 1, maxRetries)]);
+          await this.sleep(Math.min(1e3 * 2 ** attempt, 1e4));
+        }
+      }
+    }
+    const duration = Date.now() - startTime;
+    currentExecution = updateStepExecution(currentExecution, {
+      status: "failed",
+      completedAt: /* @__PURE__ */ new Date(),
+      duration,
+      error: _optionalChain([lastError, 'optionalAccess', _44 => _44.message])
+    });
+    return {
+      result: {
+        success: false,
+        error: lastError,
+        duration
+      },
+      execution: currentExecution
+    };
+  }
+  /**
+   * Wraps the step handler in a timeout race.
+   *
+   * @param handler - The user-defined step handler.
+   * @param ctx - The workflow context.
+   * @param timeout - Maximum time allowed for execution in milliseconds.
+   * @returns The handler result or a suspension signal.
+   * @throws {Error} If the timeout is reached before the handler completes.
+   * @private
+   */
+  async executeWithTimeout(handler, ctx, timeout) {
+    let timer = null;
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Step timeout")), timeout);
+      });
+      return await Promise.race([Promise.resolve(handler(ctx)), timeoutPromise]);
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    }
+  }
+  /**
+   * Pauses execution for a specified duration.
+   *
+   * @param ms - Milliseconds to sleep.
+   * @private
+   */
+  async sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/core/DataOptimizer.ts
+var DataOptimizer = class _DataOptimizer {
+  
+  
+  /**
+   * Creates a new DataOptimizer instance.
+   *
+   * @param config - Configuration options for the optimizer.
+   */
+  constructor(config = {}) {
+    this.threshold = _nullishCoalesce(config.threshold, () => ( 10 * 1024));
+    this.defaultLocation = _nullishCoalesce(config.defaultLocation, () => ( "database"));
+  }
+  /**
+   * Estimates the size of a data object in bytes.
+   *
+   * This uses JSON.stringify to calculate the approximate size,
+   * which may not be exact for all types but provides a reasonable estimate.
+   *
+   * @param data - The data to measure.
+   * @returns The estimated size in bytes.
+   *
+   * @example
+   * ```typescript
+   * const size = DataOptimizer.estimateSize({ key: 'value' });
+   * console.log(size); // 15 (approximate)
+   * ```
+   */
+  static estimateSize(data) {
+    try {
+      return JSON.stringify(data).length;
+    } catch (e2) {
+      return Number.MAX_SAFE_INTEGER;
+    }
+  }
+  /**
+   * Optimizes a data object for storage by replacing large values with references.
+   *
+   * Iterates through the object's properties and converts any value exceeding the
+   * threshold to a DataReference object.
+   *
+   * @param data - The data object to optimize.
+   * @param customThreshold - Optional custom threshold for this optimization.
+   * @returns A new object with large values replaced by references.
+   *
+   * @example
+   * ```typescript
+   * const optimizer = new DataOptimizer({ threshold: 1024 });
+   * const result = optimizer.optimizeForStorage({
+   *   small: 'text',
+   *   large: Buffer.alloc(10 * 1024)
+   * });
+   * // result.small === 'text'
+   * // result.large.__ref === true
+   * ```
+   */
+  optimizeForStorage(data, customThreshold) {
+    const threshold = _nullishCoalesce(customThreshold, () => ( this.threshold));
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (value === null || value === void 0) {
+        result[key] = value;
+        continue;
+      }
+      if (this.isReference(value)) {
+        result[key] = value;
+        continue;
+      }
+      const size = _DataOptimizer.estimateSize(value);
+      if (size > threshold) {
+        result[key] = this.createReference(value, size);
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+  /**
+   * Checks if a value is a DataReference.
+   *
+   * @param value - The value to check.
+   * @returns True if the value is a DataReference.
+   */
+  isReference(value) {
+    return typeof value === "object" && value !== null && "__ref" in value && value.__ref === true;
+  }
+  /**
+   * Creates a DataReference from a value.
+   *
+   * @param value - The original value to create a reference for.
+   * @param size - The size of the original value in bytes.
+   * @returns A DataReference object.
+   * @private
+   */
+  createReference(_value, size) {
+    return {
+      __ref: true,
+      id: this.generateReferenceId(),
+      location: this.defaultLocation,
+      size
+      // Note: The actual storage and load implementation
+      // should be handled by the storage adapter
+    };
+  }
+  /**
+   * Generates a unique identifier for a data reference.
+   *
+   * @returns A unique reference ID.
+   * @private
+   */
+  generateReferenceId() {
+    return `ref_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+  }
+  /**
+   * Resolves references in a data object by loading the actual values.
+   *
+   * This is the inverse operation of optimizeForStorage.
+   *
+   * @param data - The data object containing references.
+   * @returns A promise resolving to the data with references replaced by actual values.
+   *
+   * @example
+   * ```typescript
+   * const optimizer = new DataOptimizer();
+   * const resolved = await optimizer.resolveReferences({
+   *   small: 'text',
+   *   large: { __ref: true, id: 'ref_123', location: 'database', size: 1024 }
+   * });
+   * // resolved.large contains the actual loaded data
+   * ```
+   */
+  async resolveReferences(data) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (this.isReference(value)) {
+        if (value.load) {
+          result[key] = await value.load();
+        } else {
+          result[key] = value;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+  /**
+   * Calculates the total size reduction achieved by optimization.
+   *
+   * @param original - The original data object.
+   * @param optimized - The optimized data object.
+   * @returns An object containing size statistics.
+   *
+   * @example
+   * ```typescript
+   * const optimizer = new DataOptimizer();
+   * const original = { large: Buffer.alloc(100 * 1024) };
+   * const optimized = optimizer.optimizeForStorage(original);
+   * const stats = optimizer.getOptimizationStats(original, optimized);
+   * console.log(stats); // { originalSize: 102400, optimizedSize: 100, reduction: 99.9 }
+   * ```
+   */
+  getOptimizationStats(original, optimized) {
+    const originalSize = _DataOptimizer.estimateSize(original);
+    const optimizedSize = _DataOptimizer.estimateSize(optimized);
+    const referencesCreated = Object.values(optimized).filter((v) => this.isReference(v)).length;
+    return {
+      originalSize,
+      optimizedSize,
+      reduction: (originalSize - optimizedSize) / originalSize * 100,
+      referencesCreated
+    };
+  }
+};
+
+// src/engine/CompensationRetryPolicy.ts
+var CompensationRetryPolicy = class {
+  
+  constructor(config = {}) {
+    this.config = {
+      maxAttempts: _nullishCoalesce(config.maxAttempts, () => ( 3)),
+      initialDelay: _nullishCoalesce(config.initialDelay, () => ( 1e3)),
+      backoffCoefficient: _nullishCoalesce(config.backoffCoefficient, () => ( 2)),
+      maxDelay: _nullishCoalesce(config.maxDelay, () => ( 3e4)),
+      jitter: _nullishCoalesce(config.jitter, () => ( 0.1))
+    };
+  }
+  /**
+   * Executes an operation with automatic retry on failure.
+   *
+   * Uses exponential backoff with jitter to avoid thundering herd problems.
+   *
+   * @param operation - The async operation to execute.
+   * @returns A promise resolving to the retry result.
+   *
+   * @example
+   * ```typescript
+   * const policy = new CompensationRetryPolicy();
+   *
+   * const result = await policy.execute(async () => {
+   *   await paymentGateway.refund(transactionId);
+   * });
+   *
+   * if (result.success) {
+   *   console.log(`Refund succeeded after ${result.attempts} attempts`);
+   * }
+   * ```
+   */
+  async execute(operation) {
+    const startTime = Date.now();
+    let lastError;
+    let attempts = 0;
+    while (attempts < this.config.maxAttempts) {
+      attempts++;
+      try {
+        const value = await operation();
+        return {
+          success: true,
+          value,
+          attempts,
+          duration: Date.now() - startTime
+        };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempts < this.config.maxAttempts) {
+          const delay = this.calculateDelay(attempts);
+          await this.sleep(delay);
+        }
+      }
+    }
+    return {
+      success: false,
+      error: lastError,
+      attempts,
+      duration: Date.now() - startTime
+    };
+  }
+  /**
+   * Calculates the delay for a given retry attempt using exponential backoff.
+   *
+   * @param attempt - The current attempt number (1-indexed).
+   * @returns The delay in milliseconds.
+   * @private
+   */
+  calculateDelay(attempt) {
+    const exponentialDelay = this.config.initialDelay * this.config.backoffCoefficient ** (attempt - 1);
+    const cappedDelay = Math.min(exponentialDelay, this.config.maxDelay);
+    const jitterAmount = cappedDelay * this.config.jitter;
+    const jitter = (Math.random() - 0.5) * 2 * jitterAmount;
+    return Math.max(0, cappedDelay + jitter);
+  }
+  /**
+   * Sleeps for the specified duration.
+   *
+   * @param ms - Duration in milliseconds.
+   * @private
+   */
+  async sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Checks if an error is retryable.
+   *
+   * By default, all errors are retryable. Override this method or provide
+   * a custom predicate to implement selective retry logic.
+   *
+   * @param error - The error to check.
+   * @returns True if the error is retryable.
+   *
+   * @example
+   * ```typescript
+   * class CustomRetryPolicy extends CompensationRetryPolicy {
+   *   isRetryable(error: Error): boolean {
+   *     return error.message.includes('TRANSIENT');
+   *   }
+   * }
+   * ```
+   */
+  isRetryable(_error) {
+    return true;
+  }
+  /**
+   * Executes an operation with selective retry based on error type.
+   *
+   * @param operation - The async operation to execute.
+   * @param isRetryable - Predicate to determine if an error should trigger retry.
+   * @returns A promise resolving to the retry result.
+   *
+   * @example
+   * ```typescript
+   * const policy = new CompensationRetryPolicy();
+   *
+   * const result = await policy.executeWithPredicate(
+   *   async () => await api.call(),
+   *   (err) => err.message.includes('timeout')
+   * );
+   * ```
+   */
+  async executeWithPredicate(operation, isRetryable) {
+    const startTime = Date.now();
+    let lastError;
+    let attempts = 0;
+    while (attempts < this.config.maxAttempts) {
+      attempts++;
+      try {
+        const value = await operation();
+        return {
+          success: true,
+          value,
+          attempts,
+          duration: Date.now() - startTime
+        };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (!isRetryable(lastError)) {
+          break;
+        }
+        if (attempts < this.config.maxAttempts) {
+          const delay = this.calculateDelay(attempts);
+          await this.sleep(delay);
+        }
+      }
+    }
+    return {
+      success: false,
+      error: lastError,
+      attempts,
+      duration: Date.now() - startTime
+    };
+  }
+  /**
+   * Gets the current retry configuration.
+   *
+   * @returns A copy of the current configuration.
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+
+// src/engine/stateUpdater.ts
+function updateWorkflowContext(ctx, updates) {
+  return {
+    ...ctx,
+    ...updates
+  };
+}
+
+// src/engine/FluxEngineHelpers.ts
+function createStepExecutor(config, traceEmitter) {
+  return new StepExecutor({
+    defaultRetries: config.defaultRetries,
+    defaultTimeout: config.defaultTimeout,
+    onRetry: async (step, ctx, error, attempt, maxRetries) => {
+      await traceEmitter.emit({
+        type: "step:retry",
+        timestamp: Date.now(),
+        workflowId: ctx.id,
+        workflowName: ctx.name,
+        stepName: step.name,
+        stepIndex: ctx.currentStep,
+        commit: Boolean(step.commit),
+        retries: attempt,
+        maxRetries,
+        error: error.message,
+        status: "running"
+      });
+    }
+  });
+}
+function resolveDefinition(workflow) {
+  return workflow instanceof WorkflowBuilder ? workflow.build() : workflow;
+}
+function resolveStartIndex(definition, fromStep, fallback) {
+  if (typeof fromStep === "number") {
+    if (fromStep < 0 || fromStep >= definition.steps.length) {
+      throw invalidStepIndex(fromStep);
+    }
+    return fromStep;
+  }
+  if (typeof fromStep === "string") {
+    const index = definition.steps.findIndex((step) => step.name === fromStep);
+    if (index === -1) {
+      throw stepNotFound(fromStep);
+    }
+    return index;
+  }
+  return Math.max(0, Math.min(fallback, definition.steps.length - 1));
+}
+function resetHistoryFrom(ctx, startIndex) {
+  for (let i = startIndex; i < ctx.history.length; i++) {
+    const entry = ctx.history[i];
+    if (!entry) {
+      continue;
+    }
+    entry.status = "pending";
+    entry.startedAt = void 0;
+    entry.completedAt = void 0;
+    entry.duration = void 0;
+    entry.error = void 0;
+    entry.retries = 0;
+  }
+}
+async function handleExecutionResult(definition, ctx, result, contextManager, rollbackManager, storage) {
+  if (result.status === "failed" && result.error) {
+    const failedIndex = result.history.findIndex((h) => h.status === "failed");
+    if (failedIndex !== -1) {
+      const latestState = await storage.load(ctx.id);
+      const restoredCtx = contextManager.restore({
+        ...contextManager.toState(ctx),
+        history: result.history,
+        data: result.data,
+        status: "failed",
+        version: _nullishCoalesce(_optionalChain([latestState, 'optionalAccess', _45 => _45.version]), () => ( result.version))
+      });
+      const rolledBackCtx = await rollbackManager.rollback(
+        definition,
+        restoredCtx,
+        failedIndex,
+        result.error
+      );
+      return {
+        ...result,
+        status: rolledBackCtx.status,
+        history: rolledBackCtx.history,
+        data: rolledBackCtx.data
+      };
+    }
+  }
+  return result;
+}
+async function persistContext(ctx, storage, contextManager, definitionVersion) {
+  const state = contextManager.toState(ctx);
+  const stored = await storage.load(state.id);
+  if (stored && stored.version !== state.version) {
+    throw new FluxError(
+      "Concurrent modification detected",
+      "CONCURRENT_MODIFICATION" /* CONCURRENT_MODIFICATION */
+    );
+  }
+  if (definitionVersion !== void 0) {
+    state.definitionVersion = definitionVersion;
+  } else if (_optionalChain([stored, 'optionalAccess', _46 => _46.definitionVersion])) {
+    state.definitionVersion = stored.definitionVersion;
+  }
+  const nextVersion = state.version + 1;
+  await storage.save({ ...state, version: nextVersion });
+  const result = updateWorkflowContext(ctx, { version: nextVersion });
+  return result;
+}
+async function acquireEngineLock(config, workflowId) {
+  if (!config.lockProvider) {
+    return null;
+  }
+  const owner = `node_${Math.random().toString(36).substring(7)}`;
+  return await config.lockProvider.acquire(workflowId, owner, 3e4);
+}
+
+// src/core/IdempotencyGuard.ts
+var IdempotencyGuard = class {
+  /**
+   * Checks if a step can be compensated based on its execution history.
+   *
+   * A step can be compensated if:
+   * - It has completed successfully
+   * - It has NOT already been compensated
+   * - It is not currently being compensated
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step to check.
+   * @returns True if the step can be safely compensated.
+   *
+   * @example
+   * ```typescript
+   * const guard = new IdempotencyGuard();
+   *
+   * if (guard.canCompensate(ctx, 'reserve-inventory')) {
+   *   await inventoryService.release(ctx.data.reservationId);
+   * }
+   * ```
+   */
+  canCompensate(ctx, stepName) {
+    const execution = this.findExecution(ctx, stepName);
+    if (!execution) {
+      return false;
+    }
+    return execution.status === "completed";
+  }
+  /**
+   * Checks if a step has already been compensated.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step to check.
+   * @returns True if the step has already been compensated.
+   *
+   * @example
+   * ```typescript
+   * if (guard.isCompensated(ctx, 'book-flight')) {
+   *   console.log('Flight booking already cancelled');
+   * }
+   * ```
+   */
+  isCompensated(ctx, stepName) {
+    const execution = this.findExecution(ctx, stepName);
+    return _optionalChain([execution, 'optionalAccess', _47 => _47.status]) === "compensated";
+  }
+  /**
+   * Checks if a step is currently being compensated.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step to check.
+   * @returns True if the step is currently in the compensating state.
+   */
+  isCompensating(ctx, stepName) {
+    const execution = this.findExecution(ctx, stepName);
+    return _optionalChain([execution, 'optionalAccess', _48 => _48.status]) === "compensating";
+  }
+  /**
+   * Retrieves the compensation timestamp for a step.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @returns The compensation timestamp if available, otherwise undefined.
+   */
+  getCompensationTimestamp(ctx, stepName) {
+    const execution = this.findExecution(ctx, stepName);
+    return _optionalChain([execution, 'optionalAccess', _49 => _49.compensatedAt]);
+  }
+  /**
+   * Counts how many times compensation has been attempted for a step.
+   *
+   * This is useful for implementing retry limits or circuit breakers.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @returns The number of compensation attempts (0 if never attempted).
+   */
+  getCompensationAttempts(ctx, stepName) {
+    const executions = ctx.history.filter((h) => h.name === stepName);
+    return executions.filter((e) => e.status === "compensated" || e.status === "compensating").length;
+  }
+  /**
+   * Finds the most recent execution record for a given step.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step to find.
+   * @returns The step execution record, or undefined if not found.
+   * @private
+   */
+  findExecution(ctx, stepName) {
+    for (let i = ctx.history.length - 1; i >= 0; i--) {
+      if (ctx.history[i].name === stepName) {
+        return ctx.history[i];
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Verifies that all completed steps have been compensated.
+   *
+   * Used to ensure rollback has fully completed.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepNames - Array of step names that should be compensated.
+   * @returns True if all specified steps are compensated.
+   *
+   * @example
+   * ```typescript
+   * const guard = new IdempotencyGuard();
+   * const completedSteps = ['reserve', 'charge', 'notify'];
+   *
+   * if (guard.allCompensated(ctx, completedSteps)) {
+   *   console.log('Rollback complete');
+   * }
+   * ```
+   */
+  allCompensated(ctx, stepNames) {
+    return stepNames.every((name) => this.isCompensated(ctx, name));
+  }
+  /**
+   * Finds all steps that need compensation but haven't been compensated yet.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepNames - Array of step names to check.
+   * @returns Array of step names that still need compensation.
+   *
+   * @example
+   * ```typescript
+   * const guard = new IdempotencyGuard();
+   * const pending = guard.getPendingCompensations(ctx, ['step1', 'step2', 'step3']);
+   * console.log(`Still need to compensate: ${pending.join(', ')}`);
+   * ```
+   */
+  getPendingCompensations(ctx, stepNames) {
+    return stepNames.filter((name) => {
+      const execution = this.findExecution(ctx, name);
+      return _optionalChain([execution, 'optionalAccess', _50 => _50.status]) === "completed";
+    });
+  }
+};
+
+// src/engine/RecoveryManager.ts
+var RecoveryManager = (_class6 = class {constructor() { _class6.prototype.__init10.call(this);_class6.prototype.__init11.call(this);_class6.prototype.__init12.call(this); }
+  __init10() {this.recoveryCallbacks = []}
+  __init11() {this.actions = /* @__PURE__ */ new Map()}
+  __init12() {this.pendingRecoveries = /* @__PURE__ */ new Map()}
+  /**
+   * Registers a callback to be invoked when recovery is needed.
+   *
+   * @param callback - Function to call when a recovery event occurs.
+   *
+   * @example
+   * ```typescript
+   * manager.onRecoveryNeeded(async (ctx, stepName, error) => {
+   *   await slack.send(`#alerts`, `Workflow ${ctx.id} needs recovery at ${stepName}`);
+   * });
+   * ```
+   */
+  onRecoveryNeeded(callback) {
+    this.recoveryCallbacks.push(callback);
+  }
+  /**
+   * Emits a recovery needed event.
+   *
+   * @param ctx - The workflow context.
+   * @param stepName - The step that failed compensation.
+   * @param error - The error that occurred.
+   */
+  async notifyRecoveryNeeded(ctx, stepName, error) {
+    this.pendingRecoveries.set(ctx.id, { stepName, error });
+    for (const callback of this.recoveryCallbacks) {
+      await callback(ctx, stepName, error);
+    }
+  }
+  /**
+   * Registers a recovery action for a specific step.
+   *
+   * @param stepName - The step name to associate the action with.
+   * @param action - The recovery action to perform.
+   *
+   * @example
+   * ```typescript
+   * manager.registerAction('book-flight', {
+   *   type: 'retry',
+   *   maxAttempts: 5
+   * });
+   *
+   * manager.registerAction('charge-card', {
+   *   type: 'manual',
+   *   handler: async () => {
+   *     await accountingSystem.manualRefund(transactionId);
+   *   }
+   * });
+   * ```
+   */
+  registerAction(stepName, action) {
+    this.actions.set(stepName, action);
+  }
+  /**
+   * Gets the registered recovery action for a step.
+   *
+   * @param stepName - The step name.
+   * @returns The recovery action if registered, otherwise undefined.
+   */
+  getAction(stepName) {
+    return this.actions.get(stepName);
+  }
+  /**
+   * Checks if a workflow has a pending recovery.
+   *
+   * @param workflowId - The workflow ID.
+   * @returns True if recovery is pending.
+   */
+  hasPendingRecovery(workflowId) {
+    return this.pendingRecoveries.has(workflowId);
+  }
+  /**
+   * Gets the pending recovery details for a workflow.
+   *
+   * @param workflowId - The workflow ID.
+   * @returns The pending recovery details if any.
+   */
+  getPendingRecovery(workflowId) {
+    return this.pendingRecoveries.get(workflowId);
+  }
+  /**
+   * Marks a recovery as resolved.
+   *
+   * @param workflowId - The workflow ID.
+   */
+  resolveRecovery(workflowId) {
+    this.pendingRecoveries.delete(workflowId);
+  }
+  /**
+   * Executes the registered recovery action for a step.
+   *
+   * @param stepName - The step name.
+   * @returns The recovery action result.
+   *
+   * @example
+   * ```typescript
+   * const action = manager.getAction('failed-step');
+   * if (action && action.type === 'manual') {
+   *   await manager.executeRecovery('failed-step');
+   * }
+   * ```
+   */
+  async executeRecovery(stepName) {
+    const action = this.actions.get(stepName);
+    if (!action) {
+      throw noRecoveryAction(stepName);
+    }
+    if (action.type === "manual") {
+      await action.handler();
+    }
+  }
+  /**
+   * Clears all registered actions.
+   */
+  clearActions() {
+    this.actions.clear();
+  }
+  /**
+   * Clears all recovery callbacks.
+   */
+  clearCallbacks() {
+    this.recoveryCallbacks = [];
+  }
+  /**
+   * Gets all pending recoveries.
+   *
+   * @returns A map of workflow IDs to pending recovery details.
+   */
+  getAllPendingRecoveries() {
+    return new Map(this.pendingRecoveries);
+  }
+  /**
+   * Clears all pending recoveries.
+   */
+  clearPendingRecoveries() {
+    this.pendingRecoveries.clear();
+  }
+  /**
+   * Gets the count of registered callbacks.
+   * @internal For testing purposes.
+   */
+  getCallbackCount() {
+    return this.recoveryCallbacks.length;
+  }
+}, _class6);
+
+// src/engine/RollbackManager.ts
+var RollbackManager = class {
+  /**
+   * Initializes the RollbackManager.
+   *
+   * @param storage - The storage adapter for persisting rollback progress.
+   * @param contextManager - Manager for workflow context operations.
+   * @param traceEmitter - Emitter for rollback-related trace events.
+   * @param onPersist - Optional callback to handle custom persistence logic.
+   * @param config - Optional configuration for retry, idempotency, and recovery.
+   */
+  constructor(storage, contextManager, traceEmitter, onPersist, config) {
+    this.storage = storage;
+    this.contextManager = contextManager;
+    this.traceEmitter = traceEmitter;
+    this.onPersist = onPersist;
+    this.retryPolicy = _nullishCoalesce(_optionalChain([config, 'optionalAccess', _51 => _51.retryPolicy]), () => ( new CompensationRetryPolicy()));
+    this.idempotencyGuard = _nullishCoalesce(_optionalChain([config, 'optionalAccess', _52 => _52.idempotencyGuard]), () => ( new IdempotencyGuard()));
+    this.recoveryManager = _nullishCoalesce(_optionalChain([config, 'optionalAccess', _53 => _53.recoveryManager]), () => ( new RecoveryManager()));
+  }
+  
+  
+  
+  /**
+   * Executes the rollback process for a failed workflow.
+   *
+   * Iterates backwards from the failed step and executes the `compensate` handler
+   * for each completed step that has one defined.
+   *
+   * @param definition - The definition of the workflow being rolled back.
+   * @param ctx - The current workflow context.
+   * @param failedAtIndex - The index of the step where the failure occurred.
+   * @param originalError - The error that triggered the rollback.
+   * @returns A promise resolving to the updated workflow context after rollback.
+   * @throws {Error} If compensation logic itself fails and recovery options are exhausted.
+   *
+   * @example
+   * ```typescript
+   * const rolledBackCtx = await rollbackManager.rollback(
+   *   definition,
+   *   ctx,
+   *   failedIndex,
+   *   error
+   * );
+   * ```
+   */
+  async rollback(definition, ctx, failedAtIndex, originalError) {
+    let currentCtx = updateWorkflowContext(ctx, { status: "rolling_back" });
+    await this.traceEmitter.emit({
+      type: "workflow:rollback_start",
+      timestamp: Date.now(),
+      workflowId: currentCtx.id,
+      workflowName: currentCtx.name,
+      status: "rolling_back",
+      error: originalError.message
+    });
+    let compensatedCount = 0;
+    for (let i = failedAtIndex - 1; i >= 0; i--) {
+      const step = definition.steps[i];
+      let execution = currentCtx.history[i];
+      if (!step || !step.compensate || !execution || execution.status !== "completed") {
+        continue;
+      }
+      if (this.idempotencyGuard.isCompensated(currentCtx, step.name)) {
+        continue;
+      }
+      try {
+        execution = { ...execution, status: "compensating" };
+        currentCtx = updateWorkflowContext(currentCtx, {
+          history: currentCtx.history.map((h, idx) => idx === i ? execution : h)
+        });
+        currentCtx = await this.persist(currentCtx);
+        if (this.retryPolicy.getConfig().maxAttempts === 0) {
+          await _optionalChain([step, 'access', _54 => _54.compensate, 'optionalCall', _55 => _55(currentCtx)]);
+        } else {
+          const result = await this.retryPolicy.execute(async () => {
+            await _optionalChain([step, 'access', _56 => _56.compensate, 'optionalCall', _57 => _57(currentCtx)]);
+          });
+          if (!result.success) {
+            throw _nullishCoalesce(result.error, () => ( new Error("Compensation failed")));
+          }
+        }
+        execution = { ...execution, status: "compensated", compensatedAt: /* @__PURE__ */ new Date() };
+        currentCtx = updateWorkflowContext(currentCtx, {
+          history: currentCtx.history.map((h, idx) => idx === i ? execution : h)
+        });
+        compensatedCount++;
+        await this.traceEmitter.stepCompensate(currentCtx, step.name, i);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const action = this.recoveryManager.getAction(step.name);
+        if (_optionalChain([action, 'optionalAccess', _58 => _58.type]) === "skip") {
+          continue;
+        }
+        if (_optionalChain([action, 'optionalAccess', _59 => _59.type]) === "abort") {
+          currentCtx = updateWorkflowContext(currentCtx, { status: "compensation_failed" });
+          await this.traceEmitter.emit({
+            type: "workflow:error",
+            timestamp: Date.now(),
+            workflowId: currentCtx.id,
+            workflowName: currentCtx.name,
+            status: "compensation_failed",
+            error: `Compensation aborted at step "${step.name}": ${error.message}`
+          });
+          return currentCtx;
+        }
+        await this.recoveryManager.notifyRecoveryNeeded(currentCtx, step.name, error);
+        currentCtx = updateWorkflowContext(currentCtx, { status: "compensation_failed" });
+        await this.traceEmitter.emit({
+          type: "workflow:error",
+          timestamp: Date.now(),
+          workflowId: currentCtx.id,
+          workflowName: currentCtx.name,
+          status: "compensation_failed",
+          error: `Compensation failed at step "${step.name}": ${error.message}`
+        });
+        return currentCtx;
+      }
+      currentCtx = await this.persist(currentCtx);
+    }
+    if (compensatedCount > 0) {
+      currentCtx = updateWorkflowContext(currentCtx, { status: "rolled_back" });
+      await this.traceEmitter.emit({
+        type: "workflow:rollback_complete",
+        timestamp: Date.now(),
+        workflowId: currentCtx.id,
+        workflowName: currentCtx.name,
+        status: "rolled_back"
+      });
+    } else {
+      currentCtx = updateWorkflowContext(currentCtx, { status: "failed" });
+    }
+    return currentCtx;
+  }
+  /**
+   * Persists the current context using the configured mechanism.
+   * @private
+   */
+  async persist(ctx) {
+    if (this.onPersist) {
+      return await this.onPersist(ctx);
+    } else {
+      await this.storage.save(this.contextManager.toState(ctx));
+      return ctx;
+    }
+  }
+  /**
+   * Gets the retry policy instance used by this manager.
+   * @returns The CompensationRetryPolicy instance.
+   */
+  getRetryPolicy() {
+    return this.retryPolicy;
+  }
+  /**
+   * Gets the idempotency guard instance used by this manager.
+   * @returns The IdempotencyGuard instance.
+   */
+  getIdempotencyGuard() {
+    return this.idempotencyGuard;
+  }
+  /**
+   * Gets the recovery manager instance used by this manager.
+   * @returns The RecoveryManager instance.
+   */
+  getRecoveryManager() {
+    return this.recoveryManager;
+  }
+};
+
+// src/engine/TraceEmitter.ts
+var TraceEmitter = class {
+  /**
+   * Initializes the TraceEmitter.
+   *
+   * @param traceSink - The destination for trace events.
+   */
+  constructor(traceSink) {
+    this.traceSink = traceSink;
+  }
+  /**
+   * Emits a raw trace event to the configured sink.
+   *
+   * @param event - The trace event to emit.
+   */
+  async emit(event) {
+    try {
+      await _optionalChain([this, 'access', _60 => _60.traceSink, 'optionalAccess', _61 => _61.emit, 'call', _62 => _62(event)]);
+    } catch (e3) {
+    }
+  }
+  /**
+   * Emits an event indicating that a workflow has started.
+   *
+   * @param ctx - The workflow context at the start.
+   */
+  async workflowStart(ctx) {
+    await this.emit({
+      type: "workflow:start",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      status: "running",
+      input: ctx.input
+    });
+  }
+  /**
+   * Emits an event indicating that a workflow has completed successfully.
+   *
+   * @param ctx - The final workflow context.
+   * @param duration - The total execution time in milliseconds.
+   */
+  async workflowComplete(ctx, duration) {
+    await this.emit({
+      type: "workflow:complete",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      status: "completed",
+      duration,
+      data: ctx.data
+    });
+  }
+  /**
+   * Emits an event indicating that a workflow has failed.
+   *
+   * @param ctx - The workflow context at the time of failure.
+   * @param error - The error that caused the failure.
+   * @param duration - The execution time until failure in milliseconds.
+   */
+  async workflowError(ctx, error, duration) {
+    await this.emit({
+      type: "workflow:error",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      status: "failed",
+      duration,
+      error: error.message
+    });
+  }
+  /**
+   * Emits an event indicating that a specific step has started.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @param stepIndex - The index of the step in the workflow.
+   * @param commit - Whether the step is a commit step.
+   */
+  async stepStart(ctx, stepName, stepIndex, commit) {
+    await this.emit({
+      type: "step:start",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      stepName,
+      stepIndex,
+      commit,
+      status: "running"
+    });
+  }
+  /**
+   * Emits an event indicating that a step has completed successfully.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @param stepIndex - The index of the step.
+   * @param result - The result of the step execution.
+   */
+  async stepComplete(ctx, stepName, stepIndex, result) {
+    await this.emit({
+      type: "step:complete",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      stepName,
+      stepIndex,
+      duration: result.duration,
+      status: "completed"
+    });
+  }
+  /**
+   * Emits an event indicating that a step has failed.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @param stepIndex - The index of the step.
+   * @param result - The result containing the error.
+   */
+  async stepError(ctx, stepName, stepIndex, result) {
+    await this.emit({
+      type: "step:error",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      stepName,
+      stepIndex,
+      duration: result.duration,
+      error: _optionalChain([result, 'access', _63 => _63.error, 'optionalAccess', _64 => _64.message]),
+      status: "failed"
+    });
+  }
+  /**
+   * Emits an event indicating that a step has been suspended.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step.
+   * @param stepIndex - The index of the step.
+   * @param signal - The name of the signal the step is waiting for.
+   */
+  async stepSuspended(ctx, stepName, stepIndex, signal) {
+    await this.emit({
+      type: "step:suspend",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      stepName,
+      stepIndex,
+      meta: { signal }
+    });
+  }
+  /**
+   * Emits an event indicating that a step's compensation logic has been executed.
+   *
+   * @param ctx - The current workflow context.
+   * @param stepName - The name of the step being compensated.
+   * @param stepIndex - The index of the step.
+   */
+  async stepCompensate(ctx, stepName, stepIndex) {
+    await this.emit({
+      type: "step:compensate",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      stepName,
+      stepIndex,
+      status: "compensated"
+    });
+  }
+};
+
+// src/engine/ParallelExecutor.ts
+var ParallelExecutor = class {
+  /**
+   * Executes a list of steps concurrently.
+   *
+   * @param steps - The definitions of the steps to run in parallel.
+   * @param ctx - The shared workflow context.
+   * @param executeStep - A callback function to execute a single step.
+   * @returns A promise resolving to the aggregated execution results.
+   */
+  async executeGroup(steps, ctx, executeStep) {
+    const results = await Promise.allSettled(
+      steps.map(async (step, index) => {
+        try {
+          const result = await executeStep(step, ctx);
+          return { step, result, index, success: true };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          return { step, error: err, index, success: false };
+        }
+      })
+    );
+    const successes = [];
+    const failures = [];
+    for (const promiseResult of results) {
+      if (promiseResult.status === "fulfilled") {
+        const value = promiseResult.value;
+        if (value.success) {
+          successes.push(value.result.execution);
+        } else {
+          const failedExecution = {
+            name: value.step.name,
+            status: "failed",
+            startedAt: /* @__PURE__ */ new Date(),
+            error: value.error.message,
+            retries: 0
+          };
+          failures.push({
+            step: value.step,
+            error: value.error,
+            execution: failedExecution
+          });
+        }
+      } else {
+        const error = promiseResult.reason instanceof Error ? promiseResult.reason : new Error(String(promiseResult.reason));
+        const failedExecution = {
+          name: "unknown-step",
+          status: "failed",
+          startedAt: /* @__PURE__ */ new Date(),
+          error: error.message,
+          retries: 0
+        };
+        failures.push({
+          step: steps[0],
+          error,
+          execution: failedExecution
+        });
+      }
+    }
+    return { successes, failures };
+  }
+};
+
+// src/engine/WorkflowExecutor.ts
+var WorkflowExecutor = class {
+  /**
+   * Initializes the WorkflowExecutor.
+   *
+   * @param storage - The storage adapter for persistence.
+   * @param contextManager - Manager for workflow context operations.
+   * @param stepExecutor - Executor for individual steps.
+   * @param traceEmitter - Emitter for execution-related trace events.
+   * @param config - Global engine configuration.
+   * @param onPersist - Optional callback for custom persistence logic.
+   */
+  constructor(storage, contextManager, stepExecutor, traceEmitter, config = {}, onPersist, optimizer) {
+    this.storage = storage;
+    this.contextManager = contextManager;
+    this.stepExecutor = stepExecutor;
+    this.traceEmitter = traceEmitter;
+    this.config = config;
+    this.onPersist = onPersist;
+    this.optimizer = optimizer;
+    this.parallelExecutor = new ParallelExecutor();
+  }
+  
+  /**
+   * Executes the steps of a workflow definition.
+   *
+   * This method manages the loop over workflow steps, handling suspensions,
+   * failures, and successful completions. It delegates parallel step groups
+   * to the ParallelExecutor.
+   *
+   * @param definition - The workflow definition to execute.
+   * @param ctx - The current workflow context.
+   * @param stateMachine - The state machine governing the workflow status.
+   * @param startTime - The timestamp when the workflow execution originally started.
+   * @param startIndex - The index of the step to start execution from.
+   * @param meta - Metadata about the execution (e.g., if it's a resume or retry).
+   * @returns A promise resolving to the result of the workflow execution.
+   * @throws {Error} If execution fails and no rollback/recovery was successful (handled internally but re-thrown if critical).
+   *
+   * @example
+   * ```typescript
+   * const result = await executor.execute(definition, ctx, stateMachine, Date.now(), 0);
+   * ```
+   */
+  async execute(definition, ctx, stateMachine, startTime, startIndex, meta) {
+    let currentCtx = ctx;
+    try {
+      if (stateMachine.canExecute()) {
+        stateMachine.transition("running");
+        currentCtx = updateWorkflowContext(currentCtx, { status: "running" });
+      }
+      if (!_optionalChain([meta, 'optionalAccess', _65 => _65.resume]) && !_optionalChain([meta, 'optionalAccess', _66 => _66.retry])) {
+        await this.traceEmitter.workflowStart(currentCtx);
+      }
+      for (let i = startIndex; i < definition.steps.length; ) {
+        const step = definition.steps[i];
+        if (step.parallelGroup) {
+          const { lastIndex, updatedCtx, result } = await this.executeParallelGroup(
+            definition,
+            currentCtx,
+            i,
+            startTime
+          );
+          currentCtx = updatedCtx;
+          currentCtx = await this.persist(currentCtx);
+          if (result) {
+            return result;
+          }
+          i = lastIndex + 1;
+        } else {
+          const { updatedCtx, shouldReturn, result } = await this.executeSequentialStep(
+            definition,
+            currentCtx,
+            i,
+            startTime,
+            stateMachine
+          );
+          currentCtx = updatedCtx;
+          currentCtx = await this.persist(currentCtx);
+          if (shouldReturn && result) {
+            return result;
+          }
+          i++;
+        }
+      }
+      stateMachine.transition("completed");
+      currentCtx = updateWorkflowContext(currentCtx, { status: "completed" });
+      currentCtx = await this.persist(currentCtx);
+      _optionalChain([this, 'access', _67 => _67.config, 'access', _68 => _68.on, 'optionalAccess', _69 => _69.workflowComplete, 'optionalCall', _70 => _70(currentCtx)]);
+      await this.traceEmitter.workflowComplete(currentCtx, Date.now() - startTime);
+      return {
+        id: currentCtx.id,
+        status: "completed",
+        data: currentCtx.data,
+        history: currentCtx.history,
+        duration: Date.now() - startTime,
+        version: currentCtx.version
+      };
+    } catch (error) {
+      console.log(
+        "In catch block, history:",
+        currentCtx.history.map((h) => ({ name: h.name, status: h.status }))
+      );
+      const err = error instanceof Error ? error : new Error(String(error));
+      stateMachine.forceStatus("failed");
+      currentCtx = updateWorkflowContext(currentCtx, { status: "failed" });
+      currentCtx = await this.persist(currentCtx);
+      _optionalChain([this, 'access', _71 => _71.config, 'access', _72 => _72.on, 'optionalAccess', _73 => _73.workflowError, 'optionalCall', _74 => _74(currentCtx, err)]);
+      await this.traceEmitter.workflowError(currentCtx, err, Date.now() - startTime);
+      return {
+        id: currentCtx.id,
+        status: "failed",
+        data: currentCtx.data,
+        history: currentCtx.history,
+        duration: Date.now() - startTime,
+        error: err,
+        version: currentCtx.version
+      };
+    }
+  }
+  /**
+   * Executes a single sequential step.
+   * @private
+   */
+  async executeSequentialStep(definition, ctx, index, startTime, stateMachine) {
+    const step = definition.steps[index];
+    let execution = ctx.history[index];
+    let currentCtx = ctx;
+    currentCtx = this.contextManager.setStepName(currentCtx, index, step.name);
+    execution = currentCtx.history[index];
+    currentCtx = updateWorkflowContext(currentCtx, { currentStep: index });
+    _optionalChain([this, 'access', _75 => _75.config, 'access', _76 => _76.on, 'optionalAccess', _77 => _77.stepStart, 'optionalCall', _78 => _78(step.name, currentCtx)]);
+    await this.traceEmitter.stepStart(currentCtx, step.name, index, Boolean(step.commit));
+    const { result, execution: updatedExecution } = await this.stepExecutor.execute(
+      step,
+      currentCtx,
+      execution
+    );
+    execution = updatedExecution;
+    currentCtx = updateWorkflowContext(currentCtx, {
+      history: currentCtx.history.map((h, idx) => idx === index ? execution : h)
+    });
+    if (result.success) {
+      if (result.suspended) {
+        stateMachine.transition("suspended");
+        currentCtx = updateWorkflowContext(currentCtx, { status: "suspended" });
+        await this.traceEmitter.stepSuspended(currentCtx, step.name, index, result.waitingFor);
+        const suspendedResult = {
+          id: currentCtx.id,
+          status: "suspended",
+          data: currentCtx.data,
+          history: currentCtx.history,
+          duration: Date.now() - startTime,
+          version: currentCtx.version
+        };
+        return { updatedCtx: currentCtx, shouldReturn: true, result: suspendedResult };
+      }
+      _optionalChain([this, 'access', _79 => _79.config, 'access', _80 => _80.on, 'optionalAccess', _81 => _81.stepComplete, 'optionalCall', _82 => _82(step.name, currentCtx, result)]);
+      await this.traceEmitter.stepComplete(currentCtx, step.name, index, result);
+    } else {
+      await this.traceEmitter.stepError(currentCtx, step.name, index, result);
+      const failedResult = {
+        id: currentCtx.id,
+        status: "failed",
+        data: currentCtx.data,
+        history: currentCtx.history,
+        duration: Date.now() - startTime,
+        error: result.error,
+        version: currentCtx.version
+      };
+      return { updatedCtx: currentCtx, shouldReturn: true, result: failedResult };
+    }
+    return { updatedCtx: currentCtx, shouldReturn: false };
+  }
+  /**
+   * Executes a group of parallel steps.
+   * @private
+   */
+  async executeParallelGroup(definition, ctx, startIndex, startTime) {
+    const firstStep = definition.steps[startIndex];
+    const groupId = firstStep.parallelGroup;
+    const groupSteps = [];
+    for (let i = startIndex; i < definition.steps.length; i++) {
+      const step = definition.steps[i];
+      if (step.parallelGroup === groupId) {
+        groupSteps.push({ step, index: i });
+      } else {
+        break;
+      }
+    }
+    const lastIndex = _optionalChain([groupSteps, 'access', _83 => _83[groupSteps.length - 1], 'optionalAccess', _84 => _84.index]);
+    let currentCtx = ctx;
+    const executeStepWrapper = async (step, stepCtx) => {
+      const stepIndex = _optionalChain([groupSteps, 'access', _85 => _85.find, 'call', _86 => _86((gs) => gs.step === step), 'optionalAccess', _87 => _87.index]);
+      let execution = stepCtx.history[stepIndex];
+      const localCtx = this.contextManager.setStepName(stepCtx, stepIndex, step.name);
+      execution = localCtx.history[stepIndex];
+      _optionalChain([this, 'access', _88 => _88.config, 'access', _89 => _89.on, 'optionalAccess', _90 => _90.stepStart, 'optionalCall', _91 => _91(step.name, localCtx)]);
+      await this.traceEmitter.stepStart(localCtx, step.name, stepIndex, Boolean(step.commit));
+      const { result, execution: updatedExecution } = await this.stepExecutor.execute(
+        step,
+        localCtx,
+        execution
+      );
+      if (result.success) {
+        _optionalChain([this, 'access', _92 => _92.config, 'access', _93 => _93.on, 'optionalAccess', _94 => _94.stepComplete, 'optionalCall', _95 => _95(step.name, localCtx, result)]);
+        await this.traceEmitter.stepComplete(localCtx, step.name, stepIndex, result);
+      } else {
+        await this.traceEmitter.stepError(localCtx, step.name, stepIndex, result);
+        throw result.error || new Error(`Step ${step.name} failed`);
+      }
+      return { ctx: localCtx, execution: updatedExecution };
+    };
+    try {
+      const parallelResult = await this.parallelExecutor.executeGroup(
+        groupSteps.map((gs) => gs.step),
+        currentCtx,
+        executeStepWrapper
+      );
+      for (const execution of parallelResult.successes) {
+        const stepIndex = _optionalChain([groupSteps, 'access', _96 => _96.find, 'call', _97 => _97((gs) => gs.step.name === execution.name), 'optionalAccess', _98 => _98.index]);
+        currentCtx = updateWorkflowContext(currentCtx, {
+          history: currentCtx.history.map((h, idx) => idx === stepIndex ? execution : h)
+        });
+      }
+      for (const failure of parallelResult.failures) {
+        const stepIndex = _optionalChain([groupSteps, 'access', _99 => _99.find, 'call', _100 => _100((gs) => gs.step.name === failure.step.name), 'optionalAccess', _101 => _101.index]);
+        currentCtx = updateWorkflowContext(currentCtx, {
+          history: currentCtx.history.map((h, idx) => idx === stepIndex ? failure.execution : h)
+        });
+      }
+      if (parallelResult.failures.length > 0) {
+        const firstFailure = parallelResult.failures[0];
+        const failedResult = {
+          id: currentCtx.id,
+          status: "failed",
+          data: currentCtx.data,
+          history: currentCtx.history,
+          duration: Date.now() - startTime,
+          error: firstFailure.error,
+          version: currentCtx.version
+        };
+        return { lastIndex, updatedCtx: currentCtx, result: failedResult };
+      }
+      return { lastIndex, updatedCtx: currentCtx };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      const failedResult = {
+        id: currentCtx.id,
+        status: "failed",
+        data: currentCtx.data,
+        history: currentCtx.history,
+        duration: Date.now() - startTime,
+        error: err,
+        version: currentCtx.version
+      };
+      return { lastIndex, updatedCtx: currentCtx, result: failedResult };
+    }
+  }
+  /**
+   * Persists the context to storage.
+   * @private
+   */
+  async persist(ctx) {
+    let currentCtx = ctx;
+    if (this.optimizer) {
+      const optimizedData = this.optimizer.optimizeForStorage(ctx.data);
+      currentCtx = updateWorkflowContext(ctx, { data: optimizedData });
+    }
+    if (this.onPersist) {
+      return await this.onPersist(currentCtx);
+    } else {
+      await this.storage.save(this.contextManager.toState(currentCtx));
+      return currentCtx;
+    }
+  }
+};
+
+// src/engine/FluxEngine.ts
+var FluxEngine = class {
+  
+  
+  
+  
+  
+  
+  
+  constructor(config = {}) {
+    this.storage = _nullishCoalesce(config.storage, () => ( new MemoryStorage()));
+    this.contextManager = new ContextManager();
+    this.traceEmitter = new TraceEmitter(config.trace);
+    if (_optionalChain([config, 'access', _102 => _102.optimizer, 'optionalAccess', _103 => _103.enabled])) {
+      this.dataOptimizer = new DataOptimizer({
+        threshold: config.optimizer.threshold,
+        defaultLocation: config.optimizer.defaultLocation
+      });
+    }
+    const stepExecutor = createStepExecutor(config, this.traceEmitter);
+    const persist = (ctx) => this.persist(ctx);
+    this.executor = new WorkflowExecutor(
+      this.storage,
+      this.contextManager,
+      stepExecutor,
+      this.traceEmitter,
+      config,
+      persist,
+      this.dataOptimizer
+    );
+    this.rollbackManager = new RollbackManager(
+      this.storage,
+      this.contextManager,
+      this.traceEmitter,
+      persist,
+      {
+        retryPolicy: new CompensationRetryPolicy({
+          maxAttempts: config.defaultRetries !== void 0 ? config.defaultRetries : 3
+        })
+      }
+    );
+    this.cronTrigger = new CronTrigger(this);
+    this.config = config;
+  }
+  
+  async execute(workflow, input) {
+    const definition = resolveDefinition(workflow);
+    if (definition.validateInput && !definition.validateInput(input)) {
+      throw invalidInput(definition.name);
+    }
+    let ctx = this.contextManager.create(
+      definition.name,
+      input,
+      definition.steps.length
+    );
+    ctx = await this.persist(ctx, definition.version);
+    return this.executeWithLock(definition, ctx, 0, {}, Date.now());
+  }
+  async executeBatch(workflow, inputs, options) {
+    const executor = new BatchExecutor(this);
+    return executor.execute(workflow, inputs, options);
+  }
+  async executeWithLock(definition, ctx, startIndex, options, startTime) {
+    const lock = await acquireEngineLock(this.config, ctx.id);
+    try {
+      const result = await this.executor.execute(
+        definition,
+        ctx,
+        new StateMachine(),
+        _nullishCoalesce(startTime, () => ( Date.now())),
+        startIndex,
+        options
+      );
+      return handleExecutionResult(
+        definition,
+        ctx,
+        result,
+        this.contextManager,
+        this.rollbackManager,
+        this.storage
+      );
+    } finally {
+      await _optionalChain([lock, 'optionalAccess', _104 => _104.release, 'call', _105 => _105()]);
+    }
+  }
+  async resume(workflow, workflowId, options) {
+    const definition = resolveDefinition(workflow);
+    const state = await this.storage.load(workflowId);
+    if (!state || state.name !== definition.name) {
+      if (!state) {
+        return null;
+      }
+      throw workflowNameMismatch(definition.name, state.name);
+    }
+    if (state.history.length !== definition.steps.length) {
+      throw workflowDefinitionChanged();
+    }
+    if (state.definitionVersion && definition.version && state.definitionVersion !== definition.version) {
+      _optionalChain([this, 'access', _106 => _106.config, 'access', _107 => _107.logger, 'optionalAccess', _108 => _108.warn, 'call', _109 => _109(
+        `Workflow version mismatch: instance was created with v${state.definitionVersion}, but current definition is v${definition.version}. Continuing execution.`
+      )]);
+    }
+    let ctx = this.contextManager.restore(
+      state
+    );
+    const startIndex = resolveStartIndex(definition, _optionalChain([options, 'optionalAccess', _110 => _110.fromStep]), ctx.currentStep);
+    resetHistoryFrom(ctx, startIndex);
+    ctx = updateWorkflowContext(ctx, { status: "pending", currentStep: startIndex });
+    ctx = await this.persist(ctx);
+    return this.executeWithLock(definition, ctx, startIndex, { resume: true, fromStep: startIndex });
+  }
+  async signal(workflow, workflowId, signalName, payload) {
+    const definition = resolveDefinition(workflow);
+    const state = await this.storage.load(workflowId);
+    if (!state) {
+      throw workflowNotFound(workflowId);
+    }
+    if (state.status !== "suspended") {
+      throw workflowNotSuspended(state.status);
+    }
+    let ctx = this.contextManager.restore(
+      state
+    );
+    const idx = ctx.currentStep;
+    const exec = ctx.history[idx];
+    if (!exec || exec.status !== "suspended" || exec.waitingFor !== signalName) {
+      const isSuspended = _optionalChain([exec, 'optionalAccess', _111 => _111.status]) === "suspended";
+      throw new FluxError(
+        isSuspended ? `Workflow waiting for signal "${exec.waitingFor}", received "${signalName}"` : "Workflow state invalid: no suspended step found",
+        isSuspended ? "INVALID_STATE_TRANSITION" /* INVALID_STATE_TRANSITION */ : "STEP_NOT_FOUND" /* STEP_NOT_FOUND */
+      );
+    }
+    ctx = updateWorkflowContext(ctx, {
+      history: ctx.history.map(
+        (h, i) => i === idx ? { ...h, status: "completed", completedAt: /* @__PURE__ */ new Date(), output: payload } : h
+      )
+    });
+    await this.traceEmitter.emit({
+      type: "signal:received",
+      timestamp: Date.now(),
+      workflowId: ctx.id,
+      workflowName: ctx.name,
+      status: "suspended",
+      input: payload
+    });
+    return this.executeWithLock(definition, ctx, idx + 1, { resume: true, fromStep: idx + 1 });
+  }
+  async retryStep(workflow, workflowId, stepName) {
+    const definition = resolveDefinition(workflow);
+    const state = await this.storage.load(workflowId);
+    if (!state || state.name !== definition.name) {
+      if (!state) {
+        return null;
+      }
+      throw workflowNameMismatch(definition.name, state.name);
+    }
+    if (state.history.length !== definition.steps.length) {
+      throw workflowDefinitionChanged();
+    }
+    let ctx = this.contextManager.restore(
+      state
+    );
+    const idx = resolveStartIndex(definition, stepName, ctx.currentStep);
+    resetHistoryFrom(ctx, idx);
+    ctx = updateWorkflowContext(ctx, { status: "pending", currentStep: idx });
+    ctx = await this.persist(ctx);
+    return this.executeWithLock(definition, ctx, idx, { retry: true, fromStep: idx });
+  }
+  /**
+   * Retrieves the current state of a workflow instance from storage.
+   *
+   * @param workflowId - The unique identifier of the workflow.
+   * @returns A promise resolving to the workflow state or null if not found.
+   */
+  async get(workflowId) {
+    return this.storage.load(workflowId);
+  }
+  async saveState(state) {
+    const stored = await this.storage.load(state.id);
+    if (stored && stored.version !== state.version) {
+      throw new FluxError(
+        "Concurrent modification detected",
+        "CONCURRENT_MODIFICATION" /* CONCURRENT_MODIFICATION */
+      );
+    }
+    return this.storage.save({ ...state, version: state.version + 1 });
+  }
+  async list(filter) {
+    return this.storage.list(filter);
+  }
+  schedule(cron, workflow, input, id = `schedule_${Date.now()}`) {
+    this.cronTrigger.addSchedule({
+      id,
+      cron,
+      workflow: resolveDefinition(workflow),
+      input,
+      enabled: true
+    });
+    return id;
+  }
+  unschedule(id) {
+    this.cronTrigger.removeSchedule(id);
+  }
+  /**
+   * Lists all active workflow schedules.
+   */
+  listSchedules() {
+    return this.cronTrigger.listSchedules();
+  }
+  /**
+   * Gets the recovery manager for handling manual intervention.
+   */
+  getRecoveryManager() {
+    return this.rollbackManager.getRecoveryManager();
+  }
+  /**
+   * Gets the lock provider used for cluster mode.
+   */
+  getLockProvider() {
+    return this.config.lockProvider;
+  }
+  /**
+   * Initializes the engine and its underlying storage, and starts the scheduler.
+   */
+  async init() {
+    await _optionalChain([this, 'access', _112 => _112.storage, 'access', _113 => _113.init, 'optionalCall', _114 => _114()]);
+    this.cronTrigger.start();
+  }
+  /**
+   * Closes the engine and releases storage resources.
+   */
+  async close() {
+    this.cronTrigger.stop();
+    await _optionalChain([this, 'access', _115 => _115.storage, 'access', _116 => _116.close, 'optionalCall', _117 => _117()]);
+  }
+  async persist(ctx, definitionVersion) {
+    return persistContext(ctx, this.storage, this.contextManager, definitionVersion);
+  }
+};
+
+// src/storage/PostgreSQLStorage.ts
+var PostgreSQLStorage = (_class7 = class {
+  
+  
+  __init13() {this.initialized = false}
+  
+  /**
+   * Creates a new PostgreSQL storage instance.
+   *
+   * @param options - Connection and configuration options.
+   */
+  constructor(options = {}) {;_class7.prototype.__init13.call(this);
+    this.options = options;
+    this.tableName = _nullishCoalesce(options.tableName, () => ( "flux_workflows"));
+  }
+  /**
+   * Initializes the database connection pool and schema.
+   *
+   * Creates the workflow table and indexes if they do not exist.
+   * This method is idempotent.
+   *
+   * @throws {Error} If connection fails or schema creation fails.
+   */
+  async init() {
+    if (this.initialized) {
+      return;
+    }
+    const { Pool } = await Promise.resolve().then(() => _interopRequireWildcard(require("pg")));
+    const config = this.options.connectionString ? { connectionString: this.options.connectionString } : {
+      host: _nullishCoalesce(this.options.host, () => ( "localhost")),
+      port: _nullishCoalesce(this.options.port, () => ( 5432)),
+      database: _nullishCoalesce(this.options.database, () => ( "postgres")),
+      user: this.options.user,
+      password: this.options.password
+    };
+    if (this.options.ssl !== void 0) {
+      config.ssl = this.options.ssl;
+    }
+    this.pool = new Pool(config);
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        status TEXT NOT NULL,
+        input JSONB NOT NULL,
+        data JSONB NOT NULL,
+        current_step INTEGER NOT NULL,
+        history JSONB NOT NULL,
+        error TEXT,
+        created_at TIMESTAMPTZ NOT NULL,
+        updated_at TIMESTAMPTZ NOT NULL,
+        completed_at TIMESTAMPTZ,
+        version INTEGER NOT NULL DEFAULT 1,
+        definition_version TEXT
+      )
+    `);
+    await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_name 
+      ON ${this.tableName}(name)
+    `);
+    await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_status 
+      ON ${this.tableName}(status)
+    `);
+    await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created 
+      ON ${this.tableName}(created_at DESC)
+    `);
+    this.initialized = true;
+  }
+  /**
+   * Persists the current state of a workflow.
+   *
+   * Uses upsert (INSERT ... ON CONFLICT) to save or update the workflow state.
+   *
+   * @param state - The workflow state to save.
+   * @throws {Error} If the database operation fails.
+   */
+  async save(state) {
+    await this.init();
+    await this.pool.query(
+      `
+      INSERT INTO ${this.tableName} 
+      (id, name, status, input, data, current_step, history, error, created_at, updated_at, completed_at, version, definition_version)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+      ON CONFLICT (id) DO UPDATE SET
+        name = EXCLUDED.name,
+        status = EXCLUDED.status,
+        input = EXCLUDED.input,
+        data = EXCLUDED.data,
+        current_step = EXCLUDED.current_step,
+        history = EXCLUDED.history,
+        error = EXCLUDED.error,
+        updated_at = EXCLUDED.updated_at,
+        completed_at = EXCLUDED.completed_at,
+        version = EXCLUDED.version,
+        definition_version = EXCLUDED.definition_version
+    `,
+      [
+        state.id,
+        state.name,
+        state.status,
+        JSON.stringify(state.input),
+        JSON.stringify(state.data),
+        state.currentStep,
+        JSON.stringify(state.history),
+        _nullishCoalesce(state.error, () => ( null)),
+        state.createdAt,
+        /* @__PURE__ */ new Date(),
+        _nullishCoalesce(state.completedAt, () => ( null)),
+        state.version,
+        _nullishCoalesce(state.definitionVersion, () => ( null))
+      ]
+    );
+  }
+  /**
+   * Loads a workflow state by its ID.
+   *
+   * @param id - The unique identifier of the workflow.
+   * @returns The workflow state, or null if not found.
+   * @throws {Error} If the database query fails.
+   */
+  async load(id) {
+    await this.init();
+    const result = await this.pool.query(`SELECT * FROM ${this.tableName} WHERE id = $1`, [id]);
+    if (result.rows.length === 0) {
+      return null;
+    }
+    return this.rowToState(result.rows[0]);
+  }
+  /**
+   * Lists workflows matching the given filter.
+   *
+   * @param filter - Criteria to filter the results.
+   * @returns A list of matching workflow states.
+   * @throws {Error} If the database query fails.
+   */
+  async list(filter) {
+    await this.init();
+    let query = `SELECT * FROM ${this.tableName} WHERE 1=1`;
+    const params = [];
+    let paramIndex = 1;
+    if (_optionalChain([filter, 'optionalAccess', _118 => _118.name])) {
+      query += ` AND name = $${paramIndex++}`;
+      params.push(filter.name);
+    }
+    if (_optionalChain([filter, 'optionalAccess', _119 => _119.status])) {
+      if (Array.isArray(filter.status)) {
+        const placeholders = filter.status.map(() => `$${paramIndex++}`).join(", ");
+        query += ` AND status IN (${placeholders})`;
+        params.push(...filter.status);
+      } else {
+        query += ` AND status = $${paramIndex++}`;
+        params.push(filter.status);
+      }
+    }
+    if (_optionalChain([filter, 'optionalAccess', _120 => _120.version])) {
+      query += ` AND definition_version = $${paramIndex++}`;
+      params.push(filter.version);
+    }
+    query += " ORDER BY created_at DESC";
+    if (_optionalChain([filter, 'optionalAccess', _121 => _121.limit])) {
+      query += ` LIMIT $${paramIndex++}`;
+      params.push(filter.limit);
+    }
+    if (_optionalChain([filter, 'optionalAccess', _122 => _122.offset])) {
+      query += ` OFFSET $${paramIndex++}`;
+      params.push(filter.offset);
+    }
+    const result = await this.pool.query(query, params);
+    return result.rows.map((row) => this.rowToState(row));
+  }
+  /**
+   * Deletes a workflow state by its ID.
+   *
+   * @param id - The unique identifier of the workflow to delete.
+   * @throws {Error} If the database operation fails.
+   */
+  async delete(id) {
+    await this.init();
+    await this.pool.query(`DELETE FROM ${this.tableName} WHERE id = $1`, [id]);
+  }
+  /**
+   * Closes the database connection pool.
+   *
+   * Should be called when shutting down the application.
+   */
+  async close() {
+    if (this.pool) {
+      await this.pool.end();
+      this.initialized = false;
+    }
+  }
+  /**
+   * Converts a database row to a WorkflowState object.
+   *
+   * @param row - The raw database row.
+   * @returns The parsed workflow state.
+   */
+  rowToState(row) {
+    return {
+      id: row.id,
+      name: row.name,
+      status: row.status,
+      input: typeof row.input === "string" ? JSON.parse(row.input) : row.input,
+      data: typeof row.data === "string" ? JSON.parse(row.data) : row.data,
+      currentStep: row.current_step,
+      history: typeof row.history === "string" ? JSON.parse(row.history) : row.history,
+      error: _nullishCoalesce(row.error, () => ( void 0)),
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at),
+      completedAt: row.completed_at ? new Date(row.completed_at) : void 0,
+      version: row.version,
+      definitionVersion: _nullishCoalesce(row.definition_version, () => ( void 0))
+    };
+  }
+  /**
+   * Returns the underlying pg.Pool instance.
+   *
+   * Useful for testing or advanced database operations.
+   *
+   * @returns The PostgreSQL connection pool.
+   */
+  getPool() {
+    return this.pool;
+  }
+  /**
+   * Optimizes the database table by reclaiming storage and updating statistics.
+   *
+   * Runs VACUUM ANALYZE on the workflow table.
+   *
+   * @throws {Error} If the maintenance operation fails.
+   */
+  async vacuum() {
+    await this.init();
+    await this.pool.query("VACUUM ANALYZE");
+  }
+}, _class7);
+
+// src/trace/JsonFileTraceSink.ts
+var _promises = require('fs/promises');
+var _path = require('path');
+var JsonFileTraceSink = class {
+  
+  
+  /**
+   * Creates a new JSON file trace sink.
+   *
+   * @param options - Configuration options for the sink.
+   */
+  constructor(options) {
+    this.path = options.path;
+    this.ready = this.init(_nullishCoalesce(options.reset, () => ( true)));
+  }
+  /**
+   * Ensures the target directory exists and optionally resets the file.
+   *
+   * @param reset - Whether to truncate the file if it already exists.
+   * @throws {Error} If directory creation or file writing fails.
+   */
+  async init(reset) {
+    await _promises.mkdir.call(void 0, _path.dirname.call(void 0, this.path), { recursive: true });
+    if (reset) {
+      await _promises.writeFile.call(void 0, this.path, "", "utf8");
+    }
+  }
+  /**
+   * Appends a trace event to the file in NDJSON format.
+   *
+   * Waits for initialization to complete before writing.
+   *
+   * @param event - The trace event to record.
+   * @throws {Error} If writing to the file fails.
+   *
+   * @example
+   * ```typescript
+   * await sink.emit({
+   *   type: 'step_start',
+   *   workflowId: 'wf-1',
+   *   timestamp: Date.now(),
+   *   data: { step: 'validate' }
+   * });
+   * ```
+   */
+  async emit(event) {
+    await this.ready;
+    await _promises.appendFile.call(void 0, this.path, `${JSON.stringify(event)}
+`, "utf8");
+  }
+};
+
+// src/core/LockProvider.ts
+var MemoryLockProvider = (_class8 = class {constructor() { _class8.prototype.__init14.call(this); }
+  __init14() {this.locks = /* @__PURE__ */ new Map()}
+  async acquire(resourceId, owner, ttl) {
+    const now = Date.now();
+    const existing = this.locks.get(resourceId);
+    if (existing && existing.expiresAt > now) {
+      if (existing.owner === owner) {
+        existing.expiresAt = now + ttl;
+        return this.createLock(resourceId, owner, existing.expiresAt);
+      }
+      return null;
+    }
+    const expiresAt = now + ttl;
+    this.locks.set(resourceId, { owner, expiresAt });
+    return this.createLock(resourceId, owner, expiresAt);
+  }
+  async refresh(resourceId, owner, ttl) {
+    const now = Date.now();
+    const existing = this.locks.get(resourceId);
+    if (existing && existing.owner === owner && existing.expiresAt > now) {
+      existing.expiresAt = now + ttl;
+      return true;
+    }
+    return false;
+  }
+  async release(resourceId) {
+    this.locks.delete(resourceId);
+  }
+  createLock(id, owner, expiresAt) {
+    return {
+      id,
+      owner,
+      expiresAt,
+      release: () => this.release(id)
+    };
+  }
+}, _class8);
+
+// src/core/RedisLockProvider.ts
+var RELEASE_LOCK_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+else
+  return 0
+end
+`;
+var REFRESH_LOCK_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("pexpire", KEYS[1], ARGV[2])
+else
+  return 0
+end
+`;
+var RedisLockProvider = class {
+  
+  
+  
+  
+  
+  constructor(options) {
+    this.client = options.client;
+    this.keyPrefix = _nullishCoalesce(options.keyPrefix, () => ( "flux:lock:"));
+    this.defaultTtl = _nullishCoalesce(options.defaultTtl, () => ( 3e4));
+    this.retryDelay = _nullishCoalesce(options.retryDelay, () => ( 100));
+    this.maxRetries = _nullishCoalesce(options.maxRetries, () => ( 0));
+  }
+  /**
+   * Attempts to acquire a lock for a specific resource.
+   *
+   * Uses Redis SET with NX (only if not exists) and PX (expire in ms)
+   * for atomic lock acquisition. Supports retry with configurable delay.
+   *
+   * @param resourceId - The unique ID of the resource to lock
+   * @param owner - The identifier of the node/process requesting the lock
+   * @param ttl - Time-to-live for the lock in milliseconds
+   * @returns A Lock object if successful, otherwise null
+   */
+  async acquire(resourceId, owner, ttl) {
+    const key = this.getKey(resourceId);
+    const effectiveTtl = ttl || this.defaultTtl;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const result = await this.client.set(key, owner, {
+        NX: true,
+        PX: effectiveTtl
+      });
+      if (result === "OK") {
+        const expiresAt = Date.now() + effectiveTtl;
+        return this.createLock(resourceId, owner, expiresAt);
+      }
+      const currentOwner = await this.client.get(key);
+      if (currentOwner === owner) {
+        const refreshed = await this.refresh(resourceId, owner, effectiveTtl);
+        if (refreshed) {
+          const expiresAt = Date.now() + effectiveTtl;
+          return this.createLock(resourceId, owner, expiresAt);
+        }
+      }
+      if (attempt < this.maxRetries) {
+        await this.sleep(this.retryDelay);
+      }
+    }
+    return null;
+  }
+  /**
+   * Refreshes an existing lock to extend its lifetime.
+   *
+   * Uses a Lua script to atomically check ownership and extend TTL.
+   *
+   * @param resourceId - The ID of the resource
+   * @param owner - The current owner of the lock
+   * @param ttl - The new time-to-live from the current moment
+   * @returns True if the lock was successfully refreshed
+   */
+  async refresh(resourceId, owner, ttl) {
+    const key = this.getKey(resourceId);
+    const effectiveTtl = ttl || this.defaultTtl;
+    const result = await this.client.eval(REFRESH_LOCK_SCRIPT, [key], [owner, effectiveTtl]);
+    return result === 1;
+  }
+  /**
+   * Forcefully releases a lock, regardless of the owner.
+   *
+   * @param resourceId - The ID of the resource to unlock
+   */
+  async release(resourceId) {
+    const key = this.getKey(resourceId);
+    await this.client.del(key);
+  }
+  /**
+   * Safely releases a lock only if owned by the specified owner.
+   *
+   * Uses a Lua script to atomically check ownership and delete.
+   *
+   * @param resourceId - The ID of the resource to unlock
+   * @param owner - The owner that should release the lock
+   * @returns True if the lock was released, false if not owned
+   */
+  async releaseIfOwned(resourceId, owner) {
+    const key = this.getKey(resourceId);
+    const result = await this.client.eval(RELEASE_LOCK_SCRIPT, [key], [owner]);
+    return result === 1;
+  }
+  /**
+   * Generates the Redis key for a resource.
+   */
+  getKey(resourceId) {
+    return `${this.keyPrefix}${resourceId}`;
+  }
+  /**
+   * Creates a Lock object with a release method.
+   */
+  createLock(id, owner, expiresAt) {
+    return {
+      id,
+      owner,
+      expiresAt,
+      release: async () => {
+        await this.releaseIfOwned(id, owner);
+      }
+    };
+  }
+  /**
+   * Sleeps for the specified duration.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/logger/FluxLogger.ts
+var FluxConsoleLogger = class {
+  
+  /**
+   * Creates a new console logger instance.
+   *
+   * @param prefix - String prepended to every log message for identification.
+   */
+  constructor(prefix = "[Flux]") {
+    this.prefix = prefix;
+  }
+  /**
+   * Logs fine-grained informational events that are most useful to debug an application.
+   *
+   * @param message - The primary log message.
+   * @param args - Additional metadata or objects to include in the log output.
+   */
+  debug(message, ...args) {
+    console.debug(`${this.prefix} ${message}`, ...args);
+  }
+  /**
+   * Logs informational messages that highlight the progress of the application at coarse-grained level.
+   *
+   * @param message - The primary log message.
+   * @param args - Additional metadata or objects to include in the log output.
+   */
+  info(message, ...args) {
+    console.info(`${this.prefix} ${message}`, ...args);
+  }
+  /**
+   * Logs potentially harmful situations that should be noted but don't stop execution.
+   *
+   * @param message - The primary log message.
+   * @param args - Additional metadata or objects to include in the log output.
+   */
+  warn(message, ...args) {
+    console.warn(`${this.prefix} ${message}`, ...args);
+  }
+  /**
+   * Logs error events that might still allow the application to continue running.
+   *
+   * @param message - The primary log message.
+   * @param args - Additional metadata or objects to include in the log output.
+   */
+  error(message, ...args) {
+    console.error(`${this.prefix} ${message}`, ...args);
+  }
+};
+var FluxSilentLogger = class {
+  /** Discards debug logs. */
+  debug() {
+  }
+  /** Discards info logs. */
+  info() {
+  }
+  /** Discards warning logs. */
+  warn() {
+  }
+  /** Discards error logs. */
+  error() {
+  }
+};
+
+// src/orbit/OrbitFlux.ts
+var OrbitFlux = class _OrbitFlux {
+  
+  
+  /**
+   * Initializes a new OrbitFlux instance with the given options.
+   *
+   * @param options - Configuration for the workflow engine integration.
+   */
+  constructor(options = {}) {
+    this.options = {
+      storage: "memory",
+      exposeAs: "flux",
+      defaultRetries: 3,
+      defaultTimeout: 3e4,
+      ...options
+    };
+  }
+  /**
+   * Static factory method to create and configure an OrbitFlux instance.
+   *
+   * @param options - Configuration for the workflow engine integration.
+   * @returns A configured OrbitFlux instance.
+   */
+  static configure(options = {}) {
+    return new _OrbitFlux(options);
+  }
+  /**
+   * Installs the Flux workflow engine into the Gravito core.
+   *
+   * This method resolves the storage adapter, initializes it, configures the engine
+   * with core-integrated logging and hooks, and registers the engine in the IoC container.
+   *
+   * @param core - The PlanetCore instance being booted.
+   * @throws {Error} If storage initialization fails or engine registration conflicts occur.
+   */
+  async install(core) {
+    const { storage, dbPath, exposeAs, defaultRetries, defaultTimeout, logger } = this.options;
+    let storageAdapter;
+    if (typeof storage === "string") {
+      switch (storage) {
+        case "sqlite":
+          storageAdapter = new (0, _chunkYXBEYVGYcjs.BunSQLiteStorage)({ path: dbPath });
+          break;
+        default:
+          storageAdapter = new MemoryStorage();
+      }
+    } else {
+      storageAdapter = storage;
+    }
+    await _optionalChain([storageAdapter, 'access', _123 => _123.init, 'optionalCall', _124 => _124()]);
+    const engineConfig = {
+      storage: storageAdapter,
+      defaultRetries,
+      defaultTimeout,
+      logger: _nullishCoalesce(logger, () => ( {
+        debug: (msg) => core.logger.debug(`[Flux] ${msg}`),
+        info: (msg) => core.logger.info(`[Flux] ${msg}`),
+        warn: (msg) => core.logger.warn(`[Flux] ${msg}`),
+        error: (msg) => core.logger.error(`[Flux] ${msg}`)
+      })),
+      on: {
+        stepStart: (step) => {
+          core.hooks.doAction("flux:step:start", { step });
+        },
+        stepComplete: (step, ctx, result) => {
+          core.hooks.doAction("flux:step:complete", { step, ctx, result });
+        },
+        stepError: (step, ctx, error) => {
+          core.hooks.doAction("flux:step:error", { step, ctx, error });
+        },
+        workflowComplete: (ctx) => {
+          core.hooks.doAction("flux:workflow:complete", { ctx });
+        },
+        workflowError: (ctx, error) => {
+          core.hooks.doAction("flux:workflow:error", { ctx, error });
+        }
+      }
+    };
+    this.engine = new FluxEngine(engineConfig);
+    core.container.instance(exposeAs, this.engine);
+    core.logger.info(
+      `[OrbitFlux] Initialized (Storage: ${typeof storage === "string" ? storage : "custom"})`
+    );
+  }
+  /**
+   * Retrieves the managed FluxEngine instance.
+   *
+   * @returns The FluxEngine instance, or undefined if the orbit has not been installed.
+   */
+  getEngine() {
+    return this.engine;
+  }
+  /**
+   * Performs cleanup operations when the core is shutting down.
+   *
+   * Closes the underlying workflow engine and its storage connections.
+   *
+   * @throws {Error} If the engine fails to close cleanly.
+   */
+  async cleanup() {
+    if (this.engine) {
+      await this.engine.close();
+    }
+  }
+};
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.FluxErrorCode = FluxErrorCode; exports.FluxError = FluxError; exports.workflowNotFound = workflowNotFound; exports.invalidStateTransition = invalidStateTransition; exports.invalidInput = invalidInput; exports.workflowNameMismatch = workflowNameMismatch; exports.workflowDefinitionChanged = workflowDefinitionChanged; exports.workflowNotSuspended = workflowNotSuspended; exports.stepNotFound = stepNotFound; exports.invalidStepIndex = invalidStepIndex; exports.emptyWorkflow = emptyWorkflow; exports.noRecoveryAction = noRecoveryAction; exports.invalidJsonPointer = invalidJsonPointer; exports.invalidPathTraversal = invalidPathTraversal; exports.cannotReplaceRoot = cannotReplaceRoot; exports.cannotRemoveRoot = cannotRemoveRoot; exports.WorkflowBuilder = WorkflowBuilder; exports.createWorkflow = createWorkflow; exports.BatchExecutor = BatchExecutor; exports.ContextManager = ContextManager; exports.StateMachine = StateMachine; exports.CronTrigger = CronTrigger; exports.MemoryStorage = MemoryStorage; exports.StepExecutor = StepExecutor; exports.FluxEngine = FluxEngine; exports.PostgreSQLStorage = PostgreSQLStorage; exports.JsonFileTraceSink = JsonFileTraceSink; exports.MemoryLockProvider = MemoryLockProvider; exports.RedisLockProvider = RedisLockProvider; exports.FluxConsoleLogger = FluxConsoleLogger; exports.FluxSilentLogger = FluxSilentLogger; exports.OrbitFlux = OrbitFlux;
+//# sourceMappingURL=chunk-WAPZDXSX.cjs.map