awaitly 2.0.0 → 3.0.0

package/dist/engine.cjs

@@ -0,0 +1,4501 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/engine-entry.ts
+var engine_entry_exports = {};
+__export(engine_entry_exports, {
+  createEngine: () => createEngine
+});
+module.exports = __toCommonJS(engine_entry_exports);
+
+// src/engine/index.ts
+var import_node_crypto = require("crypto");
+
+// src/slugs.ts
+var AWAITLY_SLUGS = {
+  // --- step-* ---
+  "step-require-id": "step-require-id",
+  "step-no-immediate-execution": "step-no-immediate-execution",
+  "step-require-thunk-for-key": "step-require-thunk-for-key",
+  "step-no-bare-await": "step-no-bare-await",
+  "step-no-try-catch-wrap": "step-no-try-catch-wrap",
+  "step-stable-cache-keys": "step-stable-cache-keys",
+  // --- workflow-* ---
+  "workflow-no-floating": "workflow-no-floating",
+  "workflow-options-position": "workflow-options-position",
+  "workflow-callback-shape": "workflow-callback-shape",
+  "workflow-no-callable-form": "workflow-no-callable-form",
+  "workflow-no-dynamic-import": "workflow-no-dynamic-import",
+  "workflow-prefer-step-if": "workflow-prefer-step-if",
+  "workflow-prefer-step-foreach": "workflow-prefer-step-foreach",
+  // --- result-* ---
+  "result-no-floating": "result-no-floating",
+  "result-require-handling": "result-require-handling",
+  "result-no-double-wrap": "result-no-double-wrap",
+  "result-no-manual-propagation": "result-no-manual-propagation",
+  "result-no-direct-ok-err": "result-no-direct-ok-err",
+  // --- error-* ---
+  "error-check-unexpected-first": "error-check-unexpected-first",
+  "error-access-cause": "error-access-cause",
+  "error-normalize": "error-normalize",
+  "error-no-throw-in-deps": "error-no-throw-in-deps",
+  // --- concurrency-* ---
+  "concurrency-no-promise-all": "concurrency-no-promise-all",
+  "concurrency-no-promise-race": "concurrency-no-promise-race",
+  "concurrency-no-promise-allsettled": "concurrency-no-promise-allsettled",
+  // --- runtime-* ---
+  "runtime-step-timeout": "runtime-step-timeout",
+  "runtime-step-aborted": "runtime-step-aborted",
+  "runtime-retry-exhausted": "runtime-retry-exhausted",
+  "runtime-rate-limit": "runtime-rate-limit",
+  "runtime-circuit-open": "runtime-circuit-open",
+  "runtime-unexpected": "runtime-unexpected",
+  "runtime-resolver-not-found": "runtime-resolver-not-found",
+  "runtime-saga-compensation": "runtime-saga-compensation"
+};
+function slugDocsUrl(slug) {
+  return `https://jagreehal.github.io/awaitly/rules/#${slug}`;
+}
+var ALL_SLUGS = Object.keys(
+  AWAITLY_SLUGS
+);
+
+// src/tagged-error.ts
+var InternalTaggedErrorBase = class extends Error {
+  type;
+  /** @deprecated Use `type`. */
+  _tag;
+};
+function TaggedError(tag, options) {
+  return class extends InternalTaggedErrorBase {
+    type = tag;
+    /** @deprecated Use `type`. */
+    _tag = tag;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(props, errorOptions) {
+      const message = options?.message ? options.message(props ?? {}) : tag;
+      super(message);
+      this.name = tag;
+      if (options?.slug !== void 0) {
+        if (!options.hint) {
+          throw new TypeError(
+            `TaggedError: 'hint' is required when 'slug' is set (slug: "${options.slug}")`
+          );
+        }
+        Object.defineProperty(this, "code", {
+          value: options.slug,
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+        Object.defineProperty(this, "hint", {
+          value: options.hint,
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+        Object.defineProperty(this, "docsUrl", {
+          value: slugDocsUrl(options.slug),
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+      }
+      Object.setPrototypeOf(this, new.target.prototype);
+      if (props && typeof props === "object") {
+        let safeProps;
+        if (options?.slug !== void 0) {
+          const {
+            _tag: _,
+            type: _t,
+            name: _n,
+            message: _m,
+            stack: _s,
+            code: _c,
+            hint: _h,
+            docsUrl: _d,
+            ...rest
+          } = props;
+          safeProps = rest;
+        } else {
+          const {
+            _tag: _,
+            type: _t,
+            name: _n,
+            message: _m,
+            stack: _s,
+            ...rest
+          } = props;
+          safeProps = rest;
+        }
+        const hasUserCause = Object.prototype.hasOwnProperty.call(
+          safeProps,
+          "cause"
+        );
+        const userCause = hasUserCause ? safeProps.cause : void 0;
+        if (hasUserCause) {
+          delete safeProps.cause;
+        }
+        const hasOptionsCause = errorOptions?.cause !== void 0;
+        if (hasUserCause && hasOptionsCause) {
+          throw new TypeError(
+            "TaggedError: cannot provide 'cause' in props when also setting ErrorOptions.cause"
+          );
+        }
+        Object.assign(this, safeProps);
+        if (hasUserCause) {
+          this.cause = userCause;
+        }
+        if (hasOptionsCause) {
+          this.cause = errorOptions?.cause;
+        }
+      } else if (errorOptions?.cause !== void 0) {
+        this.cause = errorOptions.cause;
+      }
+    }
+  };
+}
+Object.defineProperty(TaggedError, Symbol.hasInstance, {
+  value: (instance) => instance instanceof InternalTaggedErrorBase
+});
+((TaggedError2) => {
+  function isError(value) {
+    return value instanceof Error;
+  }
+  TaggedError2.isError = isError;
+  function isTaggedError(value) {
+    return value instanceof InternalTaggedErrorBase;
+  }
+  TaggedError2.isTaggedError = isTaggedError;
+  function match(error, handlers) {
+    const tag = error._tag;
+    const handler = handlers[tag];
+    return handler(
+      error
+    );
+  }
+  TaggedError2.match = match;
+  function matchPartial(error, handlers, otherwise) {
+    const tag = error._tag;
+    const handler = handlers[tag];
+    if (handler) {
+      return handler(
+        error
+      );
+    }
+    return otherwise(error);
+  }
+  TaggedError2.matchPartial = matchPartial;
+})(TaggedError || (TaggedError = {}));
+
+// src/errors.ts
+var UnexpectedError = class extends (/* @__PURE__ */ TaggedError("UnexpectedError", {
+  slug: "runtime-unexpected",
+  hint: "An unexpected exception escaped a step. Inspect cause; consider returning a typed Result instead of throwing.",
+  message: (p) => `UnexpectedError: ${p.cause instanceof Error ? p.cause.message : String(p.cause ?? "unknown")}`
+})) {
+};
+
+// src/result/index.ts
+function ok(value) {
+  return { ok: true, value };
+}
+
+// src/core/bound-steps.ts
+var isDepResultShaped = (value) => typeof value === "object" && value !== null && "ok" in value && typeof value.ok === "boolean" && (value.ok ? "value" in value : "error" in value);
+var bindSteps = (deps, step) => {
+  const steps = {};
+  const invocationCounts = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(deps)) {
+    const dep = deps[key];
+    if (typeof dep !== "function") continue;
+    steps[key] = (...args) => {
+      const count = (invocationCounts.get(key) ?? 0) + 1;
+      invocationCounts.set(key, count);
+      const stepKey = count === 1 ? key : `${key}#${count}`;
+      return step(stepKey, async () => {
+        const value = await dep(...args);
+        return isDepResultShaped(value) ? value : ok(value);
+      });
+    };
+  }
+  return steps;
+};
+
+// src/duration.ts
+function millis(ms) {
+  return { _tag: "Duration", millis: ms };
+}
+function seconds(s) {
+  return { _tag: "Duration", millis: s * 1e3 };
+}
+function minutes(m) {
+  return { _tag: "Duration", millis: m * 60 * 1e3 };
+}
+function hours(h) {
+  return { _tag: "Duration", millis: h * 60 * 60 * 1e3 };
+}
+function days(d) {
+  return { _tag: "Duration", millis: d * 24 * 60 * 60 * 1e3 };
+}
+function toMillis(duration) {
+  return duration.millis;
+}
+function parse(input) {
+  const match = input.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
+  if (!match) return void 0;
+  const value = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "ms":
+      return millis(value);
+    case "s":
+      return seconds(value);
+    case "m":
+      return minutes(value);
+    case "h":
+      return hours(value);
+    case "d":
+      return days(value);
+    default:
+      return void 0;
+  }
+}
+
+// src/core/index.ts
+function parseDurationString(input) {
+  const match = input.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
+  if (!match) return void 0;
+  const value = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  const multipliers = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5 };
+  return { _tag: "Duration", millis: value * (multipliers[unit] ?? 1) };
+}
+function defaultCatchUnexpected(cause) {
+  return new UnexpectedError({ cause });
+}
+function ok2(value) {
+  return { ok: true, value };
+}
+function err(error, options) {
+  const cause = options?.cause;
+  return { ok: false, error, ...cause !== void 0 ? { cause } : {} };
+}
+var isUnexpectedError = (e) => e instanceof UnexpectedError || typeof e === "object" && e !== null && "_tag" in e && e._tag === "UnexpectedError";
+function extractErrorTag(error) {
+  if (error == null) return "unknown";
+  if (typeof error === "string") return error.trim() || "unknown";
+  if (typeof error === "object") {
+    const tagged = error;
+    if (typeof tagged._tag === "string") {
+      const trimmed = tagged._tag.trim();
+      if (trimmed) return trimmed;
+    }
+    if (typeof tagged.tag === "string") {
+      const trimmed = tagged.tag.trim();
+      if (trimmed) return trimmed;
+    }
+    if (typeof tagged.code === "string") {
+      const trimmed = tagged.code.trim();
+      if (trimmed) return trimmed;
+    } else if (typeof tagged.code === "number") {
+      return String(tagged.code);
+    }
+    if (error instanceof Error && error.name) {
+      const trimmed = error.name.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return "unknown";
+}
+function lookupErrorClassification(tag, errorMeta) {
+  if (!errorMeta || !tag) return void 0;
+  return errorMeta[tag];
+}
+function extractStepMetadata(options) {
+  const { intent, domain, owner, tags, stateChanges, emits, calls } = options;
+  if (!intent && !domain && !owner && !tags?.length && !stateChanges?.length && !emits?.length && !calls?.length) {
+    return void 0;
+  }
+  const metadata = {};
+  if (intent) metadata.intent = intent;
+  if (domain) metadata.domain = domain;
+  if (owner) metadata.owner = owner;
+  if (tags?.length) metadata.tags = tags;
+  if (stateChanges?.length) metadata.stateChanges = stateChanges;
+  if (emits?.length) metadata.emits = emits;
+  if (calls?.length) metadata.calls = calls;
+  return metadata;
+}
+function buildStepErrorPayload(error, errorMeta, origin, attempt, cumulativeDurationMs) {
+  const tag = extractErrorTag(error);
+  const classification = lookupErrorClassification(tag, errorMeta);
+  const diagnostics = { tag, origin };
+  if (classification !== void 0) diagnostics.classification = classification;
+  if (attempt !== void 0) diagnostics.attempt = attempt;
+  if (cumulativeDurationMs !== void 0) diagnostics.cumulativeDurationMs = cumulativeDurationMs;
+  return diagnostics;
+}
+var STEP_TIMEOUT_MARKER = /* @__PURE__ */ Symbol.for("step_timeout_marker");
+function isStepTimeoutError(e) {
+  if (typeof e !== "object" || e === null) {
+    return false;
+  }
+  if (e.type === "STEP_TIMEOUT") {
+    return true;
+  }
+  return STEP_TIMEOUT_MARKER in e;
+}
+function getStepTimeoutMeta(e) {
+  if (typeof e !== "object" || e === null) {
+    return void 0;
+  }
+  if (e.type === "STEP_TIMEOUT") {
+    const err2 = e;
+    return {
+      timeoutMs: err2.timeoutMs,
+      stepName: err2.stepName,
+      stepKey: err2.stepKey,
+      attempt: err2.attempt
+    };
+  }
+  if (STEP_TIMEOUT_MARKER in e) {
+    return e[STEP_TIMEOUT_MARKER];
+  }
+  return void 0;
+}
+var EARLY_EXIT_SYMBOL = /* @__PURE__ */ Symbol("early-exit");
+function createEarlyExit(error, meta) {
+  return {
+    [EARLY_EXIT_SYMBOL]: true,
+    error,
+    meta
+  };
+}
+function isEarlyExit(e) {
+  return typeof e === "object" && e !== null && e[EARLY_EXIT_SYMBOL] === true;
+}
+var MAPPER_EXCEPTION_SYMBOL = /* @__PURE__ */ Symbol("mapper-exception");
+function createMapperException(thrown) {
+  return { [MAPPER_EXCEPTION_SYMBOL]: true, thrown };
+}
+function isMapperException(e) {
+  return typeof e === "object" && e !== null && e[MAPPER_EXCEPTION_SYMBOL] === true;
+}
+function calculateRetryDelay(attempt, options) {
+  const { backoff, initialDelay, maxDelay, jitter } = options;
+  let delay;
+  switch (backoff) {
+    case "fixed":
+      delay = initialDelay;
+      break;
+    case "linear":
+      delay = initialDelay * attempt;
+      break;
+    case "exponential":
+      delay = initialDelay * Math.pow(2, attempt - 1);
+      break;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    const jitterAmount = delay * 0.25 * Math.random();
+    delay = delay + jitterAmount;
+  }
+  return Math.floor(delay);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var TIMEOUT_SYMBOL = /* @__PURE__ */ Symbol("timeout");
+var TIMEOUT_OPTION_SYMBOL = /* @__PURE__ */ Symbol("timeout-option");
+function isTimeoutOptionMarker(value) {
+  return typeof value === "object" && value !== null && value[TIMEOUT_OPTION_SYMBOL] === true;
+}
+async function executeWithTimeout(operation, options, stepInfo, externalSignal) {
+  const controller = new AbortController();
+  const behavior = options.onTimeout ?? "error";
+  const createTimeoutError = () => {
+    if (typeof behavior === "function") {
+      return behavior({
+        name: stepInfo.name,
+        key: stepInfo.key,
+        ms: options.ms
+      });
+    }
+    return options.error ?? {
+      type: "STEP_TIMEOUT",
+      stepName: stepInfo.name,
+      stepKey: stepInfo.key,
+      timeoutMs: options.ms,
+      attempt: stepInfo.attempt
+    };
+  };
+  let timeoutId;
+  if (externalSignal?.aborted) {
+    controller.abort(externalSignal.reason);
+  }
+  let externalAbortHandler;
+  if (externalSignal && !externalSignal.aborted) {
+    externalAbortHandler = () => controller.abort(externalSignal.reason);
+    externalSignal.addEventListener("abort", externalAbortHandler, { once: true });
+  }
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      if (behavior !== "disconnect") {
+        controller.abort();
+      }
+      if (behavior === "option") {
+        reject({ [TIMEOUT_OPTION_SYMBOL]: true, ms: options.ms });
+        return;
+      }
+      reject({ [TIMEOUT_SYMBOL]: true, error: createTimeoutError() });
+    }, options.ms);
+  });
+  let operationPromise;
+  if (options.signal) {
+    operationPromise = Promise.resolve(
+      operation(controller.signal)
+    );
+  } else {
+    operationPromise = Promise.resolve(operation());
+  }
+  try {
+    const result = await Promise.race([operationPromise, timeoutPromise]);
+    return result;
+  } catch (error) {
+    if (typeof error === "object" && error !== null && error[TIMEOUT_OPTION_SYMBOL] === true) {
+      throw { [TIMEOUT_OPTION_SYMBOL]: true, ms: options.ms };
+    }
+    if (typeof error === "object" && error !== null && error[TIMEOUT_SYMBOL] === true) {
+      if (behavior === "disconnect") {
+        operationPromise.catch(() => {
+        });
+      }
+      const errorToThrow = error.error;
+      if (typeof errorToThrow === "object" && errorToThrow !== null && errorToThrow.type !== "STEP_TIMEOUT") {
+        const meta = {
+          timeoutMs: options.ms,
+          stepName: stepInfo.name,
+          stepKey: stepInfo.key,
+          attempt: stepInfo.attempt
+        };
+        if (STEP_TIMEOUT_MARKER in errorToThrow) {
+          errorToThrow[STEP_TIMEOUT_MARKER] = meta;
+        } else {
+          Object.defineProperty(errorToThrow, STEP_TIMEOUT_MARKER, {
+            value: meta,
+            enumerable: false,
+            writable: true,
+            configurable: false
+          });
+        }
+      }
+      throw errorToThrow;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+    if (externalAbortHandler && externalSignal) {
+      externalSignal.removeEventListener("abort", externalAbortHandler);
+    }
+  }
+}
+var DEFAULT_RETRY_CONFIG = {
+  backoff: "exponential",
+  initialDelay: 100,
+  maxDelay: 3e4,
+  jitter: true,
+  shouldRetry: () => true,
+  onRetry: () => {
+  }
+};
+async function runFn(fnOrDeps, optionsOrFn, maybeOptions) {
+  if (typeof fnOrDeps !== "function") {
+    const deps = fnOrDeps;
+    const boundFn = optionsOrFn;
+    if (typeof boundFn !== "function") {
+      throw new TypeError(
+        "[awaitly] run(deps, fn) requires a callback as the second argument. Example: run({ getUser }, async (s) => s.getUser(id))"
+      );
+    }
+    const classicRun = runFn;
+    return classicRun(
+      ({ step }) => boundFn(bindSteps(deps, step), { step }),
+      maybeOptions
+    );
+  }
+  const fn = fnOrDeps;
+  const options = optionsOrFn;
+  const {
+    onError,
+    onEvent,
+    catchUnexpected,
+    workflowId: providedWorkflowId,
+    workflowName,
+    context,
+    graph,
+    _workflowSignal
+  } = options && typeof options === "object" ? options : {};
+  const workflowId = providedWorkflowId ?? crypto.randomUUID();
+  const declaredIds = graph ? new Set(
+    Array.isArray(graph) ? graph : graph.states.map((state) => state.semanticId ?? state.id)
+  ) : void 0;
+  const declaredPatterns = declaredIds ? [...declaredIds].filter((id) => id.includes("{")).map(
+    (id) => new RegExp(
+      `^${id.replaceAll(/[.*+?^$()[\]\\|]/g, String.raw`\$&`).replaceAll(/\{[^}]*\}/g, ".+")}$`
+    )
+  ) : void 0;
+  const assertDeclared = (id, kind) => {
+    if (!declaredIds || declaredIds.has(id)) return;
+    if (declaredPatterns?.some((re) => re.test(id))) return;
+    throw new Error(
+      `[awaitly] ${kind} id "${id}" is not in the declared workflow graph. Declared ids: ${[...declaredIds].join(", ")}. Either add it to the graph or remove the graph option.`
+    );
+  };
+  const effectiveCatchUnexpected = catchUnexpected ?? defaultCatchUnexpected;
+  const activeScopeStack = [];
+  let stepIdCounter = 0;
+  const generateStepId = (stepKey) => {
+    return stepKey ?? `step_${++stepIdCounter}`;
+  };
+  const emitEvent = (event) => {
+    const eventWithContext = event.context !== void 0 || context === void 0 ? event : { ...event, context };
+    const eventWithName = workflowName !== void 0 && eventWithContext.workflowName === void 0 ? { ...eventWithContext, workflowName } : eventWithContext;
+    if (eventWithName.type === "step_success") {
+      const stepId = eventWithName.stepId;
+      for (let i = activeScopeStack.length - 1; i >= 0; i--) {
+        const scope = activeScopeStack[i];
+        if (scope.type === "race" && !scope.winnerId) {
+          scope.winnerId = stepId;
+          break;
+        }
+      }
+    }
+    onEvent?.(eventWithName, context);
+  };
+  const earlyExit = createEarlyExit;
+  const isEarlyExitE = (e) => isEarlyExit(e);
+  const wrapForStep = (error, _meta) => {
+    return error;
+  };
+  const isResultLike = (value) => {
+    if (typeof value === "function") return false;
+    if (value && typeof value === "object" && "ok" in value) return true;
+    if (value && typeof value === "object" && "then" in value && typeof value.then === "function") return true;
+    return false;
+  };
+  try {
+    let normalizeParallelOperations2 = function(rawOperations) {
+      const out = {};
+      for (const [key, value2] of Object.entries(rawOperations)) {
+        if (typeof value2 === "function") {
+          out[key] = value2;
+        } else if (value2 && typeof value2 === "object" && "fn" in value2) {
+          out[key] = value2.fn;
+        } else {
+          throw new TypeError(`step.all: operation "${key}" must be a function or { fn, errors? } object`);
+        }
+      }
+      return out;
+    }, executeParallelArray2 = function(name, operation) {
+      const scopeId = `scope_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      return (async () => {
+        const startTime = performance.now();
+        let scopeEnded = false;
+        activeScopeStack.push({ scopeId, type: "parallel" });
+        const emitScopeEnd = () => {
+          if (scopeEnded) return;
+          scopeEnded = true;
+          const idx = activeScopeStack.findIndex((s) => s.scopeId === scopeId);
+          if (idx !== -1) activeScopeStack.splice(idx, 1);
+          emitEvent({
+            type: "scope_end",
+            workflowId,
+            scopeId,
+            ts: Date.now(),
+            durationMs: performance.now() - startTime
+          });
+        };
+        emitEvent({
+          type: "scope_start",
+          workflowId,
+          scopeId,
+          scopeType: "parallel",
+          name,
+          ts: Date.now()
+        });
+        try {
+          const result = await operation();
+          emitScopeEnd();
+          if (!result.ok) {
+            onError?.(result.error, name, context);
+            throw earlyExit(result.error, {
+              origin: "result",
+              resultCause: result.cause
+            });
+          }
+          return result.value;
+        } catch (error) {
+          emitScopeEnd();
+          throw error;
+        }
+      })();
+    }, executeParallelNamed2 = function(operations, options2) {
+      const keys = Object.keys(operations);
+      const name = options2.name ?? `Parallel(${keys.join(", ")})`;
+      const scopeId = `scope_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      return (async () => {
+        const startTime = performance.now();
+        let scopeEnded = false;
+        activeScopeStack.push({ scopeId, type: "parallel" });
+        const emitScopeEnd = () => {
+          if (scopeEnded) return;
+          scopeEnded = true;
+          const idx = activeScopeStack.findIndex((s) => s.scopeId === scopeId);
+          if (idx !== -1) activeScopeStack.splice(idx, 1);
+          emitEvent({
+            type: "scope_end",
+            workflowId,
+            scopeId,
+            ts: Date.now(),
+            durationMs: performance.now() - startTime
+          });
+        };
+        emitEvent({
+          type: "scope_start",
+          workflowId,
+          scopeId,
+          scopeType: "parallel",
+          name,
+          ts: Date.now()
+        });
+        try {
+          const results = await new Promise((resolve) => {
+            if (keys.length === 0) {
+              resolve([]);
+              return;
+            }
+            let settled = false;
+            let pendingCount = keys.length;
+            const resultArray = new Array(keys.length);
+            for (let i = 0; i < keys.length; i++) {
+              const key = keys[i];
+              const index = i;
+              Promise.resolve(operations[key]()).catch((reason) => err(
+                { type: "PROMISE_REJECTED", cause: reason },
+                { cause: { type: "PROMISE_REJECTION", reason } }
+              )).then((result) => {
+                if (settled) return;
+                if (!result.ok) {
+                  settled = true;
+                  resolve([{ key, result }]);
+                  return;
+                }
+                resultArray[index] = { key, result };
+                pendingCount--;
+                if (pendingCount === 0) {
+                  resolve(resultArray);
+                }
+              });
+            }
+          });
+          emitScopeEnd();
+          const output = {};
+          for (const { key, result } of results) {
+            if (!result.ok) {
+              onError?.(result.error, key, context);
+              throw earlyExit(result.error, {
+                origin: "result",
+                resultCause: result.cause
+              });
+            }
+            output[key] = result.value;
+          }
+          return output;
+        } catch (error) {
+          emitScopeEnd();
+          throw error;
+        }
+      })();
+    };
+    var normalizeParallelOperations = normalizeParallelOperations2, executeParallelArray = executeParallelArray2, executeParallelNamed = executeParallelNamed2;
+    const stepFn = (id, operationOrResult, stepOptions) => {
+      return (async () => {
+        if (typeof id !== "string" || id.length === 0) {
+          throw new Error(
+            '[awaitly] step() requires an explicit string ID as the first argument. Example: step("fetchUser", () => fetchUser(id))'
+          );
+        }
+        assertDeclared(id, "step");
+        const parsedOptions = stepOptions ?? {};
+        const stepMetadata = extractStepMetadata(parsedOptions);
+        const stepName = id;
+        const stepKey = parsedOptions.key ?? id;
+        const explicitKey = parsedOptions.key ?? id;
+        const { description: stepDescription, retry: retryConfig, timeout: timeoutConfig } = parsedOptions;
+        const stepId = generateStepId(stepKey);
+        const hasEventListeners = onEvent;
+        const overallStartTime = hasEventListeners ? performance.now() : 0;
+        const isDirectResult = isResultLike(operationOrResult);
+        const operation = isDirectResult ? () => operationOrResult : operationOrResult;
+        const maxAttempts = Math.max(1, retryConfig?.attempts ?? 1);
+        const effectiveRetry = {
+          attempts: maxAttempts,
+          backoff: retryConfig?.backoff ?? DEFAULT_RETRY_CONFIG.backoff,
+          initialDelay: retryConfig?.initialDelay ?? DEFAULT_RETRY_CONFIG.initialDelay,
+          maxDelay: retryConfig?.maxDelay ?? DEFAULT_RETRY_CONFIG.maxDelay,
+          jitter: retryConfig?.jitter ?? DEFAULT_RETRY_CONFIG.jitter,
+          shouldRetry: retryConfig?.shouldRetry ?? DEFAULT_RETRY_CONFIG.shouldRetry,
+          onRetry: retryConfig?.onRetry ?? DEFAULT_RETRY_CONFIG.onRetry
+        };
+        if (onEvent) {
+          emitEvent({
+            type: "step_start",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            description: stepDescription,
+            ts: Date.now(),
+            ...stepMetadata && { metadata: stepMetadata }
+          });
+        }
+        let lastResult;
+        for (let attempt = 1; attempt <= effectiveRetry.attempts; attempt++) {
+          const attemptStartTime = hasEventListeners ? performance.now() : 0;
+          try {
+            let result;
+            if (timeoutConfig) {
+              result = await executeWithTimeout(
+                operation,
+                timeoutConfig,
+                { name: stepName, key: stepKey, attempt },
+                _workflowSignal
+              );
+            } else {
+              result = await operation();
+            }
+            if (result.ok) {
+              const durationMs = performance.now() - overallStartTime;
+              emitEvent({
+                type: "step_success",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                description: stepDescription,
+                ts: Date.now(),
+                durationMs,
+                ...stepMetadata && { metadata: stepMetadata }
+              });
+              if (explicitKey) {
+                emitEvent({
+                  type: "step_complete",
+                  workflowId,
+                  stepKey: explicitKey,
+                  name: stepName,
+                  description: stepDescription,
+                  ts: Date.now(),
+                  durationMs,
+                  result,
+                  ...stepMetadata && { metadata: stepMetadata }
+                });
+              }
+              return result.value;
+            }
+            lastResult = result;
+            if (attempt < effectiveRetry.attempts && effectiveRetry.shouldRetry(result.error, attempt)) {
+              const delay = calculateRetryDelay(attempt, effectiveRetry);
+              emitEvent({
+                type: "step_retry",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                attempt: attempt + 1,
+                maxAttempts: effectiveRetry.attempts,
+                delayMs: delay,
+                error: result.error,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(result.error, parsedOptions.errorMeta, "result", attempt, performance.now() - overallStartTime)
+              });
+              effectiveRetry.onRetry(result.error, attempt, delay);
+              await sleep(delay);
+              continue;
+            }
+            if (effectiveRetry.attempts > 1) {
+              emitEvent({
+                type: "step_retries_exhausted",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: performance.now() - overallStartTime,
+                attempts: attempt,
+                lastError: result.error,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(result.error, parsedOptions.errorMeta, "result", attempt, performance.now() - overallStartTime)
+              });
+            }
+            break;
+          } catch (thrown) {
+            const durationMs = performance.now() - attemptStartTime;
+            if (isTimeoutOptionMarker(thrown)) {
+              const timeoutMs = thrown.ms;
+              emitEvent({
+                type: "step_timeout",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                timeoutMs,
+                attempt,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "timeout", attempt)
+              });
+              emitEvent({
+                type: "step_success",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                description: stepDescription,
+                ts: Date.now(),
+                durationMs: performance.now() - overallStartTime,
+                ...stepMetadata && { metadata: stepMetadata }
+              });
+              if (explicitKey) {
+                emitEvent({
+                  type: "step_complete",
+                  workflowId,
+                  stepKey: explicitKey,
+                  name: stepName,
+                  description: stepDescription,
+                  ts: Date.now(),
+                  durationMs: performance.now() - overallStartTime,
+                  result: ok2(void 0),
+                  ...stepMetadata && { metadata: stepMetadata }
+                });
+              }
+              return void 0;
+            }
+            if (isEarlyExitE(thrown)) {
+              emitEvent({
+                type: "step_aborted",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                description: stepDescription,
+                ts: Date.now(),
+                durationMs,
+                ...stepMetadata && { metadata: stepMetadata }
+              });
+              throw thrown;
+            }
+            if (isStepTimeoutError(thrown)) {
+              const timeoutMeta = getStepTimeoutMeta(thrown);
+              const timeoutMs = timeoutConfig?.ms ?? timeoutMeta?.timeoutMs ?? 0;
+              emitEvent({
+                type: "step_timeout",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                timeoutMs,
+                attempt,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "timeout", attempt)
+              });
+              if (attempt < effectiveRetry.attempts && effectiveRetry.shouldRetry(thrown, attempt)) {
+                const delay = calculateRetryDelay(attempt, effectiveRetry);
+                emitEvent({
+                  type: "step_retry",
+                  workflowId,
+                  stepId,
+                  stepKey,
+                  name: stepName,
+                  ts: Date.now(),
+                  attempt: attempt + 1,
+                  maxAttempts: effectiveRetry.attempts,
+                  delayMs: delay,
+                  error: thrown,
+                  ...stepMetadata && { metadata: stepMetadata },
+                  diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "timeout", attempt, performance.now() - overallStartTime)
+                });
+                effectiveRetry.onRetry(thrown, attempt, delay);
+                await sleep(delay);
+                continue;
+              }
+              if (effectiveRetry.attempts > 1) {
+                emitEvent({
+                  type: "step_retries_exhausted",
+                  workflowId,
+                  stepId,
+                  stepKey,
+                  name: stepName,
+                  ts: Date.now(),
+                  durationMs: performance.now() - overallStartTime,
+                  attempts: attempt,
+                  lastError: thrown,
+                  ...stepMetadata && { metadata: stepMetadata },
+                  diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "timeout", attempt, performance.now() - overallStartTime)
+                });
+              }
+              const totalDurationMs3 = performance.now() - overallStartTime;
+              emitEvent({
+                type: "step_error",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                description: stepDescription,
+                ts: Date.now(),
+                durationMs: totalDurationMs3,
+                error: thrown,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "timeout", attempt, totalDurationMs3)
+              });
+              if (explicitKey) {
+                emitEvent({
+                  type: "step_complete",
+                  workflowId,
+                  stepKey: explicitKey,
+                  name: stepName,
+                  description: stepDescription,
+                  ts: Date.now(),
+                  durationMs: totalDurationMs3,
+                  result: err(thrown, { cause: thrown }),
+                  meta: { origin: "throw", thrown },
+                  ...stepMetadata && { metadata: stepMetadata }
+                });
+              }
+              onError?.(thrown, stepName, context);
+              throw earlyExit(thrown, { origin: "throw", thrown });
+            }
+            if (attempt < effectiveRetry.attempts && effectiveRetry.shouldRetry(thrown, attempt)) {
+              const delay = calculateRetryDelay(attempt, effectiveRetry);
+              emitEvent({
+                type: "step_retry",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                attempt: attempt + 1,
+                maxAttempts: effectiveRetry.attempts,
+                delayMs: delay,
+                error: thrown,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "throw", attempt, performance.now() - overallStartTime)
+              });
+              effectiveRetry.onRetry(thrown, attempt, delay);
+              await sleep(delay);
+              continue;
+            }
+            if (effectiveRetry.attempts > 1 && !isStepTimeoutError(thrown)) {
+              emitEvent({
+                type: "step_retries_exhausted",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: performance.now() - overallStartTime,
+                attempts: attempt,
+                lastError: thrown,
+                ...stepMetadata && { metadata: stepMetadata },
+                diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "throw", attempt, performance.now() - overallStartTime)
+              });
+            }
+            const totalDurationMs2 = performance.now() - overallStartTime;
+            let mappedError;
+            try {
+              mappedError = effectiveCatchUnexpected(thrown);
+            } catch (mapperError) {
+              throw createMapperException(mapperError);
+            }
+            emitEvent({
+              type: "step_error",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              description: stepDescription,
+              ts: Date.now(),
+              durationMs: totalDurationMs2,
+              error: mappedError,
+              ...stepMetadata && { metadata: stepMetadata },
+              diagnostics: buildStepErrorPayload(thrown, parsedOptions.errorMeta, "throw", attempt, totalDurationMs2)
+            });
+            if (explicitKey) {
+              emitEvent({
+                type: "step_complete",
+                workflowId,
+                stepKey: explicitKey,
+                name: stepName,
+                description: stepDescription,
+                ts: Date.now(),
+                durationMs: totalDurationMs2,
+                result: err(mappedError, { cause: thrown }),
+                meta: { origin: "throw", thrown },
+                ...stepMetadata && { metadata: stepMetadata }
+              });
+            }
+            onError?.(mappedError, stepName, context);
+            throw earlyExit(mappedError, { origin: "throw", thrown });
+          }
+        }
+        const errorResult = lastResult;
+        const totalDurationMs = performance.now() - overallStartTime;
+        const wrappedError = wrapForStep(errorResult.error, {
+          origin: "result",
+          resultCause: errorResult.cause
+        });
+        emitEvent({
+          type: "step_error",
+          workflowId,
+          stepId,
+          stepKey,
+          name: stepName,
+          description: stepDescription,
+          ts: Date.now(),
+          durationMs: totalDurationMs,
+          error: wrappedError,
+          ...stepMetadata && { metadata: stepMetadata },
+          diagnostics: buildStepErrorPayload(errorResult.error, parsedOptions.errorMeta, "result", effectiveRetry.attempts, totalDurationMs)
+        });
+        if (explicitKey) {
+          emitEvent({
+            type: "step_complete",
+            workflowId,
+            stepKey: explicitKey,
+            name: stepName,
+            description: stepDescription,
+            ts: Date.now(),
+            durationMs: totalDurationMs,
+            result: errorResult,
+            meta: { origin: "result", resultCause: errorResult.cause },
+            ...stepMetadata && { metadata: stepMetadata }
+          });
+        }
+        onError?.(wrappedError, stepName, context);
+        throw earlyExit(wrappedError, {
+          origin: "result",
+          resultCause: errorResult.cause
+        });
+      })();
+    };
+    stepFn.try = (id, operation, opts) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.try() requires an explicit string ID as the first argument. Example: step.try("parse", () => JSON.parse(str), { error: "PARSE_ERROR" })'
+        );
+      }
+      assertDeclared(id, "step");
+      const mapToError = "error" in opts ? () => opts.error : opts.onError;
+      if (opts.retry || opts.timeout) {
+        return stepFn.retry(
+          id,
+          async () => {
+            try {
+              return ok2(await operation());
+            } catch (cause) {
+              return err(mapToError(cause), { cause });
+            }
+          },
+          {
+            attempts: opts.retry?.attempts ?? 1,
+            ...opts.retry ?? {},
+            key: opts.key,
+            timeout: opts.timeout
+          }
+        );
+      }
+      const stepKey = opts.key ?? id;
+      const stepName = id;
+      const stepId = id;
+      const hasEventListeners = onEvent;
+      return (async () => {
+        const startTime = hasEventListeners ? performance.now() : 0;
+        if (onEvent) {
+          emitEvent({
+            type: "step_start",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now()
+          });
+        }
+        try {
+          const value2 = await operation();
+          const durationMs = performance.now() - startTime;
+          emitEvent({
+            type: "step_success",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs,
+              result: ok2(value2)
+            });
+          }
+          return value2;
+        } catch (error) {
+          const mapped = mapToError(error);
+          const durationMs = performance.now() - startTime;
+          const wrappedError = wrapForStep(mapped, { origin: "throw", thrown: error });
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs,
+            error: wrappedError
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs,
+              result: err(mapped, { cause: error }),
+              meta: { origin: "throw", thrown: error }
+            });
+          }
+          onError?.(wrappedError, stepName, context);
+          throw earlyExit(wrappedError, { origin: "throw", thrown: error });
+        }
+      })();
+    };
+    stepFn.fromResult = (id, operation, opts) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.fromResult() requires an explicit string ID as the first argument. Example: step.fromResult("callProvider", () => callProvider(input), { onError: (e) => ({ type: "FAILED" }) })'
+        );
+      }
+      assertDeclared(id, "step");
+      const stepKey = opts.key ?? id;
+      const stepName = id;
+      const stepId = id;
+      const mapToError = "error" in opts ? () => opts.error : opts.onError;
+      const hasEventListeners = onEvent;
+      return (async () => {
+        const startTime = hasEventListeners ? performance.now() : 0;
+        if (onEvent) {
+          emitEvent({
+            type: "step_start",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now()
+          });
+        }
+        const result = await operation();
+        if (result.ok) {
+          const durationMs = performance.now() - startTime;
+          emitEvent({
+            type: "step_success",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs,
+              result: ok2(result.value)
+            });
+          }
+          return result.value;
+        } else {
+          const mapped = mapToError(result.error);
+          const durationMs = performance.now() - startTime;
+          const wrappedError = wrapForStep(mapped, {
+            origin: "result",
+            resultCause: result.error
+          });
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs,
+            error: wrappedError
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs,
+              result: err(mapped, { cause: result.error }),
+              meta: { origin: "result", resultCause: result.error }
+            });
+          }
+          onError?.(wrappedError, stepName, context);
+          throw earlyExit(wrappedError, {
+            origin: "result",
+            resultCause: result.error
+          });
+        }
+      })();
+    };
+    stepFn.fromNullable = (id, operation, onNull, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.fromNullable() requires an explicit string ID as the first argument. Example: step.fromNullable("getUser", () => db.find(id), () => ({ type: "NOT_FOUND" }))'
+        );
+      }
+      return stepFn(
+        id,
+        async () => {
+          const value2 = await operation();
+          return value2 != null ? ok2(value2) : err(onNull());
+        },
+        options2
+      );
+    };
+    stepFn.retry = (id, operation, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.retry() requires an explicit string ID as the first argument. Example: step.retry("fetchData", () => fetchData(), { attempts: 3 })'
+        );
+      }
+      return stepFn(id, operation, {
+        key: options2.key ?? id,
+        retry: {
+          attempts: options2.attempts,
+          backoff: options2.backoff,
+          initialDelay: options2.initialDelay,
+          maxDelay: options2.maxDelay,
+          jitter: options2.jitter,
+          shouldRetry: options2.shouldRetry,
+          onRetry: options2.onRetry
+        },
+        timeout: options2.timeout
+      });
+    };
+    stepFn.withTimeout = (id, operation, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.withTimeout() requires an explicit string ID as the first argument. Example: step.withTimeout("slowOp", () => slowOp(), { ms: 5000 })'
+        );
+      }
+      return stepFn(
+        id,
+        operation,
+        {
+          key: options2.key ?? id,
+          timeout: options2
+        }
+      );
+    };
+    stepFn.sleep = (id, duration, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.sleep() requires an explicit string ID as the first argument. Example: step.sleep("delay", "5s")'
+        );
+      }
+      const d = typeof duration === "string" ? parseDurationString(duration) : duration;
+      if (!d) {
+        throw new Error(`step.sleep: invalid duration '${duration}'`);
+      }
+      const ms = d.millis;
+      const userSignal = options2?.signal;
+      return stepFn(
+        id,
+        async () => {
+          if (_workflowSignal?.aborted || userSignal?.aborted) {
+            const e = new Error("Sleep aborted");
+            e.name = "AbortError";
+            throw e;
+          }
+          return new Promise((resolve, reject) => {
+            const state = { timeoutId: void 0 };
+            const onAbort = () => {
+              if (state.timeoutId) clearTimeout(state.timeoutId);
+              const e = new Error("Sleep aborted");
+              e.name = "AbortError";
+              reject(e);
+            };
+            _workflowSignal?.addEventListener("abort", onAbort, { once: true });
+            userSignal?.addEventListener("abort", onAbort, { once: true });
+            state.timeoutId = setTimeout(() => {
+              _workflowSignal?.removeEventListener("abort", onAbort);
+              userSignal?.removeEventListener("abort", onAbort);
+              resolve(ok2(void 0));
+            }, ms);
+          });
+        },
+        {
+          key: options2?.key ?? id,
+          description: options2?.description
+        }
+      );
+    };
+    stepFn.all = ((...args) => {
+      if (typeof args[0] !== "string") {
+        throw new TypeError(
+          "step.all(name, ...): first argument must be a string (step name). Example: step.all('Fetch data', { user: () => fetchUser(), posts: () => fetchPosts() })"
+        );
+      }
+      const name = args[0];
+      const second = args[1];
+      if (typeof second === "function") {
+        return executeParallelArray2(name, second);
+      }
+      if (second && typeof second === "object" && !Array.isArray(second)) {
+        const rawOperations = second;
+        const normalizedOperations = normalizeParallelOperations2(rawOperations);
+        return executeParallelNamed2(normalizedOperations, { name });
+      }
+      throw new TypeError(
+        "step.all(name, ...): second argument must be a function (array form) or an object of operations (object form)."
+      );
+    });
+    stepFn.race = (name, operation) => {
+      const scopeId = `scope_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      return (async () => {
+        const startTime = performance.now();
+        let scopeEnded = false;
+        const scopeEntry = { scopeId, type: "race", winnerId: void 0 };
+        activeScopeStack.push(scopeEntry);
+        const emitScopeEnd = () => {
+          if (scopeEnded) return;
+          scopeEnded = true;
+          const idx = activeScopeStack.findIndex((s) => s.scopeId === scopeId);
+          if (idx !== -1) activeScopeStack.splice(idx, 1);
+          emitEvent({
+            type: "scope_end",
+            workflowId,
+            scopeId,
+            ts: Date.now(),
+            durationMs: performance.now() - startTime,
+            winnerId: scopeEntry.winnerId
+          });
+        };
+        emitEvent({
+          type: "scope_start",
+          workflowId,
+          scopeId,
+          scopeType: "race",
+          name,
+          ts: Date.now()
+        });
+        try {
+          const result = await operation();
+          emitScopeEnd();
+          if (!result.ok) {
+            onError?.(result.error, name, context);
+            throw earlyExit(result.error, {
+              origin: "result",
+              resultCause: result.cause
+            });
+          }
+          return result.value;
+        } catch (error) {
+          emitScopeEnd();
+          throw error;
+        }
+      })();
+    };
+    stepFn.if = (id, conditionLabel, condition) => {
+      assertDeclared(id, "decision");
+      const value2 = condition();
+      emitEvent({
+        type: "decision",
+        workflowId,
+        decisionId: id,
+        label: conditionLabel,
+        branch: value2 ? "then" : "else",
+        value: value2,
+        ts: Date.now()
+      });
+      return value2;
+    };
+    stepFn.label = stepFn.if;
+    stepFn.branch = async (id, options2) => {
+      const { condition, then: thenFn, else: elseFn } = options2;
+      assertDeclared(id, "decision");
+      const conditionResult = condition();
+      const branch = conditionResult ? "then" : "else";
+      const startTime = performance.now();
+      emitEvent({
+        type: "decision",
+        workflowId,
+        decisionId: id,
+        label: options2.conditionLabel,
+        branch,
+        value: conditionResult,
+        phase: "start",
+        ts: Date.now()
+      });
+      const emitEnd = () => {
+        emitEvent({
+          type: "decision",
+          workflowId,
+          decisionId: id,
+          label: options2.conditionLabel,
+          branch,
+          value: conditionResult,
+          phase: "end",
+          durationMs: performance.now() - startTime,
+          ts: Date.now()
+        });
+      };
+      try {
+        if (conditionResult) {
+          return await thenFn();
+        } else if (elseFn) {
+          return await elseFn();
+        }
+        return void 0;
+      } finally {
+        emitEnd();
+      }
+    };
+    stepFn.arm = (fn2, errors) => {
+      return { fn: fn2, errors };
+    };
+    stepFn.forEach = async (_id, items, options2) => {
+      const results = [];
+      const maxIterations = options2.maxIterations;
+      let index = 0;
+      const isRunForm = "run" in options2;
+      const asyncItems = Symbol.asyncIterator in items ? items : (async function* () {
+        yield* items;
+      })();
+      for await (const item of asyncItems) {
+        if (maxIterations !== void 0 && index >= maxIterations) {
+          break;
+        }
+        let result;
+        if (isRunForm) {
+          const runOptions = options2;
+          result = await runOptions.run(item, index);
+        } else {
+          const itemOptions = options2;
+          result = await itemOptions.item.handler(item, index, stepFn);
+        }
+        results.push(result);
+        index++;
+      }
+      return results;
+    };
+    stepFn.item = (handler) => {
+      return {
+        __forEachItemHandler: true,
+        handler
+      };
+    };
+    stepFn.dep = (_name, fn2) => {
+      return fn2;
+    };
+    stepFn.workflow = (id, getter, options2) => {
+      return stepFn(id, getter, options2);
+    };
+    stepFn.map = async (id, items, mapper, options2) => {
+      const concurrency = options2?.concurrency ?? items.length;
+      return stepFn(
+        id,
+        () => {
+          if (concurrency >= items.length) {
+            return allAsync(items.map((item, index) => mapper(item, index)));
+          } else {
+            return (async () => {
+              const results = [];
+              for (let i = 0; i < items.length; i += concurrency) {
+                const batch = items.slice(i, i + concurrency);
+                const batchResult = await allAsync(
+                  batch.map((item, batchIndex) => mapper(item, i + batchIndex))
+                );
+                if (!batchResult.ok) {
+                  return batchResult;
+                }
+                results.push(...batchResult.value);
+              }
+              return ok2(results);
+            })();
+          }
+        },
+        { key: options2?.key }
+      );
+    };
+    stepFn.withFallback = (id, operation, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.withFallback() requires an explicit string ID as the first argument. Example: step.withFallback("getUser", () => fetchUser(id), { fallback: () => fetchFromCache(id) })'
+        );
+      }
+      assertDeclared(id, "step");
+      const stepKey = options2.key ?? id;
+      const stepName = id;
+      const stepId = generateStepId(stepKey);
+      const hasEventListeners = onEvent;
+      return (async () => {
+        const startTime = hasEventListeners ? performance.now() : 0;
+        if (onEvent) {
+          emitEvent({
+            type: "step_start",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now()
+          });
+        }
+        let primaryResult;
+        try {
+          primaryResult = await operation();
+        } catch (thrown) {
+          if (isEarlyExitE(thrown)) {
+            emitEvent({
+              type: "step_aborted",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: performance.now() - startTime
+            });
+            throw thrown;
+          }
+          let mappedError;
+          try {
+            mappedError = effectiveCatchUnexpected(thrown);
+          } catch (mapperError) {
+            throw createMapperException(mapperError);
+          }
+          if (options2.on !== void 0 && options2.on !== mappedError) {
+            const durationMs2 = performance.now() - startTime;
+            emitEvent({
+              type: "step_error",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              error: mappedError
+            });
+            if (stepKey) {
+              emitEvent({
+                type: "step_complete",
+                workflowId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: durationMs2,
+                result: err(mappedError, { cause: thrown }),
+                meta: { origin: "throw", thrown }
+              });
+            }
+            onError?.(mappedError, stepName, context);
+            throw earlyExit(mappedError, { origin: "throw", thrown });
+          }
+          let fallbackResultFromThrow;
+          try {
+            fallbackResultFromThrow = await options2.fallback();
+          } catch (fallbackThrown) {
+            if (isEarlyExitE(fallbackThrown)) {
+              emitEvent({
+                type: "step_aborted",
+                workflowId,
+                stepId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: performance.now() - startTime
+              });
+              throw fallbackThrown;
+            }
+            let fallbackMappedError;
+            try {
+              fallbackMappedError = effectiveCatchUnexpected(fallbackThrown);
+            } catch (mapperError) {
+              throw createMapperException(mapperError);
+            }
+            const durationMs2 = performance.now() - startTime;
+            emitEvent({
+              type: "step_error",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              error: fallbackMappedError
+            });
+            if (stepKey) {
+              emitEvent({
+                type: "step_complete",
+                workflowId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: durationMs2,
+                result: err(fallbackMappedError, { cause: fallbackThrown }),
+                meta: { origin: "throw", thrown: fallbackThrown }
+              });
+            }
+            onError?.(fallbackMappedError, stepName, context);
+            throw earlyExit(fallbackMappedError, { origin: "throw", thrown: fallbackThrown });
+          }
+          if (fallbackResultFromThrow.ok) {
+            const durationMs2 = performance.now() - startTime;
+            emitEvent({
+              type: "step_success",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2
+            });
+            if (stepKey) {
+              emitEvent({
+                type: "step_complete",
+                workflowId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: durationMs2,
+                result: fallbackResultFromThrow,
+                meta: { origin: "fallback", fallbackUsed: true, fallbackReason: String(mappedError) }
+              });
+            }
+            return fallbackResultFromThrow.value;
+          } else {
+            const durationMs2 = performance.now() - startTime;
+            const wrappedError2 = wrapForStep(fallbackResultFromThrow.error, {
+              origin: "result",
+              resultCause: fallbackResultFromThrow.cause
+            });
+            emitEvent({
+              type: "step_error",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              error: wrappedError2
+            });
+            if (stepKey) {
+              emitEvent({
+                type: "step_complete",
+                workflowId,
+                stepKey,
+                name: stepName,
+                ts: Date.now(),
+                durationMs: durationMs2,
+                result: fallbackResultFromThrow,
+                meta: { origin: "result", resultCause: fallbackResultFromThrow.cause }
+              });
+            }
+            onError?.(wrappedError2, stepName, context);
+            throw earlyExit(wrappedError2, {
+              origin: "result",
+              resultCause: fallbackResultFromThrow.cause
+            });
+          }
+        }
+        if (primaryResult.ok) {
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_success",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: primaryResult
+            });
+          }
+          return primaryResult.value;
+        }
+        const primaryError = primaryResult.error;
+        if (options2.on !== void 0 && options2.on !== primaryError) {
+          const durationMs2 = performance.now() - startTime;
+          const wrappedError2 = wrapForStep(primaryError, {
+            origin: "result",
+            resultCause: primaryResult.cause
+          });
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2,
+            error: wrappedError2
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: primaryResult,
+              meta: { origin: "result", resultCause: primaryResult.cause }
+            });
+          }
+          onError?.(wrappedError2, stepName, context);
+          throw earlyExit(wrappedError2, {
+            origin: "result",
+            resultCause: primaryResult.cause
+          });
+        }
+        let fallbackResult;
+        try {
+          fallbackResult = await options2.fallback();
+        } catch (thrown) {
+          if (isEarlyExitE(thrown)) {
+            emitEvent({
+              type: "step_aborted",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: performance.now() - startTime
+            });
+            throw thrown;
+          }
+          let mappedError;
+          try {
+            mappedError = effectiveCatchUnexpected(thrown);
+          } catch (mapperError) {
+            throw createMapperException(mapperError);
+          }
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2,
+            error: mappedError
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: err(mappedError, { cause: thrown }),
+              meta: { origin: "throw", thrown }
+            });
+          }
+          onError?.(mappedError, stepName, context);
+          throw earlyExit(mappedError, { origin: "throw", thrown });
+        }
+        if (fallbackResult.ok) {
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_success",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: fallbackResult,
+              meta: { origin: "fallback", fallbackUsed: true, fallbackReason: String(primaryError) }
+            });
+          }
+          return fallbackResult.value;
+        }
+        const durationMs = performance.now() - startTime;
+        const wrappedError = wrapForStep(fallbackResult.error, {
+          origin: "result",
+          resultCause: fallbackResult.cause
+        });
+        emitEvent({
+          type: "step_error",
+          workflowId,
+          stepId,
+          stepKey,
+          name: stepName,
+          ts: Date.now(),
+          durationMs,
+          error: wrappedError
+        });
+        if (stepKey) {
+          emitEvent({
+            type: "step_complete",
+            workflowId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs,
+            result: fallbackResult,
+            meta: { origin: "result", resultCause: fallbackResult.cause }
+          });
+        }
+        onError?.(wrappedError, stepName, context);
+        throw earlyExit(wrappedError, {
+          origin: "result",
+          resultCause: fallbackResult.cause
+        });
+      })();
+    };
+    stepFn.withResource = (id, options2) => {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(
+          '[awaitly] step.withResource() requires an explicit string ID as the first argument. Example: step.withResource("useDb", { acquire: () => connect(), use: (db) => query(db), release: (db) => db.close() })'
+        );
+      }
+      assertDeclared(id, "step");
+      const stepKey = id;
+      const stepName = id;
+      const stepId = generateStepId(stepKey);
+      const hasEventListeners = onEvent;
+      return (async () => {
+        const startTime = hasEventListeners ? performance.now() : 0;
+        if (onEvent) {
+          emitEvent({
+            type: "step_start",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now()
+          });
+        }
+        let acquireResult;
+        try {
+          acquireResult = await options2.acquire();
+        } catch (thrown) {
+          if (isEarlyExitE(thrown)) {
+            emitEvent({
+              type: "step_aborted",
+              workflowId,
+              stepId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: performance.now() - startTime
+            });
+            throw thrown;
+          }
+          let mappedError;
+          try {
+            mappedError = effectiveCatchUnexpected(thrown);
+          } catch (mapperError) {
+            throw createMapperException(mapperError);
+          }
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2,
+            error: mappedError
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: err(mappedError, { cause: thrown }),
+              meta: { origin: "throw", thrown }
+            });
+          }
+          onError?.(mappedError, stepName, context);
+          throw earlyExit(mappedError, { origin: "throw", thrown });
+        }
+        if (!acquireResult.ok) {
+          const durationMs2 = performance.now() - startTime;
+          const wrappedError2 = wrapForStep(acquireResult.error, {
+            origin: "result",
+            resultCause: acquireResult.cause
+          });
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2,
+            error: wrappedError2
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: acquireResult,
+              meta: { origin: "result", resultCause: acquireResult.cause }
+            });
+          }
+          onError?.(wrappedError2, stepName, context);
+          throw earlyExit(wrappedError2, {
+            origin: "result",
+            resultCause: acquireResult.cause
+          });
+        }
+        const resource = acquireResult.value;
+        let useResult;
+        let useThrown;
+        let useThrewNonResult = false;
+        try {
+          useResult = await options2.use(resource);
+        } catch (thrown) {
+          if (isEarlyExitE(thrown)) {
+            try {
+              await options2.release(resource);
+            } catch (releaseErr) {
+              console.warn(
+                `[awaitly] step.withResource("${id}"): release threw after earlyExit:`,
+                releaseErr
+              );
+            }
+            throw thrown;
+          }
+          useThrown = thrown;
+          useThrewNonResult = true;
+        }
+        try {
+          await options2.release(resource);
+        } catch (releaseErr) {
+          console.warn(
+            `[awaitly] step.withResource("${id}"): release threw:`,
+            releaseErr
+          );
+        }
+        if (useThrewNonResult) {
+          let mappedError;
+          try {
+            mappedError = effectiveCatchUnexpected(useThrown);
+          } catch (mapperError) {
+            throw createMapperException(mapperError);
+          }
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_error",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2,
+            error: mappedError
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result: err(mappedError, { cause: useThrown }),
+              meta: { origin: "throw", thrown: useThrown }
+            });
+          }
+          onError?.(mappedError, stepName, context);
+          throw earlyExit(mappedError, { origin: "throw", thrown: useThrown });
+        }
+        const result = useResult;
+        if (result.ok) {
+          const durationMs2 = performance.now() - startTime;
+          emitEvent({
+            type: "step_success",
+            workflowId,
+            stepId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs: durationMs2
+          });
+          if (stepKey) {
+            emitEvent({
+              type: "step_complete",
+              workflowId,
+              stepKey,
+              name: stepName,
+              ts: Date.now(),
+              durationMs: durationMs2,
+              result
+            });
+          }
+          return result.value;
+        }
+        const durationMs = performance.now() - startTime;
+        const wrappedError = wrapForStep(result.error, {
+          origin: "result",
+          resultCause: result.cause
+        });
+        emitEvent({
+          type: "step_error",
+          workflowId,
+          stepId,
+          stepKey,
+          name: stepName,
+          ts: Date.now(),
+          durationMs,
+          error: wrappedError
+        });
+        if (stepKey) {
+          emitEvent({
+            type: "step_complete",
+            workflowId,
+            stepKey,
+            name: stepName,
+            ts: Date.now(),
+            durationMs,
+            result,
+            meta: { origin: "result", resultCause: result.cause }
+          });
+        }
+        onError?.(wrappedError, stepName, context);
+        throw earlyExit(wrappedError, {
+          origin: "result",
+          resultCause: result.cause
+        });
+      })();
+    };
+    const step = stepFn;
+    const value = await fn({ step });
+    if (process.env.NODE_ENV !== "production" && value !== null && typeof value === "object" && "ok" in value && typeof value.ok === "boolean") {
+      const maybeResult = value;
+      if (maybeResult.ok === true && "value" in maybeResult || maybeResult.ok === false && "error" in maybeResult) {
+        console.warn(
+          `awaitly: Workflow executor returned a Result-like object. Return raw values, not ok() or err().
+
+  Incorrect: return ok({ data });
+  Correct:   return { data };
+
+See: https://jagreehal.github.io/awaitly/guides/troubleshooting/#returning-ok-from-workflow-executor-double-wrapping`
+        );
+      }
+    }
+    return ok2(value);
+  } catch (error) {
+    if (isMapperException(error)) {
+      throw error.thrown;
+    }
+    if (isEarlyExitE(error)) {
+      const originalCause = error.meta.origin === "throw" ? error.meta.thrown : error.meta.origin === "result" ? error.meta.resultCause : void 0;
+      return err(error.error, { cause: originalCause });
+    }
+    const mapped = effectiveCatchUnexpected(error);
+    onError?.(mapped, "unexpected", context);
+    return err(mapped, { cause: error });
+  }
+}
+var runStrict = (fn, options) => {
+  return runFn(fn, options);
+};
+var run = /* @__PURE__ */ Object.assign(runFn, { strict: runStrict });
+async function allAsync(results) {
+  if (results.length === 0) {
+    return ok2([]);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let pendingCount = results.length;
+    const values = new Array(results.length);
+    for (let i = 0; i < results.length; i++) {
+      const index = i;
+      Promise.resolve(results[index]).catch((reason) => err(
+        { type: "PROMISE_REJECTED", cause: reason },
+        { cause: { type: "PROMISE_REJECTION", reason } }
+      )).then((result) => {
+        if (settled) return;
+        if (!result.ok) {
+          settled = true;
+          resolve(result);
+          return;
+        }
+        values[index] = result.value;
+        pendingCount--;
+        if (pendingCount === 0) {
+          resolve(ok2(values));
+        }
+      });
+    }
+  });
+}
+
+// src/workflow/guards.ts
+function isStepComplete(event) {
+  return event.type === "step_complete";
+}
+function isWorkflowCancelled(error) {
+  return typeof error === "object" && error !== null && error.type === "WORKFLOW_CANCELLED";
+}
+
+// src/persistence.ts
+var SnapshotFormatError = class extends Error {
+  constructor(message, errors = []) {
+    super(message);
+    this.errors = errors;
+    this.name = "SnapshotFormatError";
+  }
+  errors;
+};
+var SnapshotDecodeError = class extends Error {
+  constructor(message, stepId, originalError) {
+    super(message);
+    this.stepId = stepId;
+    this.originalError = originalError;
+    this.name = "SnapshotDecodeError";
+  }
+  stepId;
+  originalError;
+};
+function validateSnapshot(obj) {
+  const errors = [];
+  if (typeof obj !== "object" || obj === null) {
+    return { valid: false, errors: ["Snapshot must be an object"] };
+  }
+  const snapshot = obj;
+  if (!("formatVersion" in snapshot)) {
+    errors.push("Missing required field: formatVersion");
+  } else if (snapshot.formatVersion !== 1) {
+    errors.push(`Invalid formatVersion: expected 1, got ${snapshot.formatVersion}`);
+  }
+  if (!("steps" in snapshot)) {
+    errors.push("Missing required field: steps");
+  } else if (typeof snapshot.steps !== "object" || snapshot.steps === null) {
+    errors.push("steps must be an object");
+  } else {
+    const steps = snapshot.steps;
+    for (const [stepId, stepResult] of Object.entries(steps)) {
+      if (typeof stepResult !== "object" || stepResult === null) {
+        errors.push(`steps["${stepId}"] must be an object`);
+        continue;
+      }
+      const step = stepResult;
+      if (!("ok" in step)) {
+        errors.push(`steps["${stepId}"] missing required field: ok`);
+      } else if (typeof step.ok !== "boolean") {
+        errors.push(`steps["${stepId}"].ok must be a boolean`);
+      } else if (step.ok === false) {
+        if (!("error" in step)) {
+          errors.push(`steps["${stepId}"] is error result but missing error field`);
+        }
+        if (!("cause" in step)) {
+          errors.push(`steps["${stepId}"] is error result but missing cause field`);
+        }
+      }
+    }
+  }
+  if (!("execution" in snapshot)) {
+    errors.push("Missing required field: execution");
+  } else if (typeof snapshot.execution !== "object" || snapshot.execution === null) {
+    errors.push("execution must be an object");
+  } else {
+    const execution = snapshot.execution;
+    if (!("status" in execution)) {
+      errors.push("execution missing required field: status");
+    } else if (!["running", "completed", "failed"].includes(execution.status)) {
+      errors.push(`execution.status must be one of: running, completed, failed`);
+    }
+    if (!("lastUpdated" in execution)) {
+      errors.push("execution missing required field: lastUpdated");
+    } else if (typeof execution.lastUpdated !== "string") {
+      errors.push("execution.lastUpdated must be a string (ISO timestamp)");
+    }
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true, snapshot: obj };
+}
+function assertValidSnapshot(obj) {
+  const result = validateSnapshot(obj);
+  if (!result.valid) {
+    throw new SnapshotFormatError(`Invalid snapshot format: ${result.errors[0]}`, result.errors);
+  }
+  return result.snapshot;
+}
+function mergeSnapshots(base, delta) {
+  const mergedSteps = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(base.steps)) {
+    if (Object.prototype.hasOwnProperty.call(base.steps, key)) {
+      mergedSteps[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(delta.steps)) {
+    if (Object.prototype.hasOwnProperty.call(delta.steps, key)) {
+      mergedSteps[key] = value;
+    }
+  }
+  const mergedMetadata = base.metadata || delta.metadata ? { ...base.metadata, ...delta.metadata } : void 0;
+  const baseWarnings = (base.warnings || []).filter(
+    (w) => !Object.prototype.hasOwnProperty.call(delta.steps, w.stepId)
+  );
+  const mergedWarnings = [...baseWarnings, ...delta.warnings || []];
+  return {
+    formatVersion: 1,
+    steps: mergedSteps,
+    execution: { ...delta.execution },
+    metadata: mergedMetadata,
+    warnings: mergedWarnings.length > 0 ? mergedWarnings : void 0
+  };
+}
+var MAX_STRING_REPRESENTATION_LENGTH = 1e3;
+function serializeError(error) {
+  const serialized = {
+    type: "error",
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack) {
+    serialized.stack = error.stack;
+  }
+  const errorWithCause = error;
+  if (errorWithCause.cause !== void 0) {
+    if (errorWithCause.cause instanceof Error) {
+      serialized.cause = serializeError(errorWithCause.cause);
+    } else {
+      serialized.cause = serializeThrown(errorWithCause.cause);
+    }
+  }
+  return serialized;
+}
+function serializeThrown(value) {
+  let stringRepresentation;
+  let truncated = false;
+  try {
+    stringRepresentation = String(value);
+    if (stringRepresentation.length > MAX_STRING_REPRESENTATION_LENGTH) {
+      stringRepresentation = stringRepresentation.slice(0, MAX_STRING_REPRESENTATION_LENGTH);
+      truncated = true;
+    }
+  } catch {
+    stringRepresentation = "[unable to convert to string]";
+  }
+  const originalType = value === null ? "null" : typeof value === "object" ? value.constructor?.name ?? "Object" : typeof value;
+  let jsonValue;
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized !== void 0) {
+      jsonValue = JSON.parse(serialized);
+    }
+  } catch {
+  }
+  const result = {
+    type: "thrown",
+    originalType,
+    stringRepresentation
+  };
+  if (jsonValue !== void 0) {
+    result.value = jsonValue;
+  }
+  if (truncated) {
+    result.truncated = true;
+  }
+  return result;
+}
+function deserializeCauseNew(serialized) {
+  if (serialized.type === "error") {
+    const error = new Error(serialized.message);
+    error.name = serialized.name;
+    if (serialized.stack) {
+      error.stack = serialized.stack;
+    }
+    if (serialized.cause) {
+      error.cause = deserializeCauseNew(serialized.cause);
+    }
+    return error;
+  }
+  return serialized.value !== void 0 ? serialized.value : serialized.stringRepresentation;
+}
+
+// src/workflow/cache-encoding.ts
+function isCachedErrorCause(cause) {
+  return typeof cause === "object" && cause !== null && cause.__cachedMeta === true;
+}
+function encodeCachedError(error, meta, originalCause) {
+  return err(error, {
+    cause: { __cachedMeta: true, originalCause, meta }
+  });
+}
+function decodeCachedMeta(cause) {
+  if (isCachedErrorCause(cause)) {
+    return cause.meta;
+  }
+  return { origin: "result", resultCause: cause };
+}
+
+// src/workflow/resume-state.ts
+function createResumeStateCollector() {
+  const steps = /* @__PURE__ */ new Map();
+  return {
+    handleEvent: (event) => {
+      if (isStepComplete(event)) {
+        steps.set(event.stepKey, { result: event.result, meta: event.meta });
+      }
+    },
+    getResumeState: () => ({ steps: new Map(steps) }),
+    clear: () => steps.clear()
+  };
+}
+
+// src/streaming/types.ts
+var STREAM_WRITE_ERROR = "STREAM_WRITE_ERROR";
+var STREAM_READ_ERROR = "STREAM_READ_ERROR";
+var STREAM_CLOSE_ERROR = "STREAM_CLOSE_ERROR";
+var STREAM_ENDED = "STREAM_ENDED";
+function streamWriteError(reason, message, cause) {
+  return {
+    type: STREAM_WRITE_ERROR,
+    reason,
+    message,
+    ...cause !== void 0 ? { cause } : {}
+  };
+}
+function streamReadError(reason, message, cause) {
+  return {
+    type: STREAM_READ_ERROR,
+    reason,
+    message,
+    ...cause !== void 0 ? { cause } : {}
+  };
+}
+function streamCloseError(reason, message, cause) {
+  return {
+    type: STREAM_CLOSE_ERROR,
+    reason,
+    message,
+    ...cause !== void 0 ? { cause } : {}
+  };
+}
+function streamEnded(finalPosition) {
+  return {
+    type: STREAM_ENDED,
+    finalPosition
+  };
+}
+
+// src/streaming/backpressure.ts
+function createBackpressureController(options = {}) {
+  const highWaterMark = options.highWaterMark ?? 16;
+  const lowWaterMark = options.lowWaterMark ?? Math.floor(highWaterMark / 2);
+  const onStateChange = options.onStateChange;
+  let state = "flowing";
+  let bufferedCount = 0;
+  let drainResolvers = [];
+  function updateState(newState) {
+    if (state !== newState) {
+      state = newState;
+      onStateChange?.(newState);
+      if (newState === "flowing" && drainResolvers.length > 0) {
+        const resolvers = drainResolvers;
+        drainResolvers = [];
+        for (const resolve of resolvers) {
+          resolve();
+        }
+      }
+    }
+  }
+  function checkState() {
+    if (state === "flowing" && bufferedCount >= highWaterMark) {
+      updateState("paused");
+    } else if (state === "paused" && bufferedCount <= lowWaterMark) {
+      updateState("flowing");
+    }
+  }
+  return {
+    get state() {
+      return state;
+    },
+    get bufferedCount() {
+      return bufferedCount;
+    },
+    get highWaterMark() {
+      return highWaterMark;
+    },
+    get lowWaterMark() {
+      return lowWaterMark;
+    },
+    increment() {
+      bufferedCount++;
+      checkState();
+    },
+    decrement() {
+      if (bufferedCount > 0) {
+        bufferedCount--;
+        checkState();
+      }
+    },
+    setCount(count) {
+      bufferedCount = Math.max(0, count);
+      checkState();
+    },
+    waitForDrain() {
+      if (state === "flowing") {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        drainResolvers.push(resolve);
+      });
+    },
+    reset() {
+      bufferedCount = 0;
+      drainResolvers = [];
+      updateState("flowing");
+    }
+  };
+}
+
+// src/workflow/validation.ts
+async function validateInput(schema, input) {
+  const result = schema["~standard"].validate(input);
+  const resolved = result instanceof Promise ? await result : result;
+  if (resolved.issues) {
+    return err({
+      type: "INPUT_VALIDATION_ERROR",
+      issues: resolved.issues.map((i) => ({
+        message: i.message,
+        path: i.path?.map(
+          (p) => typeof p === "object" ? p.key : p
+        )
+      })),
+      message: `Input validation failed: ${resolved.issues.map((i) => i.message).join(", ")}`
+    });
+  }
+  return ok2(resolved.value);
+}
+
+// src/di.ts
+function withDeps(workflow, overrides) {
+  const forward = (method) => ((...args) => {
+    const last = args.at(-1);
+    const hasConfig = args.length > 0 && typeof last === "object" && last !== null && !Array.isArray(last) && typeof last !== "function";
+    const config = hasConfig ? last : void 0;
+    const head = hasConfig ? args.slice(0, -1) : args;
+    const mergedDeps = { ...overrides, ...config?.deps ?? {} };
+    const mergedConfig = config ? { ...config, deps: mergedDeps } : { deps: mergedDeps };
+    return workflow[method](...head, mergedConfig);
+  });
+  return {
+    run: forward("run"),
+    runWithState: forward("runWithState"),
+    withDeps(nextOverrides) {
+      return withDeps(workflow, { ...overrides, ...nextOverrides });
+    }
+  };
+}
+
+// src/workflow/execute.ts
+function createWorkflow(workflowName, deps, options) {
+  if (typeof workflowName !== "string" || workflowName.length === 0) {
+    throw new TypeError(
+      "createWorkflow(workflowName, deps, options?): first argument must be a non-empty string. Example: createWorkflow('checkout', { chargeCard, sendEmail })"
+    );
+  }
+  const depsActual = deps ?? {};
+  const optionsActual = options;
+  async function internalExecute(runName, userFn, config) {
+    const workflowId = runName ?? crypto.randomUUID();
+    const effectiveDeps = config?.deps ? { ...depsActual, ...config.deps } : depsActual;
+    const compensations = [];
+    const createContextFn = config?.createContext ?? optionsActual?.createContext;
+    const context = createContextFn ? await createContextFn() : void 0;
+    const workflowSignal = config?.signal ?? optionsActual?.signal;
+    const onEventHandler = config?.onEvent ?? optionsActual?.onEvent;
+    const onErrorHandler = config?.onError ?? optionsActual?.onError;
+    const shouldRunHook = config?.shouldRun ?? optionsActual?.shouldRun;
+    const onBeforeStartHook = config?.onBeforeStart ?? optionsActual?.onBeforeStart;
+    const onAfterStepHook = config?.onAfterStep ?? optionsActual?.onAfterStep;
+    const resumeStateOption = config?.resumeState ?? optionsActual?.resumeState;
+    const catchUnexpected = optionsActual?.catchUnexpected ?? defaultCatchUnexpected;
+    const declaredGraph = config?.graph ?? optionsActual?.graph;
+    const workflowData = {};
+    const devWarnings = (config?.devWarnings ?? optionsActual?.devWarnings) === true && process.env.NODE_ENV !== "production";
+    const ctxSetWarned = /* @__PURE__ */ new Set();
+    const ctxGetWarned = /* @__PURE__ */ new Set();
+    const workflowContext = {
+      workflowId,
+      onEvent: onEventHandler,
+      context: context !== void 0 ? context : void 0,
+      signal: workflowSignal,
+      // Data store for static analysis
+      input: {},
+      ref: (key) => workflowData[key],
+      set: (key, value) => {
+        if (devWarnings && !ctxSetWarned.has(key)) {
+          ctxSetWarned.add(key);
+          console.warn(
+            `awaitly: ctx.set('${key}', ...) is deprecated for static analysis. Use step('id', fn, { out: '${key}' }) instead.`
+          );
+        }
+        workflowData[key] = value;
+      },
+      get: (key) => {
+        if (devWarnings && !ctxGetWarned.has(key)) {
+          ctxGetWarned.add(key);
+          console.warn(
+            `awaitly: ctx.get('${key}') is deprecated for static analysis. Use ctx.ref('${key}') instead for tracked dependencies.`
+          );
+        }
+        return workflowData[key];
+      }
+    };
+    const emitEvent = (event) => {
+      const eventWithContext = event.context !== void 0 || context === void 0 ? event : { ...event, context };
+      const eventWithName = eventWithContext.workflowName === void 0 ? { ...eventWithContext, workflowName } : eventWithContext;
+      onEventHandler?.(eventWithName, context);
+    };
+    const createCancelledResult = (reason, lastStepKey2) => {
+      const cancelledError = {
+        type: "WORKFLOW_CANCELLED",
+        reason,
+        lastStepKey: lastStepKey2
+      };
+      return err(catchUnexpected(cancelledError), { cause: cancelledError });
+    };
+    if (workflowSignal?.aborted) {
+      const reason = typeof workflowSignal.reason === "string" ? workflowSignal.reason : workflowSignal.reason instanceof Error ? workflowSignal.reason.message : void 0;
+      emitEvent({
+        type: "workflow_cancelled",
+        workflowId,
+        ts: Date.now(),
+        durationMs: 0,
+        reason
+      });
+      return createCancelledResult(reason);
+    }
+    if (shouldRunHook) {
+      const hookStartTime = performance.now();
+      try {
+        const shouldRunResult = await shouldRunHook(workflowId, context);
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_should_run",
+          workflowId,
+          ts: Date.now(),
+          durationMs: hookDuration,
+          result: shouldRunResult,
+          skipped: !shouldRunResult
+        });
+        if (!shouldRunResult) {
+          const skipCause = new Error("Workflow skipped by shouldRun hook");
+          return err(catchUnexpected(skipCause), { cause: skipCause });
+        }
+      } catch (thrown) {
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_should_run_error",
+          workflowId,
+          ts: Date.now(),
+          durationMs: hookDuration,
+          error: thrown
+        });
+        return err(catchUnexpected(thrown), { cause: thrown });
+      }
+    }
+    if (onBeforeStartHook) {
+      const hookStartTime = performance.now();
+      try {
+        const beforeStartResult = await onBeforeStartHook(workflowId, context);
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_before_start",
+          workflowId,
+          ts: Date.now(),
+          durationMs: hookDuration,
+          result: beforeStartResult,
+          skipped: !beforeStartResult
+        });
+        if (!beforeStartResult) {
+          const skipCause = new Error("Workflow skipped by onBeforeStart hook");
+          return err(catchUnexpected(skipCause), { cause: skipCause });
+        }
+      } catch (thrown) {
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_before_start_error",
+          workflowId,
+          ts: Date.now(),
+          durationMs: hookDuration,
+          error: thrown
+        });
+        return err(catchUnexpected(thrown), { cause: thrown });
+      }
+    }
+    const inputSchema = optionsActual?.inputSchema;
+    const inputValue = optionsActual?.input;
+    if (inputSchema) {
+      const validationResult = await validateInput(inputSchema, inputValue);
+      if (!validationResult.ok) {
+        return err(validationResult.error);
+      }
+      workflowContext.input = validationResult.value;
+    } else if (inputValue !== void 0) {
+      workflowContext.input = inputValue;
+    }
+    const startTs = Date.now();
+    const startTime = performance.now();
+    emitEvent({
+      type: "workflow_start",
+      workflowId,
+      ts: startTs
+    });
+    let cache = config?.cache ?? optionsActual?.cache;
+    const streamStore = config?.streamStore ?? optionsActual?.streamStore;
+    if (resumeStateOption && !cache) {
+      cache = /* @__PURE__ */ new Map();
+    }
+    if (resumeStateOption && cache) {
+      const resumeState = typeof resumeStateOption === "function" ? await resumeStateOption() : resumeStateOption;
+      if (!(resumeState.steps instanceof Map)) {
+        console.warn(
+          `awaitly: resumeState.steps is not a Map (got ${typeof resumeState.steps}). This usually happens when state is serialized with JSON.stringify() directly.
+Use serializeResumeState() and deserializeResumeState() from 'awaitly/workflow' instead:
+  import { serializeResumeState, deserializeResumeState } from 'awaitly/workflow';
+  const json = JSON.stringify(serializeResumeState(state));  // Save this
+  const restored = deserializeResumeState(JSON.parse(json)); // Load this`
+        );
+        if (typeof resumeState.steps === "object" && resumeState.steps !== null) {
+          resumeState.steps = new Map(Object.entries(resumeState.steps));
+        }
+      }
+      for (const [key, entry] of resumeState.steps) {
+        const { result: result2, meta } = entry;
+        if (result2.ok) {
+          cache.set(key, result2);
+        } else {
+          const effectiveMeta = meta ?? { origin: "result", resultCause: result2.cause };
+          cache.set(key, encodeCachedError(result2.error, effectiveMeta, result2.cause));
+        }
+      }
+    }
+    const snapshotOption = config?.snapshot ?? optionsActual?.snapshot;
+    const snapshotSerialization = optionsActual?.serialization;
+    if (snapshotOption && !resumeStateOption) {
+      if (!cache) {
+        cache = /* @__PURE__ */ new Map();
+      }
+      const snapshot = snapshotOption;
+      const decode = snapshotSerialization?.decode;
+      for (const [stepId, stepResult] of Object.entries(snapshot.steps)) {
+        if (!Object.prototype.hasOwnProperty.call(snapshot.steps, stepId)) {
+          continue;
+        }
+        try {
+          if (stepResult.ok) {
+            const value = decode ? decode(stepResult.value) : stepResult.value;
+            cache.set(stepId, ok2(value));
+          } else {
+            const errorValue = decode ? decode(stepResult.error) : stepResult.error;
+            const deserializedCause = deserializeCauseNew(stepResult.cause);
+            const meta = stepResult.meta?.origin === "throw" ? { origin: "throw", thrown: deserializedCause } : { origin: "result", resultCause: deserializedCause };
+            cache.set(stepId, encodeCachedError(errorValue, meta, deserializedCause));
+          }
+        } catch (e) {
+          throw new SnapshotDecodeError(
+            `Failed to decode step "${stepId}": ${e instanceof Error ? e.message : String(e)}`,
+            stepId,
+            e instanceof Error ? e : void 0
+          );
+        }
+      }
+    }
+    let abortedDuringExecution = false;
+    let abortReason;
+    let lastStepKey;
+    const abortHandler = () => {
+      abortedDuringExecution = true;
+      abortReason = typeof workflowSignal?.reason === "string" ? workflowSignal.reason : workflowSignal?.reason instanceof Error ? workflowSignal.reason.message : void 0;
+    };
+    if (workflowSignal && !workflowSignal.aborted) {
+      workflowSignal.addEventListener("abort", abortHandler, { once: true });
+    }
+    const checkCancellation = () => {
+      if (abortedDuringExecution || workflowSignal?.aborted) {
+        const reason = abortReason ?? (typeof workflowSignal?.reason === "string" ? workflowSignal.reason : workflowSignal?.reason instanceof Error ? workflowSignal.reason.message : void 0);
+        const cancelledError = {
+          type: "WORKFLOW_CANCELLED",
+          reason,
+          lastStepKey
+        };
+        throw cancelledError;
+      }
+    };
+    const callOnAfterStepHook = async (stepKey, result2, _meta) => {
+      if (!onAfterStepHook) return;
+      const hookStartTime = performance.now();
+      try {
+        await onAfterStepHook(stepKey, result2, workflowId, context);
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_after_step",
+          workflowId,
+          stepKey,
+          ts: Date.now(),
+          durationMs: hookDuration
+        });
+      } catch (thrown) {
+        const hookDuration = performance.now() - hookStartTime;
+        emitEvent({
+          type: "hook_after_step_error",
+          workflowId,
+          stepKey,
+          ts: Date.now(),
+          durationMs: hookDuration,
+          error: thrown
+        });
+        throw thrown;
+      }
+    };
+    const createCachedStep = (realStep) => {
+      const cachedStepFn = async (idOrOperationOrResult, operationOrOptions, stepOptions) => {
+        if (typeof idOrOperationOrResult !== "string") {
+          throw new Error(
+            '[awaitly] step() requires a string ID as the first argument. Example: step("fetchUser", () => fetchUser(id))'
+          );
+        }
+        const id = idOrOperationOrResult;
+        const opts = stepOptions ?? {};
+        const name = id;
+        const key = Object.prototype.hasOwnProperty.call(opts, "key") ? opts.key : id;
+        const { ttl, out } = opts;
+        checkCancellation();
+        const stepMetadata = extractStepMetadata(opts);
+        if (key && cache && cache.has(key)) {
+          emitEvent({
+            type: "step_cache_hit",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now(),
+            ...stepMetadata && { metadata: stepMetadata }
+          });
+          const cached = cache.get(key);
+          if (cached.ok) {
+            lastStepKey = key;
+            if (out) {
+              workflowData[out] = cached.value;
+            }
+            return cached.value;
+          }
+          const meta = decodeCachedMeta(cached.cause);
+          throw createEarlyExit(cached.error, meta);
+        }
+        if (key && cache) {
+          emitEvent({
+            type: "step_cache_miss",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now(),
+            ...stepMetadata && { metadata: stepMetadata }
+          });
+        }
+        try {
+          const value = await realStep(
+            id,
+            operationOrOptions,
+            opts
+          );
+          if (out) {
+            workflowData[out] = value;
+          }
+          if (opts.compensate) {
+            compensations.push({
+              stepName: name,
+              value,
+              compensate: opts.compensate
+            });
+          }
+          if (key) {
+            lastStepKey = key;
+            if (cache) {
+              cache.set(key, ok2(value), ttl ? { ttl } : void 0);
+            }
+            await callOnAfterStepHook(key, ok2(value));
+          }
+          return value;
+        } catch (thrown) {
+          if (key && isEarlyExit(thrown)) {
+            const exit = thrown;
+            const originalCause = exit.meta.origin === "result" ? exit.meta.resultCause : exit.meta.origin === "throw" ? exit.meta.thrown : void 0;
+            const errorResult = encodeCachedError(exit.error, exit.meta, originalCause);
+            if (cache) {
+              cache.set(key, errorResult, ttl ? { ttl } : void 0);
+            }
+            await callOnAfterStepHook(key, errorResult, exit.meta);
+          }
+          throw thrown;
+        }
+      };
+      cachedStepFn.try = async (id, operation, opts) => {
+        const { ttl } = opts;
+        const key = opts.key ?? id;
+        const name = id;
+        if (cache && cache.has(key)) {
+          emitEvent({
+            type: "step_cache_hit",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+          const cached = cache.get(key);
+          if (cached.ok) {
+            return cached.value;
+          }
+          const meta = decodeCachedMeta(cached.cause);
+          throw createEarlyExit(cached.error, meta);
+        }
+        if (cache) {
+          emitEvent({
+            type: "step_cache_miss",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+        }
+        try {
+          const value = await realStep.try(id, operation, { ...opts, key });
+          if (opts.compensate) {
+            compensations.push({
+              stepName: name,
+              value,
+              compensate: opts.compensate
+            });
+          }
+          if (cache) {
+            cache.set(key, ok2(value), ttl ? { ttl } : void 0);
+          }
+          await callOnAfterStepHook(key, ok2(value));
+          return value;
+        } catch (thrown) {
+          if (isEarlyExit(thrown)) {
+            const exit = thrown;
+            const originalCause = exit.meta.origin === "result" ? exit.meta.resultCause : exit.meta.origin === "throw" ? exit.meta.thrown : void 0;
+            const errorResult = encodeCachedError(exit.error, exit.meta, originalCause);
+            if (cache) {
+              cache.set(key, errorResult, ttl ? { ttl } : void 0);
+            }
+            await callOnAfterStepHook(key, errorResult, exit.meta);
+          }
+          throw thrown;
+        }
+      };
+      cachedStepFn.fromResult = async (id, operation, opts) => {
+        const { ttl } = opts;
+        const key = opts.key ?? id;
+        const name = id;
+        if (cache && cache.has(key)) {
+          emitEvent({
+            type: "step_cache_hit",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+          const cached = cache.get(key);
+          if (cached.ok) {
+            return cached.value;
+          }
+          const meta = decodeCachedMeta(cached.cause);
+          throw createEarlyExit(cached.error, meta);
+        }
+        if (cache) {
+          emitEvent({
+            type: "step_cache_miss",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+        }
+        try {
+          const value = await realStep.fromResult(id, operation, { ...opts, key });
+          if (cache) {
+            cache.set(key, ok2(value), ttl ? { ttl } : void 0);
+          }
+          await callOnAfterStepHook(key, ok2(value));
+          return value;
+        } catch (thrown) {
+          if (isEarlyExit(thrown)) {
+            const exit = thrown;
+            const originalCause = exit.meta.origin === "result" ? exit.meta.resultCause : exit.meta.origin === "throw" ? exit.meta.thrown : void 0;
+            const errorResult = encodeCachedError(exit.error, exit.meta, originalCause);
+            if (cache) {
+              cache.set(key, errorResult, ttl ? { ttl } : void 0);
+            }
+            await callOnAfterStepHook(key, errorResult, exit.meta);
+          }
+          throw thrown;
+        }
+      };
+      cachedStepFn.race = realStep.race;
+      cachedStepFn.withFallback = async (id, operation, options2) => {
+        const key = options2.key ?? id;
+        const name = id;
+        if (cache && cache.has(key)) {
+          emitEvent({
+            type: "step_cache_hit",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+          const cached = cache.get(key);
+          if (cached.ok) {
+            return cached.value;
+          }
+          const meta = decodeCachedMeta(cached.cause);
+          throw createEarlyExit(cached.error, meta);
+        }
+        if (cache) {
+          emitEvent({
+            type: "step_cache_miss",
+            workflowId,
+            stepKey: key,
+            name,
+            ts: Date.now()
+          });
+        }
+        try {
+          const value = await realStep.withFallback(
+            id,
+            operation,
+            options2
+          );
+          if (cache) {
+            cache.set(key, ok2(value));
+          }
+          await callOnAfterStepHook(key, ok2(value));
+          return value;
+        } catch (thrown) {
+          if (isEarlyExit(thrown)) {
+            const exit = thrown;
+            const originalCause = exit.meta.origin === "result" ? exit.meta.resultCause : exit.meta.origin === "throw" ? exit.meta.thrown : void 0;
+            const errorResult = encodeCachedError(exit.error, exit.meta, originalCause);
+            if (cache) {
+              cache.set(key, errorResult);
+            }
+            await callOnAfterStepHook(key, errorResult, exit.meta);
+          }
+          throw thrown;
+        }
+      };
+      cachedStepFn.withResource = async (id, options2) => {
+        const key = id;
+        try {
+          const value = await realStep.withResource(id, options2);
+          await callOnAfterStepHook(key, ok2(value));
+          return value;
+        } catch (thrown) {
+          if (isEarlyExit(thrown)) {
+            const exit = thrown;
+            const originalCause = exit.meta.origin === "result" ? exit.meta.resultCause : exit.meta.origin === "throw" ? exit.meta.thrown : void 0;
+            const errorResult = encodeCachedError(exit.error, exit.meta, originalCause);
+            await callOnAfterStepHook(key, errorResult, exit.meta);
+          }
+          throw thrown;
+        }
+      };
+      cachedStepFn.retry = (id, operation, options2) => {
+        const stepOptions = {
+          key: options2.key,
+          // explicitly pass so undefined = don't cache
+          retry: {
+            attempts: options2.attempts,
+            backoff: options2.backoff,
+            initialDelay: options2.initialDelay,
+            maxDelay: options2.maxDelay,
+            jitter: options2.jitter,
+            shouldRetry: options2.shouldRetry,
+            onRetry: options2.onRetry
+          },
+          timeout: options2.timeout,
+          ttl: options2.ttl
+        };
+        return cachedStepFn(id, operation, stepOptions);
+      };
+      cachedStepFn.withTimeout = (id, operation, options2) => {
+        const stepOptions = {
+          key: options2.key,
+          timeout: options2,
+          ttl: options2.ttl
+        };
+        return cachedStepFn(
+          id,
+          operation,
+          stepOptions
+        );
+      };
+      cachedStepFn.sleep = (id, duration, options2) => {
+        if (typeof id !== "string" || id.length === 0) {
+          throw new Error(
+            '[awaitly] step.sleep() requires an explicit string ID as the first argument. Example: step.sleep("delay", "5s")'
+          );
+        }
+        const d = typeof duration === "string" ? parse(duration) : duration;
+        if (!d) {
+          throw new Error(`step.sleep: invalid duration '${duration}'`);
+        }
+        const ms = toMillis(d);
+        const userSignal = options2?.signal;
+        const sleepOperation = async () => {
+          if (workflowSignal?.aborted || userSignal?.aborted) {
+            const e = new Error("Sleep aborted");
+            e.name = "AbortError";
+            throw e;
+          }
+          return new Promise((resolve, reject) => {
+            const state = {
+              timeoutId: void 0
+            };
+            const onAbort = () => {
+              if (state.timeoutId) clearTimeout(state.timeoutId);
+              const e = new Error("Sleep aborted");
+              e.name = "AbortError";
+              reject(e);
+            };
+            workflowSignal?.addEventListener("abort", onAbort, { once: true });
+            userSignal?.addEventListener("abort", onAbort, { once: true });
+            state.timeoutId = setTimeout(() => {
+              workflowSignal?.removeEventListener("abort", onAbort);
+              userSignal?.removeEventListener("abort", onAbort);
+              resolve(ok2(void 0));
+            }, ms);
+          });
+        };
+        return cachedStepFn(id, sleepOperation, {
+          key: options2?.key,
+          ttl: options2?.ttl,
+          description: options2?.description
+        });
+      };
+      const activeWriters = /* @__PURE__ */ new Map();
+      const activeReaders = /* @__PURE__ */ new Map();
+      cachedStepFn.getWritable = (options2) => {
+        const namespace = options2?.namespace ?? "default";
+        const highWaterMark = options2?.highWaterMark ?? 16;
+        if (!streamStore) {
+          throw new Error(
+            "streamStore is required to use getWritable(). Pass a streamStore to createWorkflow options."
+          );
+        }
+        const existingKey = `${workflowId}:${namespace}`;
+        const existing = activeWriters.get(existingKey);
+        if (existing && !existing.closed && !existing.aborted) {
+          return existing.writer;
+        }
+        const backpressure = createBackpressureController({
+          highWaterMark,
+          onStateChange: (state) => {
+            emitEvent({
+              type: "stream_backpressure",
+              workflowId,
+              namespace,
+              bufferedCount: backpressure.bufferedCount,
+              state,
+              ts: Date.now()
+            });
+          }
+        });
+        let position = 0;
+        let writable = true;
+        let aborted = false;
+        let closed = false;
+        emitEvent({
+          type: "stream_created",
+          workflowId,
+          namespace,
+          ts: Date.now()
+        });
+        const writer = {
+          async write(value) {
+            if (closed) {
+              return err(streamWriteError("closed", "Stream is closed"));
+            }
+            if (aborted) {
+              return err(streamWriteError("aborted", "Stream was aborted"));
+            }
+            if (backpressure.state === "paused") {
+              await backpressure.waitForDrain();
+            }
+            const item = {
+              value,
+              position,
+              ts: Date.now()
+            };
+            const result2 = await streamStore.append(workflowId, namespace, item);
+            if (!result2.ok) {
+              emitEvent({
+                type: "stream_error",
+                workflowId,
+                namespace,
+                error: result2.error,
+                position,
+                ts: Date.now()
+              });
+              return err(streamWriteError("store_error", result2.error.message, result2.error));
+            }
+            emitEvent({
+              type: "stream_write",
+              workflowId,
+              namespace,
+              position,
+              ts: Date.now()
+            });
+            position++;
+            backpressure.increment();
+            return ok2(void 0);
+          },
+          async close() {
+            if (closed) {
+              return err(streamCloseError("already_closed", "Stream is already closed"));
+            }
+            const result2 = await streamStore.closeStream(workflowId, namespace);
+            if (!result2.ok) {
+              return err(streamCloseError("store_error", result2.error.message, result2.error));
+            }
+            closed = true;
+            writable = false;
+            emitEvent({
+              type: "stream_close",
+              workflowId,
+              namespace,
+              finalPosition: position,
+              ts: Date.now()
+            });
+            activeWriters.delete(existingKey);
+            return ok2(void 0);
+          },
+          abort(reason) {
+            aborted = true;
+            writable = false;
+            closed = true;
+            emitEvent({
+              type: "stream_error",
+              workflowId,
+              namespace,
+              error: reason,
+              position,
+              ts: Date.now()
+            });
+            activeWriters.delete(existingKey);
+          },
+          get writable() {
+            return writable;
+          },
+          get position() {
+            return position;
+          },
+          get namespace() {
+            return namespace;
+          }
+        };
+        activeWriters.set(existingKey, {
+          writer,
+          backpressure,
+          aborted,
+          closed
+        });
+        return writer;
+      };
+      cachedStepFn.getReadable = (options2) => {
+        const namespace = options2?.namespace ?? "default";
+        const startIndex = options2?.startIndex ?? 0;
+        const pollInterval = options2?.pollInterval ?? 10;
+        const pollTimeout = options2?.pollTimeout ?? 3e4;
+        if (!streamStore) {
+          throw new Error(
+            "streamStore is required to use getReadable(). Pass a streamStore to createWorkflow options."
+          );
+        }
+        const existingKey = `${workflowId}:${namespace}:${startIndex}`;
+        const existing = activeReaders.get(existingKey);
+        if (existing && !existing.closed) {
+          return existing.reader;
+        }
+        const decrementBackpressure = () => {
+          const writerKey = `${workflowId}:${namespace}`;
+          const activeWriter = activeWriters.get(writerKey);
+          if (activeWriter) {
+            activeWriter.backpressure.decrement();
+          }
+        };
+        let position = startIndex;
+        let readable = true;
+        let closed = false;
+        let bufferedItems = [];
+        let bufferIndex = 0;
+        const reader = {
+          async read() {
+            if (closed) {
+              return err(streamReadError("closed", "Reader is closed"));
+            }
+            if (bufferIndex < bufferedItems.length) {
+              const item = bufferedItems[bufferIndex++];
+              position = item.position + 1;
+              decrementBackpressure();
+              emitEvent({
+                type: "stream_read",
+                workflowId,
+                namespace,
+                position: item.position,
+                ts: Date.now()
+              });
+              return ok2(item.value);
+            }
+            const writerKey = `${workflowId}:${namespace}`;
+            const pollStart = Date.now();
+            let hasSeenWriter = activeWriters.has(writerKey);
+            const initialMetaResult = await streamStore.getMetadata(workflowId, namespace);
+            let hasSeenMetadata = initialMetaResult.ok && initialMetaResult.value !== void 0;
+            while (Date.now() - pollStart < pollTimeout) {
+              const result2 = await streamStore.read(workflowId, namespace, position, 100);
+              if (!result2.ok) {
+                return err(streamReadError("store_error", result2.error.message, result2.error));
+              }
+              const items = result2.value;
+              if (items.length > 0) {
+                bufferedItems = items;
+                bufferIndex = 1;
+                const item = items[0];
+                position = item.position + 1;
+                decrementBackpressure();
+                emitEvent({
+                  type: "stream_read",
+                  workflowId,
+                  namespace,
+                  position: item.position,
+                  ts: Date.now()
+                });
+                return ok2(item.value);
+              }
+              const writerActive = activeWriters.has(writerKey);
+              const metaResult = await streamStore.getMetadata(workflowId, namespace);
+              const metadataExists = metaResult.ok && metaResult.value !== void 0;
+              if (writerActive) hasSeenWriter = true;
+              if (metadataExists) hasSeenMetadata = true;
+              if (metaResult.ok && metaResult.value?.closed) {
+                readable = false;
+                return err(streamEnded(position));
+              }
+              if (hasSeenWriter && !writerActive && !metadataExists) {
+                readable = false;
+                return err(streamEnded(position));
+              }
+              if (hasSeenMetadata && !writerActive && metaResult.ok && !metaResult.value?.closed) {
+              }
+              await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            }
+            readable = false;
+            return err(streamEnded(position));
+          },
+          close() {
+            closed = true;
+            readable = false;
+            bufferedItems = [];
+            activeReaders.delete(existingKey);
+          },
+          get readable() {
+            return readable;
+          },
+          get position() {
+            return position;
+          },
+          get namespace() {
+            return namespace;
+          }
+        };
+        activeReaders.set(existingKey, {
+          reader,
+          position,
+          closed
+        });
+        return reader;
+      };
+      cachedStepFn.streamForEach = async (source, processor, options2) => {
+        const checkpointInterval = options2?.checkpointInterval ?? 1;
+        const concurrency = options2?.concurrency ?? 1;
+        const results = [];
+        let processedCount = 0;
+        let lastPosition = -1;
+        const isStreamReader = (s) => {
+          return typeof s === "object" && s !== null && "read" in s && typeof s.read === "function";
+        };
+        const processItem = async (item, itemIndex, itemPosition, namespace) => {
+          const shouldCheckpoint = checkpointInterval > 0 && itemIndex % checkpointInterval === 0;
+          const stepKey = shouldCheckpoint ? `stream-foreach:${namespace}:pos-${itemPosition}` : void 0;
+          const stepId = stepKey ?? `stream-item-${itemPosition}`;
+          const stepResult = await cachedStepFn(
+            stepId,
+            () => processor(item, itemIndex),
+            { key: stepKey }
+          );
+          return { index: itemIndex, position: itemPosition, result: stepResult };
+        };
+        if (isStreamReader(source)) {
+          if (concurrency <= 1) {
+            let itemPosition = source.position;
+            let readResult = await source.read();
+            while (readResult.ok) {
+              const item = readResult.value;
+              const { result: result2 } = await processItem(item, processedCount, itemPosition, source.namespace);
+              results.push(result2);
+              lastPosition = itemPosition;
+              processedCount++;
+              itemPosition = source.position;
+              readResult = await source.read();
+            }
+          } else {
+            const resultsMap = /* @__PURE__ */ new Map();
+            let itemIndex = 0;
+            let totalItems = 0;
+            const slots = new Array(concurrency).fill(null);
+            const getSlot = async () => {
+              for (let i = 0; i < slots.length; i++) {
+                if (slots[i] === null) return i;
+              }
+              const activePromises = slots.filter((s) => s !== null);
+              const completed = await Promise.race(activePromises);
+              resultsMap.set(completed.index, { position: completed.position, result: completed.result });
+              slots[completed.slotIndex] = null;
+              return completed.slotIndex;
+            };
+            let itemPosition = source.position;
+            let readResult = await source.read();
+            while (readResult.ok) {
+              const slotIndex = await getSlot();
+              const currentIndex = itemIndex;
+              const currentPosition = itemPosition;
+              const currentItem = readResult.value;
+              const currentSlot = slotIndex;
+              slots[slotIndex] = processItem(currentItem, currentIndex, currentPosition, source.namespace).then((r) => ({ slotIndex: currentSlot, ...r }));
+              totalItems++;
+              itemIndex++;
+              itemPosition = source.position;
+              readResult = await source.read();
+            }
+            for (let i = 0; i < slots.length; i++) {
+              if (slots[i] !== null) {
+                const result2 = await slots[i];
+                resultsMap.set(result2.index, { position: result2.position, result: result2.result });
+              }
+            }
+            for (let i = 0; i < totalItems; i++) {
+              const entry = resultsMap.get(i);
+              if (entry) {
+                results.push(entry.result);
+                lastPosition = entry.position;
+                processedCount++;
+              }
+            }
+          }
+        } else {
+          if (concurrency <= 1) {
+            let index = 0;
+            for await (const item of source) {
+              const { result: result2 } = await processItem(item, index, index, "async-iterable");
+              results.push(result2);
+              lastPosition = index;
+              processedCount++;
+              index++;
+            }
+          } else {
+            const resultsMap = /* @__PURE__ */ new Map();
+            let itemIndex = 0;
+            let totalItems = 0;
+            const slots = new Array(concurrency).fill(null);
+            const getSlot = async () => {
+              for (let i = 0; i < slots.length; i++) {
+                if (slots[i] === null) return i;
+              }
+              const activePromises = slots.filter((s) => s !== null);
+              const completed = await Promise.race(activePromises);
+              resultsMap.set(completed.index, completed.result);
+              slots[completed.slotIndex] = null;
+              return completed.slotIndex;
+            };
+            for await (const item of source) {
+              const slotIndex = await getSlot();
+              const currentIndex = itemIndex;
+              const currentSlot = slotIndex;
+              slots[slotIndex] = processItem(item, currentIndex, currentIndex, "async-iterable").then((r) => ({ slotIndex: currentSlot, ...r }));
+              totalItems++;
+              itemIndex++;
+            }
+            for (let i = 0; i < slots.length; i++) {
+              if (slots[i] !== null) {
+                const result2 = await slots[i];
+                resultsMap.set(result2.index, result2.result);
+              }
+            }
+            for (let i = 0; i < totalItems; i++) {
+              if (resultsMap.has(i)) {
+                results.push(resultsMap.get(i));
+                lastPosition = i;
+                processedCount++;
+              }
+            }
+          }
+        }
+        return {
+          results,
+          processedCount,
+          lastPosition
+        };
+      };
+      cachedStepFn.if = realStep.if;
+      cachedStepFn.label = realStep.label;
+      cachedStepFn.branch = realStep.branch;
+      cachedStepFn.arm = realStep.arm;
+      cachedStepFn.forEach = realStep.forEach;
+      cachedStepFn.item = realStep.item;
+      cachedStepFn.dep = realStep.dep;
+      cachedStepFn.workflow = (id, getter, options2) => cachedStepFn(id, getter, options2);
+      cachedStepFn.all = (id, shape, options2) => {
+        const opts = options2 !== void 0 && Object.prototype.hasOwnProperty.call(options2, "key") ? options2 : { ...options2, key: void 0 };
+        return cachedStepFn(id, async () => ok2(await realStep.all(id, shape)), opts);
+      };
+      cachedStepFn.map = (id, items, mapper, options2) => {
+        const opts = options2 !== void 0 && Object.prototype.hasOwnProperty.call(options2, "key") ? options2 : { ...options2, key: void 0 };
+        return cachedStepFn(id, async () => ok2(await realStep.map(id, items, mapper, options2)), opts);
+      };
+      return cachedStepFn;
+    };
+    const wrappedFn = ({ step }) => {
+      const cachedStep = createCachedStep(step);
+      return userFn({
+        step: cachedStep,
+        steps: bindSteps(effectiveDeps ?? {}, cachedStep),
+        deps: effectiveDeps,
+        ctx: workflowContext
+      });
+    };
+    let result;
+    try {
+      result = await run(wrappedFn, {
+        onError: onErrorHandler,
+        onEvent: onEventHandler,
+        catchUnexpected,
+        workflowId,
+        workflowName,
+        context,
+        graph: declaredGraph,
+        _workflowSignal: workflowSignal
+      });
+    } finally {
+      if (workflowSignal) {
+        workflowSignal.removeEventListener("abort", abortHandler);
+      }
+    }
+    if (!result.ok && compensations.length > 0) {
+      const compensationErrors = [];
+      for (let i = compensations.length - 1; i >= 0; i--) {
+        const comp = compensations[i];
+        try {
+          await comp.compensate(comp.value);
+        } catch (compErr) {
+          compensationErrors.push({ stepName: comp.stepName, error: compErr });
+        }
+      }
+      if (compensationErrors.length > 0) {
+        const sagaError = {
+          type: "SAGA_COMPENSATION_ERROR",
+          originalError: result.error,
+          compensationErrors
+        };
+        result = err(sagaError, { cause: result.cause });
+      }
+    }
+    const durationMs = performance.now() - startTime;
+    if (!result.ok) {
+      let cancelledError;
+      if (isWorkflowCancelled(result.cause)) {
+        cancelledError = result.cause;
+      }
+      if (!cancelledError && abortedDuringExecution && isUnexpectedError(result.error)) {
+        const thrown = result.cause;
+        const isAbortError = thrown != null && typeof thrown === "object" && "name" in thrown && thrown.name === "AbortError";
+        if (isAbortError) {
+          const reason = abortReason ?? (typeof workflowSignal?.reason === "string" ? workflowSignal.reason : workflowSignal?.reason instanceof Error ? workflowSignal.reason.message : void 0);
+          cancelledError = {
+            type: "WORKFLOW_CANCELLED",
+            reason,
+            lastStepKey
+          };
+        }
+      }
+      if (cancelledError) {
+        emitEvent({
+          type: "workflow_cancelled",
+          workflowId,
+          ts: Date.now(),
+          durationMs,
+          reason: cancelledError.reason,
+          lastStepKey: cancelledError.lastStepKey
+        });
+        if (cancelledError && !isWorkflowCancelled(result.cause)) {
+          return err(result.error, { cause: cancelledError });
+        }
+        return result;
+      }
+    }
+    if (result.ok && abortedDuringExecution) {
+      const reason = abortReason ?? (typeof workflowSignal?.reason === "string" ? workflowSignal.reason : workflowSignal?.reason instanceof Error ? workflowSignal.reason.message : void 0);
+      emitEvent({
+        type: "workflow_cancelled",
+        workflowId,
+        ts: Date.now(),
+        durationMs,
+        reason,
+        lastStepKey
+      });
+      const cancelledError = {
+        type: "WORKFLOW_CANCELLED",
+        reason,
+        lastStepKey
+      };
+      return err(catchUnexpected(cancelledError), { cause: cancelledError });
+    }
+    if (result.ok) {
+      emitEvent({
+        type: "workflow_success",
+        workflowId,
+        ts: Date.now(),
+        durationMs
+      });
+    } else {
+      emitEvent({
+        type: "workflow_error",
+        workflowId,
+        ts: Date.now(),
+        durationMs,
+        error: result.error
+      });
+    }
+    return result;
+  }
+  function runMethod(fnOrName, maybeFnOrConfig, maybeConfig) {
+    let runName;
+    let fn;
+    let config;
+    if (typeof fnOrName === "string") {
+      runName = fnOrName;
+      fn = maybeFnOrConfig;
+      config = maybeConfig;
+    } else {
+      fn = fnOrName;
+      config = maybeFnOrConfig;
+    }
+    return internalExecute(runName, fn, config);
+  }
+  async function runWithStateMethod(fnOrName, maybeFnOrConfig, maybeConfig) {
+    let runName;
+    let fn;
+    let config;
+    if (typeof fnOrName === "string") {
+      runName = fnOrName;
+      fn = maybeFnOrConfig;
+      config = maybeConfig;
+    } else {
+      fn = fnOrName;
+      config = maybeFnOrConfig;
+    }
+    const collector = createResumeStateCollector();
+    const userOnEvent = config?.onEvent;
+    const mergedOnEvent = (event, ctx) => {
+      collector.handleEvent(event);
+      try {
+        userOnEvent?.(event, ctx);
+      } catch {
+      }
+    };
+    const mergedConfig = {
+      ...config,
+      onEvent: mergedOnEvent
+    };
+    let result;
+    let resumeState;
+    try {
+      result = await internalExecute(runName, fn, mergedConfig);
+    } catch (thrown) {
+      const catchUnexpected = optionsActual?.catchUnexpected ?? defaultCatchUnexpected;
+      result = err(catchUnexpected(thrown), { cause: thrown });
+    } finally {
+      resumeState = collector.getResumeState();
+    }
+    return { result, resumeState };
+  }
+  const workflow = {
+    withDeps: (overrides) => withDeps(workflow, overrides),
+    run: runMethod,
+    runWithState: runWithStateMethod
+  };
+  return workflow;
+}
+
+// src/durable/index.ts
+var defaultStore;
+function createMemorySnapshotStore() {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    async save(id, snapshot) {
+      store.set(id, { snapshot, updatedAt: /* @__PURE__ */ new Date() });
+    },
+    async load(id) {
+      const entry = store.get(id);
+      return entry?.snapshot ?? null;
+    },
+    async delete(id) {
+      store.delete(id);
+    },
+    async list(options) {
+      const prefix = options?.prefix ?? "";
+      const limit = options?.limit ?? 100;
+      const results = [];
+      for (const [id, entry] of store.entries()) {
+        if (prefix && !id.startsWith(prefix)) continue;
+        results.push({ id, updatedAt: entry.updatedAt.toISOString() });
+        if (results.length >= limit) break;
+      }
+      results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+      return results;
+    },
+    async close() {
+    }
+  };
+}
+function getDefaultStore() {
+  if (defaultStore === void 0) {
+    defaultStore = createMemorySnapshotStore();
+  }
+  return defaultStore;
+}
+function hasWorkflowLock(store) {
+  return typeof store.tryAcquire === "function" && typeof store.release === "function";
+}
+var activeWorkflows = /* @__PURE__ */ new Set();
+var pendingIdempotencyRuns = /* @__PURE__ */ new Map();
+var durable = {
+  /**
+   * Execute a workflow with automatic state persistence.
+   *
+   * Features:
+   * - **Automatic checkpointing**: State is saved after each keyed step
+   * - **Crash recovery**: Resume from the last completed step on restart
+   * - **Version checking**: Reject resume if workflow logic version changed
+   * - **Concurrency control**: Prevent duplicate executions of the same workflow ID
+   * - **Cancellation support**: Integrates with AbortSignal for graceful shutdown
+   *
+   * ## How It Works
+   *
+   * 1. On start: Load existing state from store (if any)
+   * 2. Check version compatibility (reject if mismatch)
+   * 3. Pre-populate cache from loaded state (skip completed steps)
+   * 4. Execute workflow, persisting state after each keyed step
+   * 5. On completion: Delete stored state (clean up)
+   * 6. On error/cancellation: State remains for future resume
+   *
+   * ## Important Notes
+   *
+   * - **Only keyed steps are durable**: Use `{ key: 'step-name' }` option
+   * - **Steps should be idempotent**: They may be retried on resume
+   * - **Serialization**: State is JSON-serialized; complex objects may lose fidelity
+   *
+   * @param deps - Workflow dependencies (Result-returning functions)
+   * @param fn - Workflow function receiving ({ step, deps, ctx })
+   * @param options - Durable execution options
+   * @returns AsyncResult with workflow result or error
+   *
+   * @example
+   * ```typescript
+   * import { durable } from 'awaitly/durable';
+   *
+   * // Zero-config: uses in-memory store (per process)
+   * const result = await durable.run(
+   *   { fetchUser, createOrder, sendEmail },
+   *   async ({ step, deps: { fetchUser, createOrder, sendEmail } }) => {
+   *     const user = await step(() => fetchUser('123'), { key: 'fetch-user' });
+   *     const order = await step(() => createOrder(user), { key: 'create-order' });
+   *     await step(() => sendEmail(order), { key: 'send-email' });
+   *     return order;
+   *   },
+   *   { id: 'checkout-123' }
+   * );
+   *
+   * // Persistence across restarts: pass a store adapter
+   * import { postgres } from 'awaitly-postgres'; // or awaitly-mongo, awaitly-libsql
+   * const store = postgres(process.env.DATABASE_URL);
+   * await durable.run(deps, fn, { id: 'checkout-123', store });
+   *
+   * if (result.ok) {
+   *   console.log('Order completed:', result.value);
+   * } else if (isWorkflowCancelled(result.error)) {
+   *   console.log('Workflow cancelled at:', result.error.lastStepKey);
+   * }
+   * ```
+   */
+  async run(deps, fn, options) {
+    const {
+      id,
+      store: storeOption,
+      version = 1,
+      allowConcurrent = false,
+      lockTtlMs = 6e4,
+      heartbeatIntervalMs,
+      abortOnLeaseLoss,
+      metadata,
+      signal,
+      createContext,
+      onEvent,
+      onError,
+      onVersionMismatch,
+      idempotencyKey,
+      input
+    } = options;
+    const effectiveStore = storeOption ?? getDefaultStore();
+    let resolveIdempotencyRun;
+    if (idempotencyKey) {
+      const idemId = `idem:${idempotencyKey}`;
+      const pending = pendingIdempotencyRuns.get(idemId);
+      if (pending) {
+        return await pending;
+      }
+      pendingIdempotencyRuns.set(idemId, new Promise((r) => {
+        resolveIdempotencyRun = r;
+      }));
+      try {
+        const idemSnapshot = await effectiveStore.load(idemId);
+        if (idemSnapshot) {
+          if (input !== void 0 && idemSnapshot.metadata?.input !== void 0) {
+            const storedInput = JSON.stringify(idemSnapshot.metadata.input);
+            const currentInput = JSON.stringify(input);
+            if (storedInput !== currentInput) {
+              const result = err({
+                type: "IDEMPOTENCY_CONFLICT",
+                idempotencyKey,
+                workflowId: id,
+                message: `Idempotency key '${idempotencyKey}' already used with different input for workflow '${id}'.`
+              });
+              resolveIdempotencyRun(result);
+              pendingIdempotencyRuns.delete(idemId);
+              resolveIdempotencyRun = void 0;
+              return result;
+            }
+          }
+          if (idemSnapshot.execution.status === "completed" && idemSnapshot.metadata?.finalResult !== void 0) {
+            const result = idemSnapshot.metadata.finalResult;
+            resolveIdempotencyRun(result);
+            pendingIdempotencyRuns.delete(idemId);
+            resolveIdempotencyRun = void 0;
+            return result;
+          }
+          if (idemSnapshot.execution.status === "running") {
+            const result = err({
+              type: "CONCURRENT_EXECUTION",
+              workflowId: id,
+              message: `Workflow '${id}' with idempotency key '${idempotencyKey}' is already running.`,
+              reason: "cross-process"
+            });
+            resolveIdempotencyRun(result);
+            pendingIdempotencyRuns.delete(idemId);
+            resolveIdempotencyRun = void 0;
+            return result;
+          }
+        }
+      } catch {
+      }
+      try {
+        await effectiveStore.save(idemId, {
+          formatVersion: 1,
+          steps: {},
+          execution: {
+            status: "running",
+            lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          metadata: {
+            workflowId: id,
+            idempotencyKey,
+            input
+          }
+        });
+      } catch {
+      }
+    }
+    if (!allowConcurrent && activeWorkflows.has(id)) {
+      const error = {
+        type: "CONCURRENT_EXECUTION",
+        workflowId: id,
+        message: `Workflow '${id}' is already running. Set allowConcurrent: true to allow parallel executions.`,
+        reason: "in-process"
+      };
+      return err(error);
+    }
+    let leaseOwnerToken = null;
+    if (!allowConcurrent && hasWorkflowLock(effectiveStore)) {
+      let lease;
+      try {
+        lease = await effectiveStore.tryAcquire(id, { ttlMs: lockTtlMs });
+      } catch (lockError) {
+        const error = {
+          type: "PERSISTENCE_ERROR",
+          operation: "load",
+          workflowId: id,
+          cause: lockError,
+          message: `Failed to acquire lock for workflow '${id}': ${lockError instanceof Error ? lockError.message : String(lockError)}`
+        };
+        return err(error);
+      }
+      if (lease === null) {
+        const error = {
+          type: "CONCURRENT_EXECUTION",
+          workflowId: id,
+          message: `Workflow '${id}' is already running (lease held by another process). Set allowConcurrent: true to allow parallel executions.`,
+          reason: "cross-process"
+        };
+        return err(error);
+      }
+      leaseOwnerToken = lease.ownerToken;
+    }
+    let heartbeatTimer;
+    let leaseAbortController;
+    const lockStore = effectiveStore;
+    if (leaseOwnerToken && typeof lockStore.renew === "function") {
+      const heartbeatMs = heartbeatIntervalMs ?? Math.floor(lockTtlMs / 3);
+      leaseAbortController = new AbortController();
+      heartbeatTimer = setInterval(async () => {
+        try {
+          const renewed = await lockStore.renew(id, leaseOwnerToken, { ttlMs: lockTtlMs });
+          if (!renewed) {
+            leaseAbortController.abort(new Error("Lease expired"));
+          }
+        } catch {
+          leaseAbortController.abort(new Error("Lease renewal failed"));
+        }
+      }, heartbeatMs);
+    }
+    activeWorkflows.add(id);
+    let durableResult;
+    try {
+      let existingSnapshot = null;
+      try {
+        existingSnapshot = await effectiveStore.load(id);
+      } catch (loadError) {
+        const error = {
+          type: "PERSISTENCE_ERROR",
+          operation: "load",
+          workflowId: id,
+          cause: loadError,
+          message: `Failed to load state for workflow '${id}': ${loadError instanceof Error ? loadError.message : String(loadError)}`
+        };
+        durableResult = err(error);
+        return err(error);
+      }
+      if (existingSnapshot) {
+        try {
+          assertValidSnapshot(existingSnapshot);
+        } catch (validationError) {
+          if (validationError instanceof SnapshotFormatError) {
+            const error = {
+              type: "PERSISTENCE_ERROR",
+              operation: "load",
+              workflowId: id,
+              cause: validationError,
+              message: `Invalid snapshot format for workflow '${id}': ${validationError.message}`
+            };
+            durableResult = err(error);
+            return err(error);
+          }
+          throw validationError;
+        }
+      }
+      if (existingSnapshot) {
+        const storedVersion = typeof existingSnapshot.metadata?.version === "number" ? existingSnapshot.metadata.version : 1;
+        if (storedVersion !== version) {
+          const error = {
+            type: "VERSION_MISMATCH",
+            workflowId: id,
+            storedVersion,
+            requestedVersion: version,
+            currentVersion: version,
+            message: `Workflow '${id}' has stored state at version ${storedVersion} but this run requested version ${version}. Migrate the stored state to the new version, or clear state for this id (e.g. durable.deleteState(store, '${id}')) and re-run.`
+          };
+          if (!onVersionMismatch) {
+            durableResult = err(error);
+            return err(error);
+          }
+          const resolution = await Promise.resolve(
+            onVersionMismatch({ id, storedVersion, requestedVersion: version })
+          );
+          if (resolution === "throw") {
+            durableResult = err(error);
+            return err(error);
+          }
+          if (resolution === "clear") {
+            try {
+              await effectiveStore.delete(id);
+            } catch {
+            }
+            existingSnapshot = null;
+          } else {
+            existingSnapshot = resolution.migratedSnapshot;
+          }
+        }
+      }
+      const emitDurableEvent = (event, ctx) => {
+        if (onEvent) {
+          onEvent(event, ctx);
+        }
+      };
+      const resumeCollector = createResumeStateCollector();
+      const workflowOptions = {
+        // Restore from existing snapshot
+        snapshot: existingSnapshot,
+        // Persist after each keyed step
+        onAfterStep: async (stepKey, result2, wfId, ctx) => {
+          try {
+            const collectedState = resumeCollector.getResumeState();
+            const steps = {};
+            for (const [key, entry] of collectedState.steps) {
+              if (entry.result.ok) {
+                steps[key] = { ok: true, value: entry.result.value };
+              } else {
+                const cause = entry.result.cause;
+                const serializedCause = cause instanceof Error ? serializeError(cause) : serializeThrown(cause);
+                const origin = entry.meta?.origin === "throw" ? "throw" : "result";
+                steps[key] = {
+                  ok: false,
+                  error: entry.result.error,
+                  cause: serializedCause,
+                  meta: { origin }
+                };
+              }
+            }
+            const currentSnapshot = {
+              formatVersion: 1,
+              workflowName: id,
+              steps,
+              execution: {
+                status: "running",
+                lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+                currentStepId: stepKey
+              },
+              metadata: {
+                ...existingSnapshot?.metadata ?? {},
+                ...metadata,
+                version,
+                lastStepKey: stepKey
+              }
+            };
+            let snapshotToSave = existingSnapshot ? mergeSnapshots(existingSnapshot, currentSnapshot) : currentSnapshot;
+            if (snapshotToSave.warnings && snapshotToSave.warnings.length > 0) {
+              const currentStepKeys = new Set(Object.keys(currentSnapshot.steps));
+              const filtered = snapshotToSave.warnings.filter(
+                (w) => !currentStepKeys.has(w.stepId)
+              );
+              snapshotToSave = {
+                ...snapshotToSave,
+                warnings: filtered.length > 0 ? filtered : void 0
+              };
+            }
+            await effectiveStore.save(id, snapshotToSave);
+            emitDurableEvent(
+              {
+                type: "persist_success",
+                workflowId: wfId,
+                stepKey,
+                ts: Date.now(),
+                context: ctx
+              },
+              ctx
+            );
+          } catch (persistError) {
+            emitDurableEvent(
+              {
+                type: "persist_error",
+                workflowId: wfId,
+                stepKey,
+                error: persistError,
+                ts: Date.now(),
+                context: ctx
+              },
+              ctx
+            );
+          }
+        },
+        // Forward events and collect step results for snapshot building
+        onEvent: (event, ctx) => {
+          resumeCollector.handleEvent(event);
+          emitDurableEvent(event, ctx);
+        },
+        onError,
+        signal: leaseAbortController && signal ? AbortSignal.any([signal, leaseAbortController.signal]) : leaseAbortController?.signal ?? signal,
+        createContext
+      };
+      let workflowInstance;
+      try {
+        workflowInstance = createWorkflow(id, deps, workflowOptions);
+      } catch (createError) {
+        if (createError instanceof SnapshotFormatError) {
+          const error = {
+            type: "PERSISTENCE_ERROR",
+            operation: "load",
+            workflowId: id,
+            cause: createError,
+            message: `Invalid snapshot format for workflow '${id}': ${createError.message}`
+          };
+          durableResult = err(error);
+          return err(error);
+        }
+        throw createError;
+      }
+      let result;
+      try {
+        result = await workflowInstance.run(fn);
+      } catch (runError) {
+        if (runError instanceof SnapshotFormatError || runError instanceof SnapshotDecodeError) {
+          const error = {
+            type: "PERSISTENCE_ERROR",
+            operation: "load",
+            workflowId: id,
+            cause: runError,
+            message: `Invalid snapshot format for workflow '${id}': ${runError.message}`
+          };
+          durableResult = err(error);
+          return err(error);
+        }
+        throw runError;
+      }
+      if (abortOnLeaseLoss !== false && leaseAbortController?.signal.aborted) {
+        const leaseErr = err({
+          type: "LEASE_EXPIRED",
+          workflowId: id,
+          message: `Lease expired for workflow '${id}' during execution. The workflow may have been reclaimed by another process.`
+        });
+        durableResult = leaseErr;
+        return leaseErr;
+      }
+      if (result.ok) {
+        try {
+          await effectiveStore.delete(id);
+        } catch (deleteError) {
+          const error = {
+            type: "PERSISTENCE_ERROR",
+            operation: "delete",
+            workflowId: id,
+            cause: deleteError,
+            message: `Failed to delete state for workflow '${id}': ${deleteError instanceof Error ? deleteError.message : String(deleteError)}`
+          };
+          durableResult = err(error);
+          return err(error);
+        }
+        if (idempotencyKey) {
+          const idemId = `idem:${idempotencyKey}`;
+          try {
+            await effectiveStore.save(idemId, {
+              formatVersion: 1,
+              steps: {},
+              execution: {
+                status: "completed",
+                lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+                completedAt: (/* @__PURE__ */ new Date()).toISOString()
+              },
+              metadata: {
+                workflowId: id,
+                idempotencyKey,
+                input,
+                finalResult: result
+              }
+            });
+          } catch {
+          }
+        }
+      }
+      durableResult = result;
+      return result;
+    } finally {
+      activeWorkflows.delete(id);
+      if (resolveIdempotencyRun) {
+        resolveIdempotencyRun(durableResult);
+        pendingIdempotencyRuns.delete(`idem:${idempotencyKey}`);
+      }
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+      }
+      if (leaseOwnerToken !== null && hasWorkflowLock(effectiveStore)) {
+        try {
+          await effectiveStore.release(id, leaseOwnerToken);
+        } catch {
+        }
+      }
+    }
+  },
+  /**
+   * Clear all persisted workflow state from the store.
+   * Use for admin/testing. If the store implements `clear()`, that is used;
+   * otherwise clears by listing and deleting in pages.
+   *
+   * @param store - Snapshot store
+   */
+  async clearState(store) {
+    const storeWithClear = store;
+    if (typeof storeWithClear.clear === "function") {
+      await storeWithClear.clear();
+      return;
+    }
+    const limit = 100;
+    for (; ; ) {
+      const entries = await store.list({ limit });
+      if (entries.length === 0) break;
+      const ids = entries.map((e) => e.id);
+      await this.deleteStates(store, ids, { continueOnError: true });
+      if (entries.length < limit) break;
+    }
+  },
+  /**
+   * Check if a workflow ID has persisted state (can be resumed).
+   *
+   * @param store - Snapshot store
+   * @param id - Workflow execution ID
+   * @returns `true` if state exists, `false` otherwise (including on store errors)
+   */
+  async hasState(store, id) {
+    try {
+      const snapshot = await store.load(id);
+      return snapshot !== null;
+    } catch {
+      return false;
+    }
+  },
+  /**
+   * Delete persisted state for a workflow (cancel resume capability).
+   * Deleting is effectively an ack/reset: the workflow can no longer resume from that state.
+   * If you delete while a run is in flight, the run continues; on success it may delete again (no-op) or save (recreating state).
+   * For multi-worker safety, prefer deleting only when the workflow is not running or when you hold the lock.
+   *
+   * @param store - Snapshot store
+   * @param id - Workflow execution ID
+   * @returns `true` on success, `false` on store errors
+   */
+  async deleteState(store, id) {
+    try {
+      await store.delete(id);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  /**
+   * Bulk delete persisted state for multiple workflow IDs (best-effort).
+   * Use for admin/cleanup. Deletes in a loop with optional concurrency.
+   *
+   * @param store - Snapshot store
+   * @param ids - Workflow execution IDs to delete
+   * @param options - Optional concurrency and error handling
+   * @returns Count of deleted entries and any errors when continueOnError is true
+   */
+  async deleteStates(store, ids, options = {}) {
+    const { concurrency = 10, continueOnError = true } = options;
+    if (ids.length === 0) {
+      return { deleted: 0 };
+    }
+    const errors = [];
+    let deleted = 0;
+    const run2 = async (id) => {
+      try {
+        await store.delete(id);
+        deleted++;
+      } catch (error) {
+        if (continueOnError) errors.push({ id, error });
+        else throw error;
+      }
+    };
+    const limit = Math.max(1, concurrency);
+    for (let i = 0; i < ids.length; i += limit) {
+      const batch = ids.slice(i, i + limit);
+      await Promise.all(batch.map((id) => run2(id)));
+    }
+    return errors.length > 0 ? { deleted, errors } : { deleted };
+  },
+  /**
+   * List workflow IDs with persisted state.
+   *
+   * @param store - Snapshot store
+   * @param options - Optional prefix and limit
+   * @returns Array of { id, updatedAt } entries
+   */
+  async listPending(store, options) {
+    try {
+      return await store.list(options);
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/engine/index.ts
+function createEngine(options) {
+  const {
+    store,
+    workflows,
+    concurrency = 5,
+    onEvent,
+    onError
+  } = options;
+  const schedules = /* @__PURE__ */ new Map();
+  let pollTimer;
+  let running = false;
+  let tickInFlight = false;
+  function emit(event) {
+    try {
+      onEvent?.(event);
+    } catch {
+    }
+  }
+  async function enqueue(name, opts) {
+    const wf = workflows[name];
+    if (!wf) {
+      throw new Error(`Unknown workflow: '${name}'. Registered: ${Object.keys(workflows).join(", ")}`);
+    }
+    const id = opts?.id ?? `${name}:${(0, import_node_crypto.randomUUID)()}`;
+    const snapshot = {
+      formatVersion: 1,
+      workflowName: name,
+      steps: {},
+      execution: {
+        status: "running",
+        // "running" so durable.run can resume it
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      metadata: {
+        engineState: "queued",
+        workflowName: name,
+        input: opts?.input ?? null,
+        idempotencyKey: opts?.idempotencyKey,
+        enqueuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        ...opts?.metadata
+      }
+    };
+    await store.save(id, snapshot);
+    emit({ type: "workflow_enqueued", workflowName: name, id, ts: Date.now() });
+    return id;
+  }
+  async function tick() {
+    if (tickInFlight) return 0;
+    tickInFlight = true;
+    try {
+      const entries = await store.list({ limit: concurrency * 2 });
+      let processed = 0;
+      const queued = [];
+      for (const entry of entries) {
+        if (queued.length >= concurrency) break;
+        const snapshot = await store.load(entry.id);
+        if (snapshot && snapshot.metadata?.engineState === "queued" && typeof snapshot.metadata?.workflowName === "string") {
+          queued.push({ id: entry.id, workflowName: snapshot.metadata.workflowName, snapshot });
+        }
+      }
+      const results = await Promise.allSettled(
+        queued.map(async ({ id, workflowName, snapshot }) => {
+          const wf = workflows[workflowName];
+          if (!wf) return;
+          const processingSnapshot = {
+            ...snapshot,
+            metadata: {
+              ...snapshot.metadata,
+              engineState: "processing"
+            }
+          };
+          await store.save(id, processingSnapshot);
+          emit({ type: "workflow_started", workflowName, id, ts: Date.now() });
+          const result = await durable.run(wf.deps, wf.fn, {
+            id,
+            store,
+            idempotencyKey: snapshot.metadata?.idempotencyKey,
+            input: snapshot.metadata?.input,
+            ...wf.durableDefaults
+          });
+          if (result.ok) {
+            emit({ type: "workflow_completed", workflowName, id, ts: Date.now() });
+          } else {
+            emit({ type: "workflow_failed", workflowName, id, error: result.error, ts: Date.now() });
+          }
+          processed++;
+        })
+      );
+      for (const r of results) {
+        if (r.status === "rejected") {
+          try {
+            onError?.(r.reason);
+          } catch {
+          }
+        }
+      }
+      emit({ type: "engine_tick", ts: Date.now(), processed });
+      return processed;
+    } finally {
+      tickInFlight = false;
+    }
+  }
+  function schedule(name, opts) {
+    const scheduleId = opts?.id ? `schedule:${opts.id}` : `schedule:${(0, import_node_crypto.randomUUID)()}`;
+    if (opts.immediate) {
+      void enqueue(name, opts).catch((e) => {
+        try {
+          onError?.(e);
+        } catch {
+        }
+      });
+    }
+    const interval = setInterval(() => {
+      void enqueue(name, opts).catch((e) => {
+        try {
+          onError?.(e);
+        } catch {
+        }
+      });
+    }, opts.intervalMs);
+    schedules.set(scheduleId, interval);
+    emit({ type: "schedule_created", workflowName: name, scheduleId, intervalMs: opts.intervalMs, ts: Date.now() });
+    return scheduleId;
+  }
+  function unschedule(scheduleId) {
+    const interval = schedules.get(scheduleId);
+    if (!interval) return false;
+    clearInterval(interval);
+    schedules.delete(scheduleId);
+    emit({ type: "schedule_removed", scheduleId, ts: Date.now() });
+    return true;
+  }
+  function start(pollIntervalMs = 1e3) {
+    if (running) return;
+    running = true;
+    emit({ type: "engine_start", ts: Date.now() });
+    void tick().catch((e) => {
+      try {
+        onError?.(e);
+      } catch {
+      }
+    });
+    pollTimer = setInterval(() => {
+      void tick().catch((e) => {
+        try {
+          onError?.(e);
+        } catch {
+        }
+      });
+    }, pollIntervalMs);
+  }
+  async function stop() {
+    if (!running) return;
+    running = false;
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = void 0;
+    }
+    for (const [id, interval] of schedules) {
+      clearInterval(interval);
+      schedules.delete(id);
+    }
+    while (tickInFlight) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    emit({ type: "engine_stop", ts: Date.now() });
+  }
+  return {
+    enqueue,
+    schedule,
+    unschedule,
+    start,
+    stop,
+    tick,
+    status: () => ({ running, pendingSchedules: schedules.size })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createEngine
+});
+//# sourceMappingURL=engine.cjs.map