@dudousxd/nestjs-durable-core 0.46.1 → 0.48.0

package/dist/index.js

@@ -156,6 +156,218 @@ var InMemoryAdmissionBackend = class {
   }
 };
 
+// src/ambient-ctx.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var STORAGE_KEY = Symbol.for("nestjs-durable:ambient-workflow-ctx");
+var globalRef = globalThis;
+if (!globalRef[STORAGE_KEY]) {
+  globalRef[STORAGE_KEY] = new AsyncLocalStorage();
+}
+var storage = globalRef[STORAGE_KEY];
+function runInWorkflowCtx(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+__name(runInWorkflowCtx, "runInWorkflowCtx");
+function currentWorkflowCtx() {
+  return storage.getStore();
+}
+__name(currentWorkflowCtx, "currentWorkflowCtx");
+
+// src/errors.ts
+var FatalError = class extends Error {
+  static {
+    __name(this, "FatalError");
+  }
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "FatalError";
+    this.code = code;
+  }
+};
+var SingletonQueueFullError = class extends Error {
+  static {
+    __name(this, "SingletonQueueFullError");
+  }
+  workflow;
+  key;
+  maxQueueDepth;
+  constructor(workflow, key, maxQueueDepth) {
+    super(`singleton queue for ${workflow} key "${key}" is full (maxQueueDepth=${maxQueueDepth}); retry later`);
+    this.name = "SingletonQueueFullError";
+    this.workflow = workflow;
+    this.key = key;
+    this.maxQueueDepth = maxQueueDepth;
+  }
+};
+var SignalTimeoutError = class extends Error {
+  static {
+    __name(this, "SignalTimeoutError");
+  }
+  token;
+  timeoutMs;
+  constructor(token, timeoutMs) {
+    super(`timed out after ${timeoutMs}ms waiting for signal "${token}"`);
+    this.name = "SignalTimeoutError";
+    this.token = token;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var RemoteStepTimeout = class extends Error {
+  static {
+    __name(this, "RemoteStepTimeout");
+  }
+  stepId;
+  timeoutMs;
+  constructor(stepId2, timeoutMs) {
+    super(`remote step ${stepId2} produced no result/heartbeat within ${timeoutMs}ms`);
+    this.name = "RemoteStepTimeout";
+    this.stepId = stepId2;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var RemoteWorkflowTimeout = class extends Error {
+  static {
+    __name(this, "RemoteWorkflowTimeout");
+  }
+  taskId;
+  timeoutMs;
+  constructor(taskId, timeoutMs) {
+    super(`remote workflow task ${taskId} produced no decision within ${timeoutMs}ms \u2014 presumed dropped; re-driving via recovery`);
+    this.name = "RemoteWorkflowTimeout";
+    this.taskId = taskId;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var NonDeterminismError = class extends Error {
+  static {
+    __name(this, "NonDeterminismError");
+  }
+  runId;
+  seq;
+  constructor(runId, seq, expected, recorded) {
+    super(`non-determinism at ${runId}#${seq}: code expects "${expected}" but history recorded "${recorded}". The workflow changed under an in-flight run \u2014 register a new @Workflow version.`);
+    this.name = "NonDeterminismError";
+    this.runId = runId;
+    this.seq = seq;
+  }
+};
+var GatherError = class extends Error {
+  static {
+    __name(this, "GatherError");
+  }
+  failures;
+  constructor(failures, total) {
+    const ids = failures.map((f) => f.id).join(", ");
+    const denom = total ?? failures.length;
+    super(`ctx.all: ${failures.length} of ${denom} child(ren) failed: ${ids}`);
+    this.name = "GatherError";
+    this.failures = failures;
+  }
+};
+var WorkflowSuspended = class extends Error {
+  static {
+    __name(this, "WorkflowSuspended");
+  }
+  /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
+  wakeAt;
+  constructor(wakeAt) {
+    super("workflow suspended");
+    this.name = "WorkflowSuspended";
+    this.wakeAt = wakeAt;
+  }
+};
+var ContinueAsNew = class extends Error {
+  static {
+    __name(this, "ContinueAsNew");
+  }
+  input;
+  constructor(input) {
+    super("workflow continued as new"), this.input = input;
+    this.name = "ContinueAsNew";
+  }
+};
+
+// src/workflow-ref.ts
+var WORKFLOW_NAME_KEY = Symbol.for("nestjs-durable:workflow-name");
+function workflowName(ref) {
+  if (typeof ref === "string") return ref;
+  const name = ref[WORKFLOW_NAME_KEY];
+  if (!name) {
+    throw new Error(`workflow class ${ref.name} has no registered name \u2014 is it decorated with @Workflow({ name })?`);
+  }
+  return name;
+}
+__name(workflowName, "workflowName");
+
+// src/durable-workflow.ts
+var BINDINGS_KEY = Symbol.for("nestjs-durable:workflow-class-bindings");
+var globalRef2 = globalThis;
+if (!globalRef2[BINDINGS_KEY]) {
+  globalRef2[BINDINGS_KEY] = /* @__PURE__ */ new WeakMap();
+}
+var bindings = globalRef2[BINDINGS_KEY];
+function bindWorkflowClass(ctor, client) {
+  bindings.set(ctor, client);
+}
+__name(bindWorkflowClass, "bindWorkflowClass");
+function clientOf(ctor) {
+  const client = bindings.get(ctor);
+  if (!client) {
+    throw new Error(`${workflowName(ctor)} is not bound to a durable engine \u2014 the class-first statics only work after the module that registers this workflow has booted (or, in a store-less tenant worker, use the injected WorkflowService/engine facade instead).`);
+  }
+  return client;
+}
+__name(clientOf, "clientOf");
+var DurableWorkflow = class {
+  static {
+    __name(this, "DurableWorkflow");
+  }
+  /**
+  * Fire-and-forget start — `engine.start` outside a workflow, `ctx.startChild` (parent-linked)
+  * inside one. `opts.id` pins the run id (outside) / child id (inside) for idempotent starts.
+  */
+  static async start(input, opts) {
+    const cls = this;
+    const ctx = currentWorkflowCtx();
+    if (ctx) {
+      const runId2 = await ctx.startChild(cls, input, opts?.id);
+      return {
+        runId: runId2,
+        status: "pending"
+      };
+    }
+    const runId = opts?.id ?? globalThis.crypto.randomUUID();
+    return clientOf(cls).start(workflowName(cls), input, runId, opts);
+  }
+  /**
+  * Run-and-await the typed output — `ctx.child` inside a workflow (suspends the parent, zero
+  * compute); outside, starts the run and waits until it settles terminally. Throws `FatalError`
+  * when the run does not complete. `opts.timeoutMs` bounds the OUTSIDE wait only (inside, a
+  * suspended parent costs nothing — bound the child itself with `executionTimeout` instead).
+  */
+  static async execute(input, opts) {
+    const cls = this;
+    const ctx = currentWorkflowCtx();
+    if (ctx) return ctx.child(cls, input, opts?.id);
+    const client = clientOf(cls);
+    if (!client.waitForRun) {
+      throw new FatalError(`${workflowName(cls)}.execute() outside a workflow needs a store-backed engine to await the result \u2014 this class is bound to a store-less start facade (tenant worker). Use ${workflowName(cls)}.start() and observe the run instead.`, "execute_unsupported");
+    }
+    const runId = opts?.id ?? globalThis.crypto.randomUUID();
+    await client.start(workflowName(cls), input, runId, opts);
+    const settled = await client.waitForRun(runId, {
+      ...opts?.timeoutMs != null ? {
+        timeoutMs: opts.timeoutMs
+      } : {},
+      until: "terminal"
+    });
+    if (settled.status === "completed") return settled.output;
+    const detail = settled.error ? `: ${settled.error.message}` : "";
+    throw new FatalError(`${workflowName(cls)} run ${runId} settled ${settled.status}${detail}`, settled.error?.code ?? "execute_failed");
+  }
+};
+
 // src/duration.ts
 var UNIT_MS = {
   ms: 1,
@@ -412,121 +624,6 @@ function instantCheckpoint(p) {
 }
 __name(instantCheckpoint, "instantCheckpoint");
 
-// src/errors.ts
-var FatalError = class extends Error {
-  static {
-    __name(this, "FatalError");
-  }
-  code;
-  constructor(message, code) {
-    super(message);
-    this.name = "FatalError";
-    this.code = code;
-  }
-};
-var SingletonQueueFullError = class extends Error {
-  static {
-    __name(this, "SingletonQueueFullError");
-  }
-  workflow;
-  key;
-  maxQueueDepth;
-  constructor(workflow, key, maxQueueDepth) {
-    super(`singleton queue for ${workflow} key "${key}" is full (maxQueueDepth=${maxQueueDepth}); retry later`);
-    this.name = "SingletonQueueFullError";
-    this.workflow = workflow;
-    this.key = key;
-    this.maxQueueDepth = maxQueueDepth;
-  }
-};
-var SignalTimeoutError = class extends Error {
-  static {
-    __name(this, "SignalTimeoutError");
-  }
-  token;
-  timeoutMs;
-  constructor(token, timeoutMs) {
-    super(`timed out after ${timeoutMs}ms waiting for signal "${token}"`);
-    this.name = "SignalTimeoutError";
-    this.token = token;
-    this.timeoutMs = timeoutMs;
-  }
-};
-var RemoteStepTimeout = class extends Error {
-  static {
-    __name(this, "RemoteStepTimeout");
-  }
-  stepId;
-  timeoutMs;
-  constructor(stepId2, timeoutMs) {
-    super(`remote step ${stepId2} produced no result/heartbeat within ${timeoutMs}ms`);
-    this.name = "RemoteStepTimeout";
-    this.stepId = stepId2;
-    this.timeoutMs = timeoutMs;
-  }
-};
-var RemoteWorkflowTimeout = class extends Error {
-  static {
-    __name(this, "RemoteWorkflowTimeout");
-  }
-  taskId;
-  timeoutMs;
-  constructor(taskId, timeoutMs) {
-    super(`remote workflow task ${taskId} produced no decision within ${timeoutMs}ms \u2014 presumed dropped; re-driving via recovery`);
-    this.name = "RemoteWorkflowTimeout";
-    this.taskId = taskId;
-    this.timeoutMs = timeoutMs;
-  }
-};
-var NonDeterminismError = class extends Error {
-  static {
-    __name(this, "NonDeterminismError");
-  }
-  runId;
-  seq;
-  constructor(runId, seq, expected, recorded) {
-    super(`non-determinism at ${runId}#${seq}: code expects "${expected}" but history recorded "${recorded}". The workflow changed under an in-flight run \u2014 register a new @Workflow version.`);
-    this.name = "NonDeterminismError";
-    this.runId = runId;
-    this.seq = seq;
-  }
-};
-var GatherError = class extends Error {
-  static {
-    __name(this, "GatherError");
-  }
-  failures;
-  constructor(failures, total) {
-    const ids = failures.map((f) => f.id).join(", ");
-    const denom = total ?? failures.length;
-    super(`ctx.all: ${failures.length} of ${denom} child(ren) failed: ${ids}`);
-    this.name = "GatherError";
-    this.failures = failures;
-  }
-};
-var WorkflowSuspended = class extends Error {
-  static {
-    __name(this, "WorkflowSuspended");
-  }
-  /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
-  wakeAt;
-  constructor(wakeAt) {
-    super("workflow suspended");
-    this.name = "WorkflowSuspended";
-    this.wakeAt = wakeAt;
-  }
-};
-var ContinueAsNew = class extends Error {
-  static {
-    __name(this, "ContinueAsNew");
-  }
-  input;
-  constructor(input) {
-    super("workflow continued as new"), this.input = input;
-    this.name = "ContinueAsNew";
-  }
-};
-
 // src/entities.ts
 var ENTITY_WORKFLOW = "__entity";
 var entityRunId = /* @__PURE__ */ __name((name, key) => `entity:${name}:${key}`, "entityRunId");
@@ -988,18 +1085,6 @@ function stepConfigOf(ref) {
 }
 __name(stepConfigOf, "stepConfigOf");
 
-// src/workflow-ref.ts
-var WORKFLOW_NAME_KEY = Symbol.for("nestjs-durable:workflow-name");
-function workflowName(ref) {
-  if (typeof ref === "string") return ref;
-  const name = ref[WORKFLOW_NAME_KEY];
-  if (!name) {
-    throw new Error(`workflow class ${ref.name} has no registered name \u2014 is it decorated with @Workflow({ name })?`);
-  }
-  return name;
-}
-__name(workflowName, "workflowName");
-
 // src/workflow-ctx.ts
 function normalizeChildOptions(options) {
   return typeof options === "string" ? {
@@ -1185,6 +1270,20 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       value: buffered.payload
     };
   }, "consumeBuffered");
+  const stampDeadline = /* @__PURE__ */ __name(async (deadlineSeq, label, timeoutMs) => {
+    const recorded = await readCheckpoint(deadlineSeq);
+    const deadline = recorded?.wakeAt ?? host.clock() + timeoutMs;
+    if (!recorded) {
+      await writeCheckpoint(instantCheckpoint({
+        runId,
+        seq: deadlineSeq,
+        name: `timeout:${label}`,
+        kind: "sleep",
+        wakeAt: deadline
+      }));
+    }
+    return deadline;
+  }, "stampDeadline");
   const waitForSignal = /* @__PURE__ */ __name(async (token, opts) => {
     if (opts?.timeoutMs == null) {
       const current = pos.next();
@@ -1202,17 +1301,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
     const timeoutMs = opts.timeoutMs;
     const deadlineSeq = pos.next();
     const waitSeq = pos.next();
-    const recorded = await readCheckpoint(deadlineSeq);
-    const deadline = recorded?.wakeAt ?? host.clock() + timeoutMs;
-    if (!recorded) {
-      await writeCheckpoint(instantCheckpoint({
-        runId,
-        seq: deadlineSeq,
-        name: `timeout:${token}`,
-        kind: "sleep",
-        wakeAt: deadline
-      }));
-    }
+    const deadline = await stampDeadline(deadlineSeq, token, timeoutMs);
     const waited = await readCheckpoint(waitSeq);
     if (waited && waited.status === "completed") return waited.output;
     const buffered = await consumeBuffered(token, waitSeq);
@@ -1245,17 +1334,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
     const deadlineSeq = pos.next();
     const waitSeq = pos.next();
     const token = eventToken(name, opts.match, runId, waitSeq);
-    const recorded = await readCheckpoint(deadlineSeq);
-    const deadline = recorded?.wakeAt ?? host.clock() + timeoutMs;
-    if (!recorded) {
-      await writeCheckpoint(instantCheckpoint({
-        runId,
-        seq: deadlineSeq,
-        name: `timeout:event:${name}`,
-        kind: "sleep",
-        wakeAt: deadline
-      }));
-    }
+    const deadline = await stampDeadline(deadlineSeq, `event:${name}`, timeoutMs);
     const waited = await readCheckpoint(waitSeq);
     if (waited && waited.status === "completed") return waited.output;
     if (host.clock() >= deadline) {
@@ -1311,6 +1390,9 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
         const cp = existing[i];
         const c = cp?.status === "completed" ? cp.output : null;
         if (c && c.ok === false) {
+          for (let j = 0; j < inputs.length; j += 1) {
+            if (j !== i && existing[j]?.status !== "completed") host.cancelChild?.(id(j));
+          }
           throw new GatherError([
             {
               index: i,
@@ -1467,15 +1549,30 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
   const webhook = /* @__PURE__ */ __name(() => {
     const current = pos.next();
     const token = `wh:${runId}:${current}`;
-    const wait = /* @__PURE__ */ __name(async () => {
+    const wait = /* @__PURE__ */ __name(async (opts) => {
+      const timeoutMs = opts?.timeoutMs;
+      const deadlineSeq = timeoutMs == null ? -1 : pos.next();
       const existing = await readCheckpoint(current);
       if (existing && existing.status === "completed") return existing.output;
+      if (timeoutMs == null) {
+        await store.putSignalWaiter({
+          token,
+          runId,
+          seq: current
+        });
+        throw new WorkflowSuspended();
+      }
+      const deadline = await stampDeadline(deadlineSeq, token, timeoutMs);
+      if (host.clock() >= deadline) {
+        await store.takeSignalWaiter(token).catch(() => void 0);
+        throw new SignalTimeoutError(token, timeoutMs);
+      }
       await store.putSignalWaiter({
         token,
         runId,
         seq: current
       });
-      throw new WorkflowSuspended();
+      throw new WorkflowSuspended(deadline);
     }, "wait");
     return {
       token,
@@ -1503,6 +1600,18 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       output: attrs
     }));
   }, "upsertSearchAttributes");
+  function resolveCompensateDef(compensate) {
+    const name = typeof compensate === "string" ? compensate : stepNameOf(compensate);
+    if (name === void 0) {
+      throw new Error("ctx.step: compensate handler is not a @Step reference (no stamped step name) \u2014 pass a @Step-decorated method or a step name string");
+    }
+    const config = typeof compensate === "string" ? void 0 : stepConfigOf(compensate);
+    return {
+      name,
+      ...resolveStepPolicy(config, void 0)
+    };
+  }
+  __name(resolveCompensateDef, "resolveCompensateDef");
   function step(handlerOrName, input, opts) {
     const name = typeof handlerOrName === "string" ? handlerOrName : stepNameOf(handlerOrName);
     if (name === void 0) {
@@ -1516,6 +1625,20 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
     return host.callRemote(runId, pos.next(), def, input, opts?.queue, opts?.transport, {
       priority: opts?.priority,
       fairnessKey: opts?.fairnessKey
+    }).then((output) => {
+      if (opts?.compensate) {
+        compensations.push({
+          name,
+          dispatch: {
+            def: resolveCompensateDef(opts.compensate),
+            args: {
+              input,
+              output
+            }
+          }
+        });
+      }
+      return output;
     });
   }
   __name(step, "step");
@@ -2409,7 +2532,13 @@ var WorkflowEngine = class {
   * `start` when a call site needs the outcome — `await start(...); const r = await waitForRun(id)`.
   */
   waitForRun(runId, opts) {
-    const isSettled = /* @__PURE__ */ __name((run) => run.status !== "pending" && run.status !== "running" && run.status !== "cancelling" && !(run.status === "suspended" && run.awaitingDecisionTaskId !== void 0), "isSettled");
+    const TERMINAL = /* @__PURE__ */ new Set([
+      "completed",
+      "failed",
+      "cancelled",
+      "dead"
+    ]);
+    const isSettled = /* @__PURE__ */ __name((run) => opts?.until === "terminal" ? TERMINAL.has(run.status) : run.status !== "pending" && run.status !== "running" && run.status !== "cancelling" && !(run.status === "suspended" && run.awaitingDecisionTaskId !== void 0), "isSettled");
     const toResult = /* @__PURE__ */ __name((run) => ({
       runId,
       status: run.status,
@@ -2423,6 +2552,7 @@ var WorkflowEngine = class {
       const timer = opts?.timeoutMs != null ? setTimeout(() => {
         if (done) return;
         done = true;
+        if (poller) clearInterval(poller);
         off();
         reject(new Error(`waitForRun(${runId}) timed out after ${opts.timeoutMs}ms`));
       }, opts.timeoutMs) : void 0;
@@ -2430,6 +2560,7 @@ var WorkflowEngine = class {
         if (done) return;
         done = true;
         if (timer) clearTimeout(timer);
+        if (poller) clearInterval(poller);
         off();
         resolve(toResult(run));
       }, "finish");
@@ -2438,6 +2569,11 @@ var WorkflowEngine = class {
           if (run && isSettled(run)) finish(run);
         });
       }, "check");
+      const poller = opts?.until === "terminal" ? (() => {
+        const interval = setInterval(check, 250);
+        interval.unref?.();
+        return interval;
+      })() : void 0;
       off = this.subscribe((ev) => {
         if (ev.runId === runId && (ev.type === "run.completed" || ev.type === "run.failed" || ev.type === "run.suspended")) {
           check();
@@ -3361,14 +3497,24 @@ var WorkflowEngine = class {
   * Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
   * exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
   * suspended, hit continue-as-new, or threw — so a cancel is never lost just because the body didn't
-  * stop at a suspension point. Clears the in-memory cancel flag.
+  * stop at a suspension point.
+  *
+  * A dispatched compensation still in flight (or backing off a retry) needs the run to keep waiting:
+  * unlike the failure path (which is fine going `suspended` — a resumable state no different from an
+  * ordinary in-flight `ctx.step`), THIS run must stay `cancelling` — `engine.cancel`'s idempotent
+  * re-check, `waitForRun`'s non-terminal treatment, and crash recovery (`recoverIncomplete` only
+  * re-drives `running`/`cancelling` runs — a `cancelling` one with a free lease, whatever it's
+  * internally waiting on) all key off that status. So on a pending unwind this returns WITHOUT
+  * touching `status` (already `cancelling`, untouched since `engine.cancel` set it) — the in-memory
+  * cancel flag stays too, re-derived from the status on any later re-drive regardless.
   */
-  async compensateAndCancel(run, compensations) {
+  async compensateAndCancel(run, compensations, replay) {
+    const pending = await this.unwindCompensations(run, compensations, replay);
+    if (pending) return {
+      runId: run.id,
+      status: "cancelling"
+    };
     this.cancelRequested.delete(run.id);
-    for (let i = compensations.length - 1; i >= 0; i -= 1) {
-      const comp = compensations[i];
-      if (comp) await this.runCompensation(run, comp);
-    }
     const error = {
       message: "cancelled"
     };
@@ -3431,15 +3577,19 @@ var WorkflowEngine = class {
     for (const cp of snapshot) replay.set(cp.seq, cp);
     const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow);
     try {
-      const output = await fn(ctx, run.input);
-      if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+      const output = await runInWorkflowCtx(ctx, () => fn(ctx, run.input));
+      if (this.cancelRequested.has(run.id)) {
+        return this.compensateAndCancel(run, compensations, replay);
+      }
       return this.settleRun(run, {
         kind: "completed",
         output
       });
     } catch (err) {
       if (err instanceof ContinueAsNew) {
-        if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+        if (this.cancelRequested.has(run.id)) {
+          return this.compensateAndCancel(run, compensations, replay);
+        }
         await this.store.updateRun(run.id, {
           status: "completed",
           output: void 0,
@@ -3464,22 +3614,26 @@ var WorkflowEngine = class {
         };
       }
       if (err instanceof WorkflowSuspended) {
-        if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+        if (this.cancelRequested.has(run.id)) {
+          return this.compensateAndCancel(run, compensations, replay);
+        }
         return this.settleRun(run, {
           kind: "suspended",
           wakeAt: err.wakeAt
         });
       }
-      if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+      if (this.cancelRequested.has(run.id)) {
+        return this.compensateAndCancel(run, compensations, replay);
+      }
       const error = {
         message: err instanceof Error ? err.message : String(err),
         stack: err instanceof Error ? err.stack : void 0
       };
-      for (let i = compensations.length - 1; i >= 0; i -= 1) {
-        const comp = compensations[i];
-        if (!comp) continue;
-        await this.runCompensation(run, comp);
-      }
+      const pending = await this.unwindCompensations(run, compensations, replay);
+      if (pending) return this.settleRun(run, {
+        kind: "suspended",
+        wakeAt: pending.wakeAt
+      });
       return this.settleRun(run, {
         kind: "failed",
         error
@@ -3489,14 +3643,62 @@ var WorkflowEngine = class {
     }
   }
   /**
-  * Run one saga compensation, retried up to `compensationRetries`, emitting a `compensate:<step>`
-  * step event for its outcome so a stranded undo is visible. Never throws — a permanently-failing
-  * compensation is skipped so it can't mask the original failure.
+  * Undo every registered saga compensation in strict reverse order — the shared unwind both the
+  * run-failure path (`runExecution`'s catch) and the compensating-cancel path
+  * (`compensateAndCancel`) drive. Every entry, LOCAL or DISPATCHED, gets a NEGATIVE checkpoint seq
+  * `-(k + 1)` for its position `k` (0, 1, 2… walking the stack in reverse) — reserved space that can
+  * never collide with a body position (those start at 0), so a saga's undo trail composes onto the
+  * run's ordinary checkpoint history with no store-schema change, and shows up in run detail exactly
+  * like any other step. Deterministic because `compensations` is rebuilt identically on every replay
+  * (see `workflow-ctx.ts`), so the same comp always lands on the same negative seq across a crash +
+  * re-drive — the crash-safety this whole scheme rests on.
+  *
+  * A LOCAL entry runs in-process (`runCompensation`), which checkpoints its own outcome — completed,
+  * or failed once `compensationRetries` are exhausted — so a crash mid-unwind SKIPS an
+  * already-resolved one on the next pass instead of re-running it (and re-spending its retry budget)
+  * from attempt 1. A DISPATCHED entry is an ordinary remote-step dispatch under the hood
+  * (`dispatchCompensation`): when it needs the run to WAIT — freshly dispatched, still in flight, or
+  * backing off a durable retry — this function returns that wait signal immediately (skipping every
+  * comp after it in this pass); the CALLER decides how to represent "still unwinding" (see
+  * `compensateAndCancel`'s doc comment for why that differs between the two callers). Either way, the
+  * run resumes later exactly like any other dispatched step: `completeRemoteResult` completes the
+  * negative-seq checkpoint and re-drives, the body replays and deterministically re-throws the same
+  * exit it took before (the original failure, or the suspension `compensateAndCancel` resumed from),
+  * this function runs again, the now-resolved comp is skipped, and the unwind continues from there.
+  *
+  * Returns `undefined` once every compensation has resolved — the caller then finalizes the run
+  * (`failed` with the ORIGINAL body error, never masked by a comp outcome; or `cancelled`).
+  */
+  async unwindCompensations(run, compensations, replay) {
+    for (let i = compensations.length - 1; i >= 0; i -= 1) {
+      const comp = compensations[i];
+      if (!comp) continue;
+      const seq = -(compensations.length - i);
+      if ("fn" in comp) {
+        const existing = replay?.get(seq) ?? await this.store.getCheckpoint(run.id, seq);
+        if (existing) continue;
+        await this.runCompensation(run, comp, seq, replay);
+        continue;
+      }
+      const pending = await this.dispatchCompensation(run, comp, seq, replay);
+      if (pending) return pending;
+    }
+    return void 0;
+  }
+  /**
+  * Run one LOCAL saga compensation, retried up to `compensationRetries`, emitting a
+  * `compensate:<step>` step event for its outcome so a stranded undo is visible. Never throws — a
+  * permanently-failing compensation is skipped so it can't mask the original failure. Checkpoints
+  * its outcome at `seq` (a negative unwind position reserved by {@link unwindCompensations}) so a
+  * crash mid-unwind skips an already-resolved undo on a later pass instead of re-running it (and
+  * re-spending its retry budget) from attempt 1 — the checkpoint is durability/visibility only; the
+  * runtime retry-in-process-back-to-back semantics of `comp.fn()` are unchanged.
   */
-  async runCompensation(run, comp) {
+  async runCompensation(run, comp, seq, replay) {
     const name = `compensate:${comp.name}`;
+    const enqueuedAt = /* @__PURE__ */ new Date();
     for (let attempt = 1; attempt <= this.compensationRetries; attempt += 1) {
-      const startedAt = Date.now();
+      const startedAt = /* @__PURE__ */ new Date();
       try {
         await comp.fn();
         this.emit({
@@ -3505,26 +3707,143 @@ var WorkflowEngine = class {
           workflow: run.workflow,
           name,
           kind: "local",
-          durationMs: Date.now() - startedAt
+          durationMs: Date.now() - startedAt.getTime()
         });
+        const cp = stepCheckpoint({
+          runId: run.id,
+          seq,
+          name,
+          kind: "local",
+          status: "completed",
+          attempts: attempt,
+          enqueuedAt,
+          startedAt,
+          finishedAt: /* @__PURE__ */ new Date()
+        });
+        await this.store.saveCheckpoint(cp);
+        replay?.set(seq, cp);
         return;
       } catch (err) {
         if (attempt >= this.compensationRetries) {
+          const error = {
+            message: err instanceof Error ? err.message : String(err)
+          };
           this.emit({
             type: "step.failed",
             runId: run.id,
             workflow: run.workflow,
             name,
             kind: "local",
-            error: {
-              message: err instanceof Error ? err.message : String(err)
-            },
-            durationMs: Date.now() - startedAt
+            error,
+            durationMs: Date.now() - startedAt.getTime()
           });
+          const cp = stepCheckpoint({
+            runId: run.id,
+            seq,
+            name,
+            kind: "local",
+            status: "failed",
+            attempts: attempt,
+            error,
+            enqueuedAt,
+            startedAt,
+            finishedAt: /* @__PURE__ */ new Date()
+          });
+          await this.store.saveCheckpoint(cp);
+          replay?.set(seq, cp);
         }
       }
     }
   }
+  /**
+  * Resolve (or advance) ONE dispatched saga compensation at its reserved negative `seq` — the undo
+  * handler is an ordinary remote `@Step`, so this mirrors `callRemote`'s pending/failed/absent
+  * branches (engine.ts's `callRemote`), minus the queue/admission and in-memory-`timeoutMs` paths
+  * (V1: dispatch direct by name, always durable). Returns the wait signal when the run must pause for
+  * this compensation (freshly dispatched, still in flight, or backing off before a durable retry);
+  * `undefined` once it's resolved — completed (crash-safe skip), or retries exhausted/non-retryable
+  * (already visible: `completeRemoteResult` emitted `step.failed` for `compensate:<name>` when that
+  * checkpoint landed — never re-emitted here, and never allowed to block the rest of the unwind or
+  * mask the run's original failure).
+  */
+  async dispatchCompensation(run, comp, seq, replay) {
+    const { def, args } = comp.dispatch;
+    const name = `compensate:${comp.name}`;
+    const existing = replay?.get(seq) ?? await this.store.getCheckpoint(run.id, seq);
+    if (existing?.status === "completed") return void 0;
+    if (existing?.status === "pending") return {};
+    if (existing?.status === "failed") {
+      const maxAttempts = Math.max(1, def.retries ?? 1);
+      const retryable = existing.error?.retryable !== false;
+      if (!retryable || existing.attempts >= maxAttempts) return void 0;
+      if (existing.wakeAt == null) {
+        const wakeAt = this.clock() + backoffDelay(existing.attempts, def);
+        const withWakeAt = {
+          ...existing,
+          wakeAt
+        };
+        await this.store.saveCheckpoint(withWakeAt);
+        replay?.set(seq, withWakeAt);
+        return {
+          wakeAt
+        };
+      }
+      if (this.clock() < existing.wakeAt) return {
+        wakeAt: existing.wakeAt
+      };
+      await this.dispatchCompensationAttempt(run, seq, name, def, args, existing.attempts + 1, replay);
+      return {};
+    }
+    await this.dispatchCompensationAttempt(run, seq, name, def, args, 1, replay);
+    return {};
+  }
+  /**
+  * Dispatch (or re-dispatch, on a durable retry) one compensation's undo handler — mirrors
+  * `callRemote`'s dispatch block (persist the `pending` checkpoint BEFORE handing off to the
+  * transport, so a fast result always finds it to complete). Two DIFFERENT names are in play: the
+  * checkpoint's `name` is `compensate:<originalStepName>` (what makes this undo show up on the run's
+  * timeline, and what `completeRemoteResult` emits `step.completed`/`step.failed` under); the WIRE
+  * task's `name` is the undo handler's OWN routing name (`def.name`) — a worker dispatches to the
+  * `@Step` it registered, not to this saga-visibility label.
+  */
+  async dispatchCompensationAttempt(run, seq, name, def, args, attempt, replay) {
+    if (this.pool.size === 0) throw new Error("remote steps require a Transport");
+    const group = tenantGroup(sanitizeQueueToken(def.name), def.partition);
+    const enqueuedAt = /* @__PURE__ */ new Date();
+    const cp = stepCheckpoint({
+      runId: run.id,
+      seq,
+      name,
+      kind: "remote",
+      status: "pending",
+      input: args,
+      attempts: attempt,
+      workerGroup: group,
+      enqueuedAt,
+      startedAt: enqueuedAt,
+      finishedAt: enqueuedAt
+    });
+    await this.store.saveCheckpoint(cp);
+    replay?.set(seq, cp);
+    await this.pool.dispatch({
+      runId: run.id,
+      seq,
+      name: def.name,
+      stepId: cp.stepId,
+      group,
+      input: args,
+      traceparent: this.traceparent?.(),
+      context: this.context?.(),
+      attempt
+    });
+    this.emit({
+      type: "step.started",
+      runId: run.id,
+      seq,
+      name,
+      kind: "remote"
+    });
+  }
   /** The seam handed to {@link createWorkflowCtx}: the authoring API reaches durability + lifecycle
   *  (checkpointing, dispatch, child start) through this, so the ctx primitives live in their own
   *  module and the engine stays the orchestrator. */
@@ -3550,6 +3869,12 @@ var WorkflowEngine = class {
           namespace: parentNamespace
         }).catch(() => void 0));
       }, "startChild"),
+      // Deferred for the same reentrancy reason as `startChild` above. `cancel()` is already
+      // idempotent on a terminal/cancelled run (returns its existing status without side effects), so
+      // no extra guard is needed here for the failFast replay case (re-issuing the same cancel calls).
+      cancelChild: /* @__PURE__ */ __name((childId) => {
+        queueMicrotask(() => void this.cancel(childId).catch(() => void 0));
+      }, "cancelChild"),
       // Shallow-merge into the run's searchAttributes (the ctx primitive makes this exactly-once).
       upsertSearchAttributes: /* @__PURE__ */ __name(async (runId, attrs) => {
         const run = await this.store.getRun(runId);
@@ -4672,6 +4997,7 @@ export {
   DURABLE_OPTIONS_CANONICAL,
   DURABLE_STEP_CONFIG,
   DURABLE_STEP_NAME,
+  DurableWorkflow,
   Entities,
   EventAccumulators,
   FatalError,
@@ -4698,9 +5024,11 @@ export {
   applyAttributeQuery,
   attributeColumnFor,
   attributeOperand,
+  bindWorkflowClass,
   breakpointToken,
   collectMetrics,
   createStepLogger,
+  currentWorkflowCtx,
   eventMatchOf,
   eventMatches,
   eventPrefix,
@@ -4709,6 +5037,7 @@ export {
   normalizeAttributeRows,
   parseDuration,
   prevCronFireMs,
+  runInWorkflowCtx,
   runSchedules,
   runStepHandler,
   sanitizeQueueToken,