@dudousxd/nestjs-durable-core 0.27.1 → 0.28.0

package/dist/index.cjs

@@ -0,0 +1,3923 @@
+const __importMetaUrl = require('url').pathToFileURL(__filename).href;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CodecStateStore: () => CodecStateStore,
+  ContinueAsNew: () => ContinueAsNew,
+  DURABLE_OPTIONS: () => DURABLE_OPTIONS,
+  Entities: () => Entities,
+  EventAccumulators: () => EventAccumulators,
+  FatalError: () => FatalError,
+  InMemoryStateStore: () => InMemoryStateStore,
+  InMemoryTransport: () => InMemoryTransport,
+  NonDeterminismError: () => NonDeterminismError,
+  QueueController: () => QueueController,
+  RemoteStepError: () => RemoteStepError,
+  RemoteStepTimeout: () => RemoteStepTimeout,
+  RemoteWorkflowExecutor: () => RemoteWorkflowExecutor,
+  STATE_STORE: () => STATE_STORE,
+  SignalTimeoutError: () => SignalTimeoutError,
+  SingletonQueueFullError: () => SingletonQueueFullError,
+  TRANSPORT: () => TRANSPORT,
+  WORKFLOW_NAME_KEY: () => WORKFLOW_NAME_KEY,
+  WorkflowEngine: () => WorkflowEngine,
+  WorkflowSuspended: () => WorkflowSuspended,
+  applyAttributeQuery: () => applyAttributeQuery,
+  attributeColumnFor: () => attributeColumnFor,
+  attributeOperand: () => attributeOperand,
+  breakpointToken: () => breakpointToken,
+  collectMetrics: () => collectMetrics,
+  eventMatchOf: () => eventMatchOf,
+  eventMatches: () => eventMatches,
+  eventPrefix: () => eventPrefix,
+  eventToken: () => eventToken,
+  matchesAttributes: () => matchesAttributes,
+  normalizeAttributeRows: () => normalizeAttributeRows,
+  parseDuration: () => parseDuration,
+  prevCronFireMs: () => prevCronFireMs,
+  remoteStep: () => remoteStep,
+  runSchedules: () => runSchedules,
+  runStepHandler: () => runStepHandler,
+  scheduledRunId: () => scheduledRunId,
+  sqlComparator: () => sqlComparator,
+  stepId: () => stepId,
+  workflowName: () => workflowName
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/duration.ts
+var UNIT_MS = {
+  ms: 1,
+  s: 1e3,
+  sec: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  m: 6e4,
+  min: 6e4,
+  minute: 6e4,
+  minutes: 6e4,
+  h: 36e5,
+  hr: 36e5,
+  hour: 36e5,
+  hours: 36e5,
+  d: 864e5,
+  day: 864e5,
+  days: 864e5,
+  w: 6048e5,
+  week: 6048e5,
+  weeks: 6048e5
+};
+function parseDuration(duration) {
+  if (typeof duration === "number") return duration;
+  const match = duration.trim().match(/^(\d+(?:\.\d+)?)\s*([a-z]+)$/i);
+  if (!match) throw new Error(`invalid duration: ${duration}`);
+  const value = Number(match[1]);
+  const unit = (match[2] ?? "").toLowerCase();
+  const factor = UNIT_MS[unit];
+  if (factor === void 0) throw new Error(`unknown duration unit: ${unit}`);
+  return value * factor;
+}
+__name(parseDuration, "parseDuration");
+
+// src/backoff.ts
+function backoffDelay(attempt, options) {
+  const base = options?.backoffMs ?? 0;
+  if (base <= 0) return 0;
+  const raw = options?.backoff === "exp" ? base * 2 ** (attempt - 1) : base;
+  const capped = options?.backoffMaxMs ? Math.min(raw, options.backoffMaxMs) : raw;
+  return options?.jitter ? Math.round(capped * (0.5 + Math.random() * 0.5)) : capped;
+}
+__name(backoffDelay, "backoffDelay");
+
+// src/step-logger.ts
+function withDuration(start, now, data) {
+  if (data && typeof data === "object" && "durationMs" in data) {
+    return data;
+  }
+  const base = data && typeof data === "object" ? data : {};
+  return {
+    ...base,
+    durationMs: now() - start
+  };
+}
+__name(withDuration, "withDuration");
+function createStepLogger(events, now) {
+  let currentSub;
+  const push = /* @__PURE__ */ __name((level, message, data) => events.push({
+    at: now(),
+    level,
+    message,
+    ...currentSub ? {
+      subId: currentSub.id
+    } : {},
+    ...data === void 0 ? {} : {
+      data
+    }
+  }), "push");
+  const subEvent = /* @__PURE__ */ __name((e) => events.push({
+    at: now(),
+    level: e.status === "failed" ? "error" : e.status === "skipped" ? "warn" : "info",
+    message: e.message ?? e.phase ?? e.name,
+    subId: e.id,
+    name: e.name,
+    ...e.group === void 0 ? {} : {
+      group: e.group
+    },
+    ...e.phase === void 0 ? {} : {
+      phase: e.phase
+    },
+    ...e.status === void 0 ? {} : {
+      status: e.status
+    },
+    ...e.data === void 0 ? {} : {
+      data: e.data
+    }
+  }), "subEvent");
+  const subProcess = /* @__PURE__ */ __name(async (name, body, opts) => {
+    const id = opts?.id ?? globalThis.crypto.randomUUID();
+    const group = opts?.group;
+    const start = now();
+    const prevSub = currentSub;
+    currentSub = {
+      id
+    };
+    let terminal = false;
+    const emit = /* @__PURE__ */ __name((status, message, data) => {
+      if (terminal) return;
+      terminal = true;
+      subEvent({
+        id,
+        name,
+        group,
+        status,
+        message,
+        data: withDuration(start, now, data)
+      });
+    }, "emit");
+    const handle = {
+      phase: /* @__PURE__ */ __name((phase, data) => {
+        if (!terminal) subEvent({
+          id,
+          name,
+          group,
+          phase,
+          data
+        });
+        return handle;
+      }, "phase"),
+      skip: /* @__PURE__ */ __name((reason, data) => emit("skipped", reason, data), "skip"),
+      fail: /* @__PURE__ */ __name((reason, data) => emit("failed", reason, data), "fail")
+    };
+    try {
+      const result = await body(handle);
+      emit("ok");
+      return result;
+    } catch (err) {
+      emit("failed", err instanceof Error ? err.message : String(err));
+      throw err;
+    } finally {
+      currentSub = prevSub;
+    }
+  }, "subProcess");
+  return {
+    debug: /* @__PURE__ */ __name((m, d) => push("debug", m, d), "debug"),
+    info: /* @__PURE__ */ __name((m, d) => push("info", m, d), "info"),
+    warn: /* @__PURE__ */ __name((m, d) => push("warn", m, d), "warn"),
+    error: /* @__PURE__ */ __name((m, d) => push("error", m, d), "error"),
+    sub: /* @__PURE__ */ __name((name, status, message, data) => events.push({
+      at: now(),
+      level: status === "failed" ? "error" : status === "skipped" ? "warn" : "info",
+      message: message ?? name,
+      name,
+      status,
+      ...data === void 0 ? {} : {
+        data
+      }
+    }), "sub"),
+    subEvent,
+    subProcess
+  };
+}
+__name(createStepLogger, "createStepLogger");
+
+// src/protocol.ts
+function stepId(runId, seq) {
+  return `${runId}:${seq}`;
+}
+__name(stepId, "stepId");
+var breakpointToken = /* @__PURE__ */ __name((runId, seq) => `bp:${runId}:${seq}`, "breakpointToken");
+async function runStepHandler(task, handler) {
+  const base = {
+    runId: task.runId,
+    seq: task.seq,
+    stepId: task.stepId,
+    startedAt: Date.now()
+  };
+  if (!handler) {
+    return {
+      ...base,
+      status: "failed",
+      error: {
+        message: `no handler for ${task.name}`,
+        retryable: false
+      }
+    };
+  }
+  const events = [];
+  const withEvents = /* @__PURE__ */ __name((result) => events.length > 0 ? {
+    ...result,
+    events
+  } : result, "withEvents");
+  try {
+    const output = await handler(task.input, createStepLogger(events, Date.now));
+    return withEvents({
+      ...base,
+      status: "completed",
+      output
+    });
+  } catch (err) {
+    const e = err;
+    return withEvents({
+      ...base,
+      status: "failed",
+      error: {
+        message: err instanceof Error ? err.message : String(err),
+        ...typeof e?.code === "string" ? {
+          code: e.code
+        } : {},
+        ...typeof e?.retryable === "boolean" ? {
+          retryable: e.retryable
+        } : {}
+      }
+    });
+  }
+}
+__name(runStepHandler, "runStepHandler");
+
+// src/checkpoints.ts
+function instantCheckpoint(p) {
+  const at = /* @__PURE__ */ new Date();
+  return {
+    runId: p.runId,
+    seq: p.seq,
+    name: p.name,
+    kind: p.kind,
+    stepId: stepId(p.runId, p.seq),
+    status: p.status ?? "completed",
+    output: p.output,
+    wakeAt: p.wakeAt,
+    attempts: 1,
+    enqueuedAt: at,
+    startedAt: at,
+    finishedAt: at
+  };
+}
+__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 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 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");
+var Entities = class {
+  static {
+    __name(this, "Entities");
+  }
+  host;
+  configs = /* @__PURE__ */ new Map();
+  constructor(host) {
+    this.host = host;
+    host.register(ENTITY_WORKFLOW, "1", (ctx, input) => this.run(ctx, input));
+  }
+  register(name, config) {
+    this.configs.set(name, config);
+  }
+  /** Deliver an op to an entity's runner, starting it on first contact. `reply` (a signal token)
+  *  receives the handler's result, for `ctx.callEntity`. */
+  dispatch(name, key, op, arg, reply) {
+    const runId = entityRunId(name, key);
+    return this.host.signalWithStart(ENTITY_WORKFLOW, {
+      name,
+      key
+    }, runId, {
+      token: runId,
+      payload: {
+        op,
+        arg,
+        reply
+      }
+    });
+  }
+  async signal(name, key, op, arg) {
+    await this.dispatch(name, key, op, arg);
+  }
+  getState(name, key) {
+    return this.host.getEvent(entityRunId(name, key), "state");
+  }
+  /** The built-in runner: one long-lived run per key, processing ops serially over state. */
+  async run(ctx, input) {
+    const { name, key } = input;
+    const config = this.configs.get(name);
+    if (!config) throw new FatalError(`entity "${name}" is not registered`);
+    const token = entityRunId(name, key);
+    let state = config.initialState();
+    for (let i = 0; ; i += 1) {
+      const msg = await ctx.waitForSignal(token);
+      const out = await ctx.step(`op:${i}`, async () => {
+        const handler = config.handlers[msg.op];
+        if (!handler) throw new FatalError(`entity "${name}" has no handler for op "${msg.op}"`);
+        const result = await handler(state, msg.arg);
+        return {
+          result,
+          state
+        };
+      });
+      state = out.state;
+      await ctx.setEvent("state", state);
+      if (msg.reply) {
+        await ctx.step(`reply:${i}`, async () => {
+          await this.host.signal(msg.reply, out.result);
+        });
+      }
+    }
+  }
+};
+
+// src/event-accumulators.ts
+var accToken = /* @__PURE__ */ __name((target) => `__evtacc__:${target}`, "accToken");
+var EventAccumulators = class {
+  static {
+    __name(this, "EventAccumulators");
+  }
+  host;
+  constructor(host) {
+    this.host = host;
+    host.register("__evt_debounce", "1", (ctx, input) => this.debounce(ctx, input));
+    host.register("__evt_batch", "1", (ctx, input) => this.batch(ctx, input));
+  }
+  /** Route an `onEvent` payload into its target's debounce/batch accumulator. */
+  route(target, config, payload) {
+    const [workflow, input] = config.mode === "debounce" ? [
+      "__evt_debounce",
+      {
+        target,
+        windowMs: config.windowMs
+      }
+    ] : [
+      "__evt_batch",
+      {
+        target,
+        maxSize: config.maxSize,
+        windowMs: config.windowMs
+      }
+    ];
+    return this.host.signalWithStart(workflow, input, accToken(target), {
+      token: accToken(target),
+      payload
+    });
+  }
+  /** Fire the target with the LAST payload once events have been quiet for `windowMs`. */
+  async debounce(ctx, input) {
+    const { target, windowMs } = input;
+    const token = accToken(target);
+    let last = await ctx.waitForSignal(token);
+    for (; ; ) {
+      try {
+        last = await ctx.waitForSignal(token, {
+          timeoutMs: windowMs
+        });
+      } catch (e) {
+        if (e instanceof SignalTimeoutError) break;
+        throw e;
+      }
+    }
+    await ctx.startChild(target, last);
+    return ctx.continueAsNew(input);
+  }
+  /** Fire the target with all payloads (`{ events }`) once `maxSize` or `windowMs` from the first. */
+  async batch(ctx, input) {
+    const { target, maxSize, windowMs } = input;
+    const token = accToken(target);
+    const events = [
+      await ctx.waitForSignal(token)
+    ];
+    const deadline = await ctx.now() + windowMs;
+    while (events.length < maxSize) {
+      const remaining = deadline - await ctx.now();
+      if (remaining <= 0) break;
+      try {
+        events.push(await ctx.waitForSignal(token, {
+          timeoutMs: remaining
+        }));
+      } catch (e) {
+        if (e instanceof SignalTimeoutError) break;
+        throw e;
+      }
+    }
+    await ctx.startChild(target, {
+      events
+    });
+    return ctx.continueAsNew(input);
+  }
+};
+
+// src/events.ts
+var enc = /* @__PURE__ */ __name((s) => Buffer.from(s, "utf8").toString("base64"), "enc");
+var dec = /* @__PURE__ */ __name((s) => Buffer.from(s, "base64").toString("utf8"), "dec");
+function eventPrefix(name) {
+  return `event:${enc(name)}:`;
+}
+__name(eventPrefix, "eventPrefix");
+function eventToken(name, match, runId, seq) {
+  return `${eventPrefix(name)}${enc(JSON.stringify(match ?? {}))}:${runId}#${seq}`;
+}
+__name(eventToken, "eventToken");
+function eventMatchOf(token) {
+  try {
+    return JSON.parse(dec(token.split(":")[2] ?? ""));
+  } catch {
+    return {};
+  }
+}
+__name(eventMatchOf, "eventMatchOf");
+function eventMatches(payload, match) {
+  const keys = Object.keys(match);
+  if (keys.length === 0) return true;
+  if (!payload || typeof payload !== "object") return false;
+  const p = payload;
+  return keys.every((k) => JSON.stringify(p[k]) === JSON.stringify(match[k]));
+}
+__name(eventMatches, "eventMatches");
+
+// src/queue.ts
+var QueueController = class {
+  static {
+    __name(this, "QueueController");
+  }
+  config;
+  clock;
+  inFlight = 0;
+  windowStart = 0;
+  windowCount = 0;
+  /** Registered waiters by id (only used when priority/fairness ordering is in play). */
+  waiters = /* @__PURE__ */ new Map();
+  /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
+  waiterSeq = 0;
+  /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
+  keyServed = /* @__PURE__ */ new Map();
+  servedTick = 0;
+  constructor(config, clock) {
+    this.config = config;
+    this.clock = clock;
+  }
+  /** Whether this controller does any priority/fairness ordering (else it's a plain FIFO gate). */
+  get ordered() {
+    return this.config.fairness === "key";
+  }
+  /**
+  * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
+  * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
+  *
+  * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
+  * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
+  * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
+  */
+  tryAdmit(item) {
+    const now = this.clock();
+    const rl = this.config.rateLimit;
+    if (rl) {
+      if (now - this.windowStart >= rl.periodMs) {
+        this.windowStart = now;
+        this.windowCount = 0;
+      }
+      if (this.windowCount >= rl.limit) return {
+        ok: false,
+        retryAt: this.windowStart + rl.periodMs
+      };
+    }
+    const usingOrder = this.ordered || item?.priority != null || item?.waiterId != null;
+    const waiterId = item?.waiterId;
+    const full = this.config.concurrency != null && this.inFlight >= this.config.concurrency;
+    if (full) {
+      if (usingOrder && waiterId != null) this.register(waiterId, item);
+      return {
+        ok: false,
+        retryAt: now + (this.config.retryMs ?? 1e3)
+      };
+    }
+    if (usingOrder && this.waiters.size > 0) {
+      if (waiterId != null) this.register(waiterId, item);
+      if (!this.isNext(waiterId, item)) {
+        return {
+          ok: false,
+          retryAt: now + (this.config.retryMs ?? 1e3)
+        };
+      }
+    }
+    if (rl) this.windowCount += 1;
+    this.inFlight += 1;
+    if (waiterId != null) this.waiters.delete(waiterId);
+    if (item?.key != null) this.keyServed.set(item.key, ++this.servedTick);
+    return {
+      ok: true
+    };
+  }
+  /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
+  release() {
+    if (this.inFlight > 0) this.inFlight -= 1;
+  }
+  /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
+  register(waiterId, item) {
+    const existing = this.waiters.get(waiterId);
+    if (existing) {
+      existing.priority = item?.priority ?? 0;
+      existing.key = item?.key;
+      return;
+    }
+    this.waiters.set(waiterId, {
+      priority: item?.priority ?? 0,
+      key: item?.key,
+      seq: this.waiterSeq++
+    });
+  }
+  /**
+  * Is the calling item the best candidate among all registered waiters? Ordering, best first:
+  *   1. higher `priority`;
+  *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
+  *   3. earliest registration (FIFO) — stable tiebreak.
+  * A bare item (no waiterId) is compared on its hints directly.
+  */
+  isNext(waiterId, item) {
+    const self = (waiterId != null ? this.waiters.get(waiterId) : void 0) ?? {
+      priority: item?.priority ?? 0,
+      key: item?.key,
+      seq: Number.POSITIVE_INFINITY
+    };
+    let best = self;
+    for (const w of this.waiters.values()) {
+      if (this.better(w, best)) best = w;
+    }
+    return best === self;
+  }
+  /** Strict "a should be admitted before b" comparison under the active policy. */
+  better(a, b) {
+    if (a.priority !== b.priority) return a.priority > b.priority;
+    if (this.config.fairness === "key") {
+      const sa = this.servedOf(a.key);
+      const sb = this.servedOf(b.key);
+      if (sa !== sb) return sa < sb;
+    }
+    return a.seq < b.seq;
+  }
+  /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
+  servedOf(key) {
+    if (key == null) return 0;
+    return this.keyServed.get(key) ?? 0;
+  }
+};
+
+// src/transport-pool.ts
+var TransportPool = class {
+  static {
+    __name(this, "TransportPool");
+  }
+  transports;
+  constructor(transports) {
+    this.transports = transports;
+  }
+  get size() {
+    return this.transports.length;
+  }
+  /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
+  *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
+  *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
+  bind(onResult, onHeartbeat, onStepEvent) {
+    for (const { transport } of this.transports) {
+      transport.onResult(onResult);
+      transport.onHeartbeat(onHeartbeat);
+      if (onStepEvent && transport.onStepEvent) {
+        transport.onStepEvent(onStepEvent);
+      }
+    }
+  }
+  /**
+  * Dispatch `task` over the pool: try the preferred (or first) transport, fail over to the next on
+  * a dispatch error, and stamp the task with the id of the transport that accepted it (so a worker
+  * replies on the matching one). Throws if every transport fails.
+  */
+  async dispatch(task, preferId) {
+    let lastErr;
+    for (const { id, transport } of this.ordered(preferId)) {
+      try {
+        await transport.dispatch({
+          ...task,
+          transport: id
+        });
+        return;
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    throw lastErr ?? new Error("no transport accepted the dispatch");
+  }
+  /** Worker-health for `group`, merged across every transport that can report it (a group's queue
+  *  and its workers may live on any pinned transport). Undefined when no transport implements
+  *  `groupHealth` (e.g. a pure in-process transport — nothing to introspect). */
+  async groupHealth(group) {
+    const reports = [];
+    for (const { transport } of this.transports) {
+      if (transport.groupHealth) reports.push(await transport.groupHealth(group));
+    }
+    if (reports.length === 0) return void 0;
+    return {
+      group,
+      depth: reports.reduce((sum, r) => sum + r.depth, 0),
+      liveWorkers: reports.flatMap((r) => r.liveWorkers)
+    };
+  }
+  /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
+  async listWorkerGroups() {
+    const groups = /* @__PURE__ */ new Set();
+    for (const { transport } of this.transports) {
+      if (transport.listWorkerGroups) {
+        for (const g of await transport.listWorkerGroups()) groups.add(g);
+      }
+    }
+    return [
+      ...groups
+    ];
+  }
+  /** Pinned `preferId` first, then the rest (failover order). */
+  ordered(preferId) {
+    if (!preferId) return this.transports;
+    const pref = this.transports.filter((t) => t.id === preferId);
+    if (pref.length === 0) throw new Error(`transport "${preferId}" is not registered`);
+    return [
+      ...pref,
+      ...this.transports.filter((t) => t.id !== preferId)
+    ];
+  }
+};
+
+// src/completion.ts
+function unwrapCompletion(payload, label) {
+  const c = payload;
+  if (c && typeof c === "object" && "ok" in c && c.ok === false) {
+    throw new FatalError(`${label} failed: ${c.error}`);
+  }
+  return c?.value;
+}
+__name(unwrapCompletion, "unwrapCompletion");
+
+// 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
+var Position = class Position2 {
+  static {
+    __name(this, "Position");
+  }
+  seq = -1;
+  next() {
+    this.seq += 1;
+    return this.seq;
+  }
+  rewind() {
+    this.seq -= 1;
+  }
+};
+function createWorkflowCtx(host, runId, compensations, workflow = "") {
+  const { store, replay } = host;
+  const pos = new Position();
+  const readCheckpoint = /* @__PURE__ */ __name((seq) => {
+    const hit = replay?.get(seq);
+    if (hit !== void 0) return hit;
+    return store.getCheckpoint(runId, seq);
+  }, "readCheckpoint");
+  const writeCheckpoint = /* @__PURE__ */ __name(async (cp) => {
+    await store.saveCheckpoint(cp);
+    replay?.set(cp.seq, cp);
+  }, "writeCheckpoint");
+  const step = /* @__PURE__ */ __name(async (name, fn, options) => {
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing && existing.name !== name) {
+      throw new NonDeterminismError(runId, current, name, existing.name);
+    }
+    if (existing && existing.status === "completed") {
+      if (options?.compensate) compensations.push({
+        name,
+        fn: options.compensate
+      });
+      return existing.output;
+    }
+    const maxAttempts = Math.max(1, options?.retries ?? 1);
+    const startedAt = /* @__PURE__ */ new Date();
+    await host.startStep({
+      runId,
+      seq: current,
+      name,
+      kind: "local",
+      attempts: 1,
+      enqueuedAt: startedAt,
+      startedAt
+    });
+    for (let attempt = 1; ; attempt += 1) {
+      const events = [];
+      try {
+        const invocation = {
+          runId,
+          workflow,
+          stepName: name,
+          seq: current,
+          attempt
+        };
+        const body = /* @__PURE__ */ __name(() => fn(createStepLogger(events, host.clock)), "body");
+        const output = host.interceptStep ? await host.interceptStep(invocation, body) : await body();
+        await host.completeStep({
+          runId,
+          seq: current,
+          name,
+          kind: "local",
+          output,
+          events,
+          attempts: attempt,
+          enqueuedAt: startedAt,
+          startedAt
+        });
+        if (options?.compensate) compensations.push({
+          name,
+          fn: options.compensate
+        });
+        return output;
+      } catch (err) {
+        if (err instanceof FatalError || attempt >= maxAttempts) {
+          await host.failStep({
+            runId,
+            seq: current,
+            name,
+            kind: "local",
+            error: {
+              message: err instanceof Error ? err.message : String(err),
+              stack: err instanceof Error ? err.stack : void 0
+            },
+            events,
+            attempts: attempt,
+            enqueuedAt: startedAt,
+            startedAt
+          });
+          throw err;
+        }
+        const wait = backoffDelay(attempt, options);
+        if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+      }
+    }
+  }, "step");
+  const transaction = /* @__PURE__ */ __name(async (name, fn) => {
+    if (!store.transaction) {
+      throw new Error("ctx.transaction needs a store that supports transactions (the SQL adapters do). Use ctx.step for non-transactional work.");
+    }
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing && existing.name !== name) {
+      throw new NonDeterminismError(runId, current, name, existing.name);
+    }
+    if (existing && existing.status === "completed") return existing.output;
+    return store.transaction(async (tx) => {
+      const output = await fn(tx.raw);
+      const cp = instantCheckpoint({
+        runId,
+        seq: current,
+        name,
+        kind: "local",
+        output
+      });
+      await tx.saveCheckpoint(cp);
+      replay?.set(current, cp);
+      return output;
+    });
+  }, "transaction");
+  const suspendUntil = /* @__PURE__ */ __name(async (wakeAt) => {
+    const current = pos.next();
+    const now2 = host.clock();
+    const existing = await readCheckpoint(current);
+    if (existing) {
+      if (now2 >= (existing.wakeAt ?? 0)) return;
+      throw new WorkflowSuspended(existing.wakeAt ?? now2);
+    }
+    const at = wakeAt();
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name: "sleep",
+      kind: "sleep",
+      wakeAt: at
+    }));
+    throw new WorkflowSuspended(at);
+  }, "suspendUntil");
+  const sleep = /* @__PURE__ */ __name((duration) => suspendUntil(() => host.clock() + parseDuration(duration)), "sleep");
+  const sleepUntil = /* @__PURE__ */ __name((when) => suspendUntil(() => typeof when === "number" ? when : when.getTime()), "sleepUntil");
+  const continueAsNew = /* @__PURE__ */ __name((input) => {
+    throw new ContinueAsNew(input);
+  }, "continueAsNew");
+  const consumeBuffered = /* @__PURE__ */ __name(async (token, seq) => {
+    const buffered = await store.takeBufferedSignal(token);
+    if (!buffered) return null;
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq,
+      name: `signal:${token}`,
+      kind: "signal",
+      output: buffered.payload
+    }));
+    return {
+      value: buffered.payload
+    };
+  }, "consumeBuffered");
+  const waitForSignal = /* @__PURE__ */ __name(async (token, opts) => {
+    if (opts?.timeoutMs == null) {
+      const current = pos.next();
+      const existing = await readCheckpoint(current);
+      if (existing && existing.status === "completed") return existing.output;
+      const buffered2 = await consumeBuffered(token, current);
+      if (buffered2) return buffered2.value;
+      await store.putSignalWaiter({
+        token,
+        runId,
+        seq: current
+      });
+      throw new WorkflowSuspended();
+    }
+    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 waited = await readCheckpoint(waitSeq);
+    if (waited && waited.status === "completed") return waited.output;
+    const buffered = await consumeBuffered(token, waitSeq);
+    if (buffered) return buffered.value;
+    if (host.clock() >= deadline) {
+      await store.takeSignalWaiter(token).catch(() => void 0);
+      throw new SignalTimeoutError(token, timeoutMs);
+    }
+    await store.putSignalWaiter({
+      token,
+      runId,
+      seq: waitSeq
+    });
+    throw new WorkflowSuspended(deadline);
+  }, "waitForSignal");
+  const waitForEvent = /* @__PURE__ */ __name(async (name, opts) => {
+    if (opts?.timeoutMs == null) {
+      const current = pos.next();
+      const token2 = eventToken(name, opts?.match, runId, current);
+      const existing = await readCheckpoint(current);
+      if (existing && existing.status === "completed") return existing.output;
+      await store.putSignalWaiter({
+        token: token2,
+        runId,
+        seq: current
+      });
+      throw new WorkflowSuspended();
+    }
+    const timeoutMs = opts.timeoutMs;
+    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 waited = await readCheckpoint(waitSeq);
+    if (waited && waited.status === "completed") return waited.output;
+    if (host.clock() >= deadline) {
+      await store.takeSignalWaiter(token).catch(() => void 0);
+      throw new SignalTimeoutError(`event:${name}`, timeoutMs);
+    }
+    await store.putSignalWaiter({
+      token,
+      runId,
+      seq: waitSeq
+    });
+    throw new WorkflowSuspended(deadline);
+  }, "waitForEvent");
+  const task = /* @__PURE__ */ __name(async (name, dispatch, options) => {
+    await step(`task:dispatch:${name}`, dispatch, options);
+    return unwrapCompletion(await waitForSignal(`task:${runId}:${name}`), `task "${name}"`);
+  }, "task");
+  const child = /* @__PURE__ */ __name(async (workflow2, input, childId) => {
+    const current = pos.next();
+    const id = childId ?? `${runId}.child.${current}`;
+    const existing = await readCheckpoint(current);
+    if (existing && existing.status === "completed") {
+      return unwrapCompletion(existing.output, `child "${id}"`);
+    }
+    await store.putSignalWaiter({
+      token: `child:${id}`,
+      runId,
+      seq: current
+    });
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id);
+    if (!existing) {
+      await writeCheckpoint(instantCheckpoint({
+        runId,
+        seq: current,
+        name: `signal:child:${id}`,
+        kind: "signal",
+        status: "running"
+      }));
+    }
+    throw new WorkflowSuspended();
+  }, "child");
+  const startChild = /* @__PURE__ */ __name(async (workflow2, input, childId) => {
+    const current = pos.next();
+    const id = childId ?? `${runId}.child.${current}`;
+    const existing = await readCheckpoint(current);
+    if (existing && existing.status === "completed") return existing.output;
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id);
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name: `spawn:${id}`,
+      kind: "local",
+      output: id
+    }));
+    return id;
+  }, "startChild");
+  const callEntity = /* @__PURE__ */ __name(async (name, key, op, arg) => {
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing && existing.status === "completed") return existing.output;
+    const reply = `entityreply:${runId}:${current}`;
+    await store.putSignalWaiter({
+      token: reply,
+      runId,
+      seq: current
+    });
+    host.signalEntity?.(name, key, op, arg, reply);
+    throw new WorkflowSuspended();
+  }, "callEntity");
+  const signalEntity = /* @__PURE__ */ __name(async (name, key, op, arg) => {
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing && existing.status === "completed") return;
+    host.signalEntity?.(name, key, op, arg);
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name: `entitysig:${name}:${key}`,
+      kind: "local"
+    }));
+  }, "signalEntity");
+  const breakpoint = /* @__PURE__ */ __name(async (label) => {
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing && existing.status === "completed") return;
+    if (!existing) {
+      await writeCheckpoint(instantCheckpoint({
+        runId,
+        seq: current,
+        name: label ? `breakpoint:${label}` : "breakpoint",
+        kind: "signal",
+        status: "pending"
+      }));
+      await store.putSignalWaiter({
+        token: breakpointToken(runId, current),
+        runId,
+        seq: current
+      });
+    }
+    throw new WorkflowSuspended();
+  }, "breakpoint");
+  const patched = /* @__PURE__ */ __name(async (id) => {
+    const marker = `patch:${id}`;
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing) {
+      if (existing.name === marker) return true;
+      if (existing.name.startsWith("patch:")) {
+        throw new NonDeterminismError(runId, current, marker, existing.name);
+      }
+      pos.rewind();
+      return false;
+    }
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name: marker,
+      kind: "local",
+      output: true
+    }));
+    return true;
+  }, "patched");
+  const onUpdate = /* @__PURE__ */ __name((name, opts) => waitForSignal(`update:${runId}:${name}`, opts), "onUpdate");
+  const setEvent = /* @__PURE__ */ __name(async (key, value) => {
+    const current = pos.next();
+    const name = `event:${key}`;
+    const existing = await readCheckpoint(current);
+    if (existing && existing.name !== name) {
+      throw new NonDeterminismError(runId, current, name, existing.name);
+    }
+    if (existing && existing.status === "completed") return;
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name,
+      kind: "local",
+      output: value
+    }));
+  }, "setEvent");
+  const webhook = /* @__PURE__ */ __name(() => {
+    const current = pos.next();
+    const token = `wh:${runId}:${current}`;
+    const wait = /* @__PURE__ */ __name(async () => {
+      const existing = await readCheckpoint(current);
+      if (existing && existing.status === "completed") return existing.output;
+      await store.putSignalWaiter({
+        token,
+        runId,
+        seq: current
+      });
+      throw new WorkflowSuspended();
+    }, "wait");
+    return {
+      token,
+      url: host.webhookUrl?.(token),
+      wait
+    };
+  }, "webhook");
+  const now = /* @__PURE__ */ __name(() => step("now", async () => host.clock()), "now");
+  const random = /* @__PURE__ */ __name(() => step("random", async () => Math.random()), "random");
+  const uuid = /* @__PURE__ */ __name(() => step("uuid", async () => globalThis.crypto.randomUUID()), "uuid");
+  return {
+    runId,
+    step,
+    transaction,
+    callEntity,
+    signalEntity,
+    sleep,
+    sleepUntil,
+    continueAsNew,
+    waitForSignal,
+    waitForEvent,
+    task,
+    child,
+    startChild,
+    breakpoint,
+    webhook,
+    setEvent,
+    onUpdate,
+    patched,
+    now,
+    random,
+    uuid,
+    call: /* @__PURE__ */ __name((remote, input, opts) => host.callRemote(runId, pos.next(), remote, input, opts?.queue, opts?.transport, {
+      priority: opts?.priority,
+      fairnessKey: opts?.fairnessKey
+    }), "call")
+  };
+}
+__name(createWorkflowCtx, "createWorkflowCtx");
+
+// src/engine.ts
+var SINGLETON_RETRY_MS = 1e3;
+var SINGLETON_RETRY_JITTER_MS = 250;
+var singletonRetryWakeAt = /* @__PURE__ */ __name((nowMs) => nowMs + SINGLETON_RETRY_MS + Math.floor((Math.random() * 2 - 1) * SINGLETON_RETRY_JITTER_MS), "singletonRetryWakeAt");
+var singletonTag = /* @__PURE__ */ __name((cfg, input) => `singleton:${cfg.key(input)}`, "singletonTag");
+function mergeTags(staticTags, runTags) {
+  if (!staticTags?.length && !runTags?.length) return void 0;
+  return [
+    .../* @__PURE__ */ new Set([
+      ...staticTags ?? [],
+      ...runTags ?? []
+    ])
+  ];
+}
+__name(mergeTags, "mergeTags");
+var BREAKPOINT = "breakpoint";
+var isBreakpoint = /* @__PURE__ */ __name((cp) => cp.status === "pending" && cp.name.startsWith(BREAKPOINT), "isBreakpoint");
+var versionKey = /* @__PURE__ */ __name((name, version) => `${name}@${version}`, "versionKey");
+function nextContinuationId(runId) {
+  const m = runId.match(/^(.*)~(\d+)$/);
+  return m ? `${m[1]}~${Number(m[2]) + 1}` : `${runId}~1`;
+}
+__name(nextContinuationId, "nextContinuationId");
+function isNewerVersion(a, b) {
+  const na = Number(a);
+  const nb = Number(b);
+  if (!Number.isNaN(na) && !Number.isNaN(nb)) return na > nb;
+  return a.localeCompare(b, void 0, {
+    numeric: true
+  }) > 0;
+}
+__name(isNewerVersion, "isNewerVersion");
+var WorkflowEngine = class {
+  static {
+    __name(this, "WorkflowEngine");
+  }
+  store;
+  /** Ordered transport pool (dispatch + failover). Empty = no remote steps. */
+  pool;
+  controlPlane;
+  clock;
+  instanceId;
+  leaseMs;
+  maxRecoveryAttempts;
+  webhookUrl;
+  traceparent;
+  context;
+  /** Establish the originating context ambiently around a local step body (see {@link WorkflowEngineDeps.rehydrate}). Default passthrough. */
+  rehydrate;
+  compensationRetries;
+  /** Persist a `running` checkpoint at the start of a local step body (see {@link WorkflowEngineDeps.trackStepStart}). */
+  trackStepStart;
+  /** Where a freshly-started run executes — in-process by default (see {@link RunDispatcher}). */
+  runDispatcher;
+  /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
+  workflows = /* @__PURE__ */ new Map();
+  /** The newest registered version per workflow name — used to `start` new runs. */
+  latest = /* @__PURE__ */ new Map();
+  /** Event name → workflow names started when that event is published (see `onEvent`). */
+  eventTriggers = /* @__PURE__ */ new Map();
+  /** Durable-entity subsystem (registers the `__entity` runner; see `registerEntity`). */
+  entities;
+  /** Event debounce/batch accumulators (register the `__evt_*` runners; see `accumulators.route`). */
+  accumulators;
+  /** In-flight remote steps awaiting a worker result, keyed by stepId. */
+  pending = /* @__PURE__ */ new Map();
+  /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+  heartbeatResets = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  /** Step interceptors (onion middleware around real local-step execution), first = outermost. */
+  interceptors = [];
+  /** Callbacks notified (on any instance) when a run is cancelled — for cooperative cancellation. */
+  cancelListeners = /* @__PURE__ */ new Set();
+  /** Callbacks notified when a run is enqueued elsewhere — for low-latency cross-pod dispatch. */
+  enqueuedListeners = /* @__PURE__ */ new Set();
+  /** Notified when a run is dead-lettered (moved to `dead`) — a hook for a DLQ handler. */
+  deadListeners = /* @__PURE__ */ new Set();
+  /** Validators gating `engine.update`, keyed by `<workflow>:<updateName>`. */
+  updateValidators = /* @__PURE__ */ new Map();
+  /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
+  cancelRequested = /* @__PURE__ */ new Set();
+  /** Flow-control queues for remote steps, keyed by name (see {@link registerQueue}). */
+  queues = /* @__PURE__ */ new Map();
+  /** Which queue a dispatched step took a slot from, by stepId — so the result can release it. */
+  stepQueue = /* @__PURE__ */ new Map();
+  /** Executions currently in flight, so a graceful shutdown can wait for them to settle. */
+  inflight = /* @__PURE__ */ new Set();
+  draining = false;
+  constructor(deps) {
+    this.store = deps.store;
+    this.pool = new TransportPool(deps.transports ?? (deps.transport ? [
+      {
+        id: "default",
+        transport: deps.transport
+      }
+    ] : []));
+    this.controlPlane = deps.controlPlane;
+    this.clock = deps.clock ?? Date.now;
+    this.instanceId = deps.instanceId ?? globalThis.crypto.randomUUID();
+    this.leaseMs = deps.leaseMs ?? 3e4;
+    this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
+    this.webhookUrl = deps.webhookUrl;
+    this.traceparent = deps.traceparent;
+    this.context = deps.context;
+    this.rehydrate = deps.rehydrate ?? ((_carrier, fn) => fn());
+    this.compensationRetries = Math.max(1, deps.compensationRetries ?? 1);
+    this.trackStepStart = deps.trackStepStart ?? true;
+    this.runDispatcher = deps.runDispatcher ?? {
+      dispatch: /* @__PURE__ */ __name((runId) => queueMicrotask(() => void this.runOne(runId).catch(() => {
+      })), "dispatch")
+    };
+    this.pool.bind(
+      async (result) => {
+        const waiter = this.pending.get(result.stepId);
+        if (waiter) {
+          this.pending.delete(result.stepId);
+          if (result.status === "completed") {
+            waiter.resolve({
+              output: result.output,
+              startedAt: result.startedAt,
+              events: result.events
+            });
+          } else {
+            waiter.reject(new RemoteStepError(result.error));
+          }
+          return;
+        }
+        await this.completeRemoteResult(result);
+      },
+      // A heartbeat for an in-flight long step resets its liveness window (see callRemote).
+      async (beat) => {
+        this.heartbeatResets.get(beat.stepId)?.();
+      },
+      // A remote workflow worker streams each local step's lifecycle (running → completed/failed) so
+      // it's checkpointed live, not all-at-once when the long turn ends.
+      async (event) => {
+        await this.persistStepEvent(event);
+      }
+    );
+    this.controlPlane?.onControl((msg) => {
+      if (msg.from === this.instanceId) return;
+      if (msg.kind === "event") {
+        this.deliver({
+          ...msg.event,
+          at: new Date(msg.event.at)
+        });
+      } else if (msg.kind === "cancel") {
+        this.notifyCancelled(msg.runId);
+      } else if (msg.kind === "enqueued") {
+        for (const fn of this.enqueuedListeners) {
+          try {
+            fn(msg.runId);
+          } catch {
+          }
+        }
+      }
+    });
+    this.accumulators = new EventAccumulators(this);
+    this.entities = new Entities(this);
+  }
+  /**
+  * Register a **durable entity** (a virtual object): a keyed actor whose `handlers` run **serialized
+  * per key** over **durable state**, exactly once. Drive it with `signalEntity` (fire) /
+  * `ctx.callEntity` (call + await result) and read its state with `getEntityState`. See {@link Entities}.
+  */
+  registerEntity(name, config) {
+    this.entities.register(name, config);
+  }
+  /** Send an operation to an entity (fire-and-forget). Ordered + exactly-once per key. */
+  signalEntity(name, key, op, arg) {
+    return this.entities.signal(name, key, op, arg);
+  }
+  /** Read an entity's current durable state (published after each op), or undefined if it has none yet. */
+  getEntityState(name, key) {
+    return this.entities.getState(name, key);
+  }
+  /**
+  * Be notified when a run is enqueued on ANOTHER instance (via the control plane), so a worker can
+  * pick it up at once — e.g. `engine.onEnqueued((runId) => engine.runOne(runId))`. Returns an
+  * unsubscribe function. Only wire this on instances that should execute runs (workers).
+  */
+  onEnqueued(listener) {
+    this.enqueuedListeners.add(listener);
+    return () => this.enqueuedListeners.delete(listener);
+  }
+  /** Fire cooperative-cancellation listeners for `runId` (a worker bridge aborts in-flight work). */
+  notifyCancelled(runId) {
+    for (const fn of this.cancelListeners) {
+      try {
+        fn(runId);
+      } catch {
+      }
+    }
+  }
+  /**
+  * Register a workflow version. Register multiple versions of the same name to keep in-flight
+  * runs working across a breaking change: old runs resume on the version they started on, new
+  * runs start on the newest registered version.
+  */
+  register(name, version, fn, opts) {
+    const registered = {
+      name,
+      version,
+      fn,
+      tags: opts?.tags,
+      singleton: opts?.singleton,
+      executionTimeoutMs: opts?.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
+      validateInput: opts?.validateInput,
+      onEvent: opts?.onEvent,
+      eventBatch: opts?.eventBatch
+    };
+    this.workflows.set(versionKey(name, version), registered);
+    const current = this.latest.get(name);
+    if (!current || isNewerVersion(version, current.version)) this.latest.set(name, registered);
+    for (const event of opts?.onEvent ?? []) {
+      const subscribers = this.eventTriggers.get(event) ?? /* @__PURE__ */ new Set();
+      subscribers.add(name);
+      this.eventTriggers.set(event, subscribers);
+    }
+  }
+  /**
+  * Register a workflow whose body runs in another SDK (e.g. Python). The engine owns the run exactly
+  * as for a TS workflow — it persists checkpoints, recovers, runs timers — but advances it by handing
+  * the run's history to `executor` (which dispatches a {@link WorkflowTask} to the worker) and applying
+  * the {@link WorkflowDecision} the worker's replay returns. The worker never touches the store.
+  */
+  registerRemote(name, version, opts) {
+    const registered = {
+      name,
+      version,
+      // A remote workflow has no in-process body; execute() branches on `remote` before this is read.
+      fn: /* @__PURE__ */ __name(() => {
+        throw new Error(`workflow ${name} is remote \u2014 it has no in-process body`);
+      }, "fn"),
+      tags: opts.tags,
+      singleton: opts.singleton,
+      executionTimeoutMs: opts.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
+      validateInput: opts.validateInput,
+      remote: {
+        group: opts.group,
+        executor: opts.executor
+      }
+    };
+    this.workflows.set(versionKey(name, version), registered);
+    const current = this.latest.get(name);
+    if (!current || isNewerVersion(version, current.version)) this.latest.set(name, registered);
+  }
+  /**
+  * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
+  * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
+  * durable. Per engine instance (see {@link QueueConfig}). Registering the same name replaces it.
+  */
+  registerQueue(config) {
+    this.queues.set(config.name, new QueueController(config, this.clock));
+  }
+  /** Subscribe to lifecycle events. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+  * Register a {@link StepInterceptor} — onion middleware run around the real execution of every
+  * local `ctx.step` (timing, logging, tracing, error enrichment, context propagation). First
+  * registered is outermost; interceptors fire only when a step executes, never on replay. Returns
+  * an unsubscribe function.
+  */
+  use(interceptor) {
+    this.interceptors.push(interceptor);
+    return () => {
+      const i = this.interceptors.indexOf(interceptor);
+      if (i >= 0) this.interceptors.splice(i, 1);
+    };
+  }
+  /**
+  * Fold the registered interceptors around a local step body (identity when there are none), then
+  * run the whole thing inside the re-hydrated originating context. The carrier is read at execution
+  * time from {@link context} — the SAME reader stamped on dispatched remote tasks — so a local step
+  * sees the live tenant / user / trace ids ambiently (via the {@link rehydrate} bridge). Default
+  * `rehydrate` is a passthrough, so this is byte-identical to a bare body call when unwired.
+  */
+  interceptStep(invocation, body) {
+    const carrier = this.context?.();
+    const run = /* @__PURE__ */ __name(() => {
+      if (this.interceptors.length === 0) return body();
+      const chain = this.interceptors.reduceRight((next, interceptor) => () => interceptor(invocation, next), body);
+      return chain();
+    }, "run");
+    return this.rehydrate(carrier, run);
+  }
+  /**
+  * Be notified when a run is cancelled — on ANY instance, via the transport control plane. A
+  * worker bridge can use this for cooperative cancellation: abort the in-flight work for `runId`
+  * instead of finishing it just to have the result discarded. Returns an unsubscribe function.
+  */
+  onCancel(listener) {
+    this.cancelListeners.add(listener);
+    return () => this.cancelListeners.delete(listener);
+  }
+  /**
+  * Be notified when a run is **dead-lettered** — moved to `dead` after exceeding
+  * `maxRecoveryAttempts`. The listener receives the dead run (status `dead`, with its error), so a
+  * DLQ handler can do something other than just leaving it parked: alert, push to a real queue, or
+  * start a dead-letter workflow (e.g. `engine.onDead((run) => engine.start('pipeline-dlq', run, ...))`).
+  * Returns an unsubscribe function.
+  */
+  onDead(listener) {
+    this.deadListeners.add(listener);
+    return () => this.deadListeners.delete(listener);
+  }
+  notifyDead(run) {
+    for (const fn of this.deadListeners) {
+      try {
+        fn(run);
+      } catch {
+      }
+    }
+  }
+  /** Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the
+  *  control plane so other instances (e.g. a dashboard pod) can live-tail this run. */
+  emit(event) {
+    const full = {
+      ...event,
+      at: /* @__PURE__ */ new Date()
+    };
+    this.deliver(full);
+    if (this.controlPlane) {
+      void this.controlPlane.publishControl({
+        kind: "event",
+        event: full,
+        from: this.instanceId
+      }).catch(() => {
+      });
+    }
+  }
+  /** Deliver an event to local subscribers only (no re-broadcast) — used for both locally-produced
+  *  events and ones received from the control plane, so an event shows up once on every instance. */
+  deliver(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  async start(workflow, input, runId, opts) {
+    const name = workflowName(workflow);
+    const registered = this.latest.get(name);
+    if (!registered) throw new Error(`workflow ${name} is not registered`);
+    await registered.validateInput?.(input);
+    const prior = await this.store.getRun(runId);
+    if (prior) {
+      return {
+        runId,
+        status: prior.status,
+        output: prior.output,
+        error: prior.error
+      };
+    }
+    const now = /* @__PURE__ */ new Date();
+    const tags = mergeTags(registered.tags, registered.singleton ? [
+      ...opts?.tags ?? [],
+      singletonTag(registered.singleton, input)
+    ] : opts?.tags);
+    const maxQueueDepth = registered.singleton?.maxQueueDepth;
+    if (registered.singleton && maxQueueDepth != null) {
+      const cfg = registered.singleton;
+      const key = cfg.key(input);
+      const cap = (cfg.limit ?? 1) + maxQueueDepth;
+      const queued = await this.store.listRuns({
+        tag: singletonTag(cfg, input),
+        workflow: name,
+        statuses: [
+          "pending",
+          "running",
+          "suspended"
+        ]
+      });
+      if (queued.length >= cap) {
+        throw new SingletonQueueFullError(name, key, maxQueueDepth);
+      }
+    }
+    const run = {
+      id: runId,
+      workflow: name,
+      workflowVersion: registered.version,
+      status: "pending",
+      input,
+      tags,
+      searchAttributes: opts?.searchAttributes,
+      createdAt: now,
+      updatedAt: now
+    };
+    await this.store.createRun(run);
+    await this.runDispatcher.dispatch(runId);
+    if (this.controlPlane) {
+      void this.controlPlane.publishControl({
+        kind: "enqueued",
+        runId,
+        from: this.instanceId
+      }).catch(() => void 0);
+    }
+    return {
+      runId,
+      status: "pending"
+    };
+  }
+  /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
+  getRun(runId) {
+    return this.store.getRun(runId);
+  }
+  async resume(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) throw new Error(`run ${runId} not found`);
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead") {
+      return {
+        runId,
+        status: run.status,
+        output: run.output,
+        error: run.error
+      };
+    }
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion));
+    if (!registered) {
+      throw new Error(`workflow ${run.workflow}@${run.workflowVersion} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
+    }
+    return this.track(this.execute(run, registered.fn));
+  }
+  /** Track an in-flight execution so {@link drain} can wait for it. */
+  track(p) {
+    this.inflight.add(p);
+    void p.finally(() => this.inflight.delete(p));
+    return p;
+  }
+  /**
+  * Graceful shutdown: stop picking up new runs (recovery/timer become no-ops) and wait for
+  * in-flight executions to settle, up to `timeoutMs`. Call from your app's shutdown hook so a
+  * deploy hands off cleanly instead of leaving runs to the lease timeout.
+  */
+  async drain(timeoutMs = 1e4) {
+    this.draining = true;
+    if (this.inflight.size === 0) return;
+    const timer = new Promise((resolve) => {
+      const t = setTimeout(resolve, timeoutMs);
+      t.unref?.();
+    });
+    await Promise.race([
+      Promise.allSettled([
+        ...this.inflight
+      ]),
+      timer
+    ]);
+  }
+  /**
+  * Cancel in-flight runs that have outlived their workflow's `executionTimeout`. Call it from the
+  * timer poller alongside {@link resumeDueTimers}. A timed-out run is moved to `cancelled` with an
+  * `execution_timeout` error (terminal, so a late step result can't resurrect it).
+  */
+  async sweepTimeouts(now = this.clock()) {
+    for (const reg of new Set(this.latest.values())) {
+      if (reg.executionTimeoutMs == null) continue;
+      const deadline = now - reg.executionTimeoutMs;
+      const inflight = [
+        ...await this.store.listRuns({
+          workflow: reg.name,
+          status: "running"
+        }),
+        ...await this.store.listRuns({
+          workflow: reg.name,
+          status: "suspended"
+        })
+      ];
+      for (const run of inflight) {
+        if (run.createdAt.getTime() > deadline) continue;
+        const error = {
+          message: "execution timeout",
+          code: "execution_timeout"
+        };
+        await this.store.updateRun(run.id, {
+          status: "cancelled",
+          error,
+          updatedAt: /* @__PURE__ */ new Date()
+        });
+        this.emit({
+          type: "run.failed",
+          runId: run.id,
+          workflow: run.workflow,
+          error
+        });
+      }
+    }
+  }
+  /**
+  * Resume every run left incomplete by a crash or deploy. Called on boot. Completed steps
+  * replay from their checkpoints, so only the work that had not finished runs again.
+  */
+  async recoverIncomplete(nowMs = this.clock()) {
+    if (this.draining) return [];
+    const results = [];
+    for (const run of await this.store.listIncompleteRuns()) {
+      const acquired = await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs);
+      if (!acquired) continue;
+      const settled = await this.countRecovery(run);
+      if (settled) {
+        results.push(settled);
+        continue;
+      }
+      await this.store.releaseRunLock(run.id);
+      await this.store.updateRun(run.id, {
+        status: "pending",
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      await this.runDispatcher.dispatch(run.id);
+      results.push({
+        runId: run.id,
+        status: "pending"
+      });
+    }
+    return results;
+  }
+  /**
+  * Per-recovery bookkeeping (called once the lease is held): count the attempt, or — past
+  * `maxRecoveryAttempts` — move a poison pill to the `dead` dead-letter state. Returns a terminal
+  * result to skip the resume, or `undefined` to proceed.
+  */
+  async countRecovery(run) {
+    const attempts = (run.recoveryAttempts ?? 0) + 1;
+    if (this.maxRecoveryAttempts != null && attempts > this.maxRecoveryAttempts) {
+      const error = {
+        message: `run exceeded maxRecoveryAttempts (${this.maxRecoveryAttempts}) \u2014 moved to dead-letter`,
+        code: "max_recovery_attempts"
+      };
+      await this.store.updateRun(run.id, {
+        status: "dead",
+        error,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      await this.store.releaseRunLock(run.id);
+      this.emit({
+        type: "run.failed",
+        runId: run.id,
+        workflow: run.workflow,
+        error
+      });
+      this.notifyDead({
+        ...run,
+        status: "dead",
+        error,
+        recoveryAttempts: attempts
+      });
+      return {
+        runId: run.id,
+        status: "dead",
+        error
+      };
+    }
+    await this.store.updateRun(run.id, {
+      recoveryAttempts: attempts,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    return void 0;
+  }
+  /**
+  * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
+  * boot. A run still not due re-suspends cheaply without running new work.
+  */
+  async resumeDueTimers(nowMs = this.clock()) {
+    return this.resumeLeased(await this.store.listDueTimers(nowMs), nowMs);
+  }
+  /**
+  * Lease and execute one run by id — the worker side of dispatch. Acquires the recovery lease (so
+  * exactly one instance runs it), then resumes the body. Returns the result, or null if another
+  * instance holds the lease or the engine is draining. The default in-process dispatcher calls this;
+  * a broker-backed worker calls it per consumed run id.
+  */
+  async runOne(runId) {
+    if (this.draining) return null;
+    const nowMs = this.clock();
+    const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
+    if (!acquired) return null;
+    return this.resume(runId);
+  }
+  /**
+  * Re-enqueue a run for a worker to (re-)execute — the dispatch-model **retry**. Sets it back to
+  * `pending`, clears any stale lease, and dispatches; a worker resumes it (replaying its checkpoints,
+  * re-attempting the failed step). Returns the enqueued state immediately — never runs the body
+  * inline — or null if the run is unknown. The dashboard "retry" goes through here so it can't block
+  * the HTTP request on workflow execution.
+  */
+  async requeue(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    await this.store.releaseRunLock(runId);
+    await this.store.updateRun(runId, {
+      status: "pending",
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    await this.runDispatcher.dispatch(runId);
+    return {
+      runId,
+      status: "pending"
+    };
+  }
+  /**
+  * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
+  * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
+  * the original stays inspectable. Returns the new run's id, or null if `runId` is unknown.
+  */
+  async retryWithInput(runId, input, newRunId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    const id = newRunId ?? `${runId}~retry~${globalThis.crypto.randomUUID().slice(0, 8)}`;
+    await this.start(run.workflow, input, id, {
+      tags: run.tags
+    });
+    return {
+      runId: id
+    };
+  }
+  /**
+  * Pick up and execute every `pending` run — the poll-based side of dispatch for a worker pod with
+  * no broker. Runs enqueued by other pods (or by a caller using a no-op dispatcher) sit `pending`
+  * in the store until polled; leasing ensures exactly one pod runs each. Call periodically alongside
+  * {@link resumeDueTimers}.
+  */
+  async runPending(nowMs = this.clock()) {
+    return this.resumeLeased(await this.store.listPendingRuns(100), nowMs);
+  }
+  /**
+  * Resolve once `runId` reaches a settled state — terminal (completed/failed/cancelled/dead) or
+  * suspended (handed off to a timer/signal/event). The async counterpart to dispatch: pair it with
+  * `start` when a call site needs the outcome — `await start(...); const r = await waitForRun(id)`.
+  */
+  waitForRun(runId, opts) {
+    const isSettled = /* @__PURE__ */ __name((s) => s !== "pending" && s !== "running", "isSettled");
+    const toResult = /* @__PURE__ */ __name((run) => ({
+      runId,
+      status: run.status,
+      output: run.output,
+      error: run.error
+    }), "toResult");
+    return new Promise((resolve, reject) => {
+      let done = false;
+      let off = /* @__PURE__ */ __name(() => {
+      }, "off");
+      const timer = opts?.timeoutMs != null ? setTimeout(() => {
+        if (done) return;
+        done = true;
+        off();
+        reject(new Error(`waitForRun(${runId}) timed out after ${opts.timeoutMs}ms`));
+      }, opts.timeoutMs) : void 0;
+      const finish = /* @__PURE__ */ __name((run) => {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        off();
+        resolve(toResult(run));
+      }, "finish");
+      const check = /* @__PURE__ */ __name(() => {
+        void this.store.getRun(runId).then((run) => {
+          if (run && isSettled(run.status)) finish(run);
+        });
+      }, "check");
+      off = this.subscribe((ev) => {
+        if (ev.runId === runId && (ev.type === "run.completed" || ev.type === "run.failed" || ev.type === "run.suspended")) {
+          check();
+        }
+      });
+      check();
+    });
+  }
+  /**
+  * Resume each run only if this instance can acquire its recovery lease — so when several
+  * replicas recover or poll at once, each run is picked up by exactly one of them.
+  */
+  async resumeLeased(runs, nowMs = this.clock(), onLocked) {
+    if (this.draining) return [];
+    const results = [];
+    for (const run of runs) {
+      const acquired = await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs);
+      if (!acquired) continue;
+      const settled = onLocked ? await onLocked(run) : void 0;
+      results.push(settled ?? await this.resume(run.id));
+    }
+    return results;
+  }
+  /**
+  * Deliver an external signal to the run waiting on `token` and resume it with `payload`.
+  * Returns the run result, or null if no run is waiting for that token.
+  */
+  /**
+  * Publish a named event. It does two things, and returns how many runs it touched (the sum):
+  *  1. **Resumes** every in-flight run waiting on it via `ctx.waitForEvent(name, { match })` whose
+  *     match the payload satisfies (fan-out, vs `signal`'s point-to-point token).
+  *  2. **Starts** a fresh run of every workflow registered with `onEvent: [name]`, passing the
+  *     payload as input. Idempotent by `evt:<id>:<workflow>` — pass `opts.id` to dedupe redeliveries
+  *     of the same logical event (default: a fresh uuid, so each publish triggers once).
+  */
+  async publishEvent(name, payload, opts) {
+    let touched = 0;
+    const waiters = await this.store.listSignalWaiters(eventPrefix(name));
+    for (const w of waiters) {
+      if (eventMatches(payload, eventMatchOf(w.token))) {
+        await this.signal(w.token, payload);
+        touched += 1;
+      }
+    }
+    const subscribers = this.eventTriggers.get(name);
+    if (subscribers?.size) {
+      const eventId = opts?.id ?? globalThis.crypto.randomUUID();
+      for (const workflow of subscribers) {
+        try {
+          const batch = this.latest.get(workflow)?.eventBatch;
+          if (batch) {
+            await this.accumulators.route(workflow, batch, payload);
+          } else {
+            await this.start(workflow, payload, `evt:${eventId}:${workflow}`);
+          }
+          touched += 1;
+        } catch {
+        }
+      }
+    }
+    return touched;
+  }
+  async signal(token, payload) {
+    const waiter = await this.store.takeSignalWaiter(token);
+    if (!waiter) {
+      await this.store.bufferSignal(token, payload);
+      return null;
+    }
+    await this.store.saveCheckpoint(instantCheckpoint({
+      runId: waiter.runId,
+      seq: waiter.seq,
+      name: `signal:${token}`,
+      kind: "signal",
+      output: payload
+    }));
+    return this.resume(waiter.runId);
+  }
+  /**
+  * Ensure a run exists for `runId`, then deliver a signal to it — atomically race-free thanks to
+  * signal buffering: if the run is new (or busy / not yet waiting), the signal is buffered and
+  * consumed when it reaches `waitForSignal(token)`. The canonical **durable-entity / accumulator**
+  * pattern: one long-lived run per key (the `runId`) that loops on `waitForSignal`, fed events by
+  * many `signalWithStart` calls. `start` is idempotent by `runId`, so concurrent callers converge on
+  * one run. (Use a per-run `token`, e.g. derived from `runId`, so the signal targets this entity.)
+  */
+  async signalWithStart(workflow, input, runId, signal, opts) {
+    await this.start(workflow, input, runId, opts);
+    await this.signal(signal.token, signal.payload);
+    return {
+      runId
+    };
+  }
+  /**
+  * Report the result of a `ctx.task(name, …)` back to its run (async completion). The external
+  * worker that the task dispatched to calls this when done; the run resumes with `result`. Returns
+  * null if no run is waiting on the task (e.g. a duplicate/late delivery) — a safe no-op.
+  */
+  async completeTask(runId, name, result) {
+    return this.signal(`task:${runId}:${name}`, {
+      ok: true,
+      value: result
+    });
+  }
+  /** Report that a `ctx.task` failed — the run resumes and throws a FatalError at the task. */
+  async failTask(runId, name, error) {
+    return this.signal(`task:${runId}:${name}`, {
+      ok: false,
+      error
+    });
+  }
+  /**
+  * Notify a parent that's waiting on `runId` as a child of its terminal outcome (the `ctx.child`
+  * rendezvous). A no-op when no parent is waiting, so `execute()` can call it on every run without
+  * knowing about the child feature.
+  */
+  notifyParent(runId, completion) {
+    void this.signal(`child:${runId}`, completion).catch(() => void 0);
+  }
+  /**
+  * Cancel a run (e.g. from the dashboard). Returns null if the run does not exist. Pass
+  * `{ compensate: true }` to undo the saga first: the suspended run is resumed so its completed
+  * steps' compensations run in reverse (visible as `compensate:<step>` events), then it's marked
+  * cancelled. Without it, cancellation is immediate (no undo).
+  */
+  async cancel(runId, opts) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    if (run.status === "completed" || run.status === "cancelled" || run.status === "dead") {
+      return {
+        runId,
+        status: run.status,
+        output: run.output,
+        error: run.error
+      };
+    }
+    if (opts?.compensate && (run.status === "suspended" || run.status === "running")) {
+      this.cancelRequested.add(runId);
+      if (this.controlPlane) {
+        void this.controlPlane.publishControl({
+          kind: "cancel",
+          runId,
+          from: this.instanceId
+        }).catch(() => void 0);
+      }
+      queueMicrotask(() => {
+        void this.resume(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
+      });
+      await this.cancelChildren(runId, opts);
+      return {
+        runId,
+        status: run.status
+      };
+    }
+    const error = {
+      message: "cancelled"
+    };
+    await this.store.updateRun(runId, {
+      status: "cancelled",
+      error,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "run.failed",
+      runId,
+      workflow: run.workflow,
+      error
+    });
+    await this.cancelChildren(runId, opts);
+    this.notifyCancelled(runId);
+    if (this.controlPlane) {
+      void this.controlPlane.publishControl({
+        kind: "cancel",
+        runId,
+        from: this.instanceId
+      }).catch(() => void 0);
+    }
+    void this.wakeNextSingletons(run).catch(() => void 0);
+    return {
+      runId,
+      status: "cancelled",
+      error
+    };
+  }
+  /**
+  * Bulk-cancel every run matching a filter — e.g. cancel all `order` runs tagged `vip`, or every run
+  * whose `tier` search attribute is `free`. The filter is a {@link RunQuery} (workflow / status / tag
+  * / search-attribute predicates), so it reuses the same matching the dashboard list uses. Each match
+  * is run through {@link cancel}, so the same plumbing applies per run: child cascade, the optional
+  * saga `compensate`, local cancel listeners, and the control-plane broadcast that tells the owning
+  * worker to abort. Returns one {@link RunResult} per matched run (already-finished matches report
+  * their terminal status — `cancel` is a no-op on them, never clobbering a completed/dead run).
+  */
+  async cancelWhere(filter, opts) {
+    const runs = await this.store.listRuns(filter);
+    const results = [];
+    for (const run of runs) {
+      const r = await this.cancel(run.id, opts);
+      if (r) results.push(r);
+    }
+    return results;
+  }
+  /**
+  * Cascade cancellation to a run's children — both awaited (`ctx.child`, found via its live
+  * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
+  * checkpoint). Recursive, so a whole subtree is cancelled; the terminal guard in `cancel` stops it
+  * at finished / already-cancelled runs (no loops, no re-cancel).
+  */
+  async cancelChildren(parentRunId, opts) {
+    for (const id of await this.getRunChildren(parentRunId)) {
+      await this.cancel(id, opts).catch(() => void 0);
+    }
+  }
+  /**
+  * The ids of the runs a run spawned — both awaited (`ctx.child`) and fire-and-forget
+  * (`ctx.startChild`, found via its `spawn:<id>` checkpoint). The canonical parent→children edge,
+  * used for both cancellation cascades and the dashboard run-tree.
+  *
+  * An awaited child is discovered two ways, because the live `child:<id>` waiter only exists WHILE
+  * the parent is suspended on it: the waiter resolves and is consumed the moment the child settles,
+  * so a completed parent (or a completed awaited child) would otherwise drop out of the tree. The
+  * `signal:child:<id>` checkpoint (the placeholder written when the parent first awaits the child,
+  * overwritten as completed/failed when it settles) persists across completion, so we read both and
+  * dedupe — the edge stays stable for a finished run, not just a live one.
+  */
+  async getRunChildren(parentRunId) {
+    const childIds = /* @__PURE__ */ new Set();
+    for (const w of await this.store.listSignalWaiters("child:")) {
+      if (w.runId === parentRunId) childIds.add(w.token.slice("child:".length));
+    }
+    for (const cp of await this.store.listCheckpoints(parentRunId)) {
+      if (cp.name.startsWith("signal:child:")) childIds.add(cp.name.slice("signal:child:".length));
+      if (cp.name.startsWith("spawn:") && typeof cp.output === "string") childIds.add(cp.output);
+    }
+    return [
+      ...childIds
+    ];
+  }
+  /** The worker groups this engine dispatches to: every registered remote workflow's group, plus any
+  *  `extra` the caller declares. Local-step groups (a group consumed by in-process `@DurableStep`
+  *  workers, e.g. `pipeline`) aren't derivable from registrations — pass them via `extra` so a group
+  *  with backlog and ZERO workers is still reported (the alert case has no heartbeat to discover). */
+  knownGroups(extra = []) {
+    const groups = new Set(extra);
+    for (const def of this.workflows.values()) {
+      if (def.remote?.group) groups.add(def.remote.group);
+    }
+    return [
+      ...groups
+    ];
+  }
+  /** Per-group worker health (queue backlog + live worker heartbeats). Covers {@link knownGroups}
+  *  (so a registered group with backlog and ZERO workers still reports — the alert case) UNION the
+  *  groups discovered from live heartbeats (so a local-step group like `pipeline`, not derivable
+  *  from registrations, shows once its workers beat). Empty when no transport can introspect health
+  *  (only the BullMQ transport implements `groupHealth`). */
+  async workerHealth(extra = []) {
+    const groups = /* @__PURE__ */ new Set([
+      ...this.knownGroups(extra),
+      ...await this.pool.listWorkerGroups()
+    ]);
+    const out = [];
+    for (const group of groups) {
+      const health = await this.pool.groupHealth(group);
+      if (health) out.push(health);
+    }
+    return out;
+  }
+  /**
+  * Persist a streamed local-step lifecycle event from a remote workflow worker (see
+  * {@link WorkflowStepEvent}). A Python `@workflow` runs its `ctx.step`s inline over one turn that
+  * can last minutes; the worker streams each step's start/finish so the engine checkpoints it LIVE —
+  * a step shows `running` the moment its body begins, then resolves to `completed`/`failed` with its
+  * real wall-clock window and sub-process events — instead of every step appearing at once when the
+  * turn ends. The turn's final `recordStep` command re-persists the same (runId, seq) checkpoint
+  * idempotently, so this is purely additive observability and never changes the run's outcome.
+  */
+  async persistStepEvent(event) {
+    const startedAt = new Date(event.startedAt);
+    const events = event.events && event.events.length > 0 ? event.events : void 0;
+    if (event.phase === "running") {
+      await this.store.saveCheckpoint({
+        runId: event.runId,
+        seq: event.seq,
+        name: event.name,
+        kind: "local",
+        stepId: stepId(event.runId, event.seq),
+        status: "running",
+        events,
+        attempts: 1,
+        enqueuedAt: startedAt,
+        startedAt,
+        finishedAt: startedAt
+      });
+      this.emit({
+        type: "step.started",
+        runId: event.runId,
+        seq: event.seq,
+        name: event.name,
+        kind: "local"
+      });
+      return;
+    }
+    const failed = event.phase === "failed";
+    await this.store.saveCheckpoint({
+      runId: event.runId,
+      seq: event.seq,
+      name: event.name,
+      kind: "local",
+      stepId: stepId(event.runId, event.seq),
+      status: failed ? "failed" : "completed",
+      output: failed ? void 0 : event.output,
+      error: failed ? event.error : void 0,
+      events,
+      attempts: 1,
+      enqueuedAt: startedAt,
+      startedAt,
+      finishedAt: event.finishedAt != null ? new Date(event.finishedAt) : /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: failed ? "step.failed" : "step.completed",
+      runId: event.runId,
+      seq: event.seq,
+      name: event.name,
+      kind: "local",
+      output: failed ? void 0 : event.output,
+      error: failed ? event.error : void 0
+    });
+  }
+  /**
+  * Announce a local step's body has begun and (when `trackStepStart`) checkpoint it as `running`,
+  * so it's visible in flight rather than appearing only on completion. The checkpoint is a
+  * placeholder overwritten by {@link completeStep}/{@link failStep}; it never short-circuits replay
+  * (only `completed` does), so a crash mid-body just re-runs the step. The `step.started` event
+  * fires regardless — the live SSE view sees the start even with persistence off.
+  */
+  async startStep(step) {
+    if (this.trackStepStart) {
+      await this.store.saveCheckpoint({
+        runId: step.runId,
+        seq: step.seq,
+        name: step.name,
+        kind: step.kind,
+        stepId: stepId(step.runId, step.seq),
+        status: "running",
+        input: step.input,
+        events: step.events && step.events.length > 0 ? step.events : void 0,
+        attempts: step.attempts,
+        workerGroup: step.workerGroup,
+        enqueuedAt: step.enqueuedAt,
+        startedAt: step.startedAt,
+        finishedAt: step.startedAt
+      });
+    }
+    this.emit({
+      type: "step.started",
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind
+    });
+  }
+  /** Checkpoint a finished step and announce it — the two things that must always happen together. */
+  async completeStep(step) {
+    await this.store.saveCheckpoint({
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      stepId: stepId(step.runId, step.seq),
+      status: "completed",
+      input: step.input,
+      output: step.output,
+      events: step.events && step.events.length > 0 ? step.events : void 0,
+      attempts: step.attempts,
+      workerGroup: step.workerGroup,
+      enqueuedAt: step.enqueuedAt,
+      startedAt: step.startedAt,
+      finishedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "step.completed",
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      output: step.output,
+      queueMs: step.startedAt.getTime() - step.enqueuedAt.getTime(),
+      durationMs: Date.now() - step.startedAt.getTime()
+    });
+  }
+  /** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
+  async failStep(step) {
+    await this.store.saveCheckpoint({
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      stepId: stepId(step.runId, step.seq),
+      status: "failed",
+      input: step.input,
+      error: step.error,
+      events: step.events && step.events.length > 0 ? step.events : void 0,
+      attempts: step.attempts,
+      workerGroup: step.workerGroup,
+      enqueuedAt: step.enqueuedAt,
+      startedAt: step.startedAt,
+      finishedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "step.failed",
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      error: step.error,
+      queueMs: step.startedAt.getTime() - step.enqueuedAt.getTime(),
+      durationMs: Date.now() - step.startedAt.getTime()
+    });
+  }
+  /**
+  * Whether `run` may run now under its singleton key: it's among the `limit` oldest in-flight runs
+  * (running or suspended) sharing the key, by `(createdAt, id)` order. A consistent store gives every
+  * instance the same ordering, so admission is race-free + FIFO.
+  */
+  async admitSingleton(run, cfg) {
+    const tag = singletonTag(cfg, run.input);
+    const inflight = (await this.store.listRuns({
+      tag,
+      workflow: run.workflow,
+      statuses: [
+        "running",
+        "suspended"
+      ]
+    })).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
+    const idx = inflight.findIndex((r) => r.id === run.id);
+    return idx >= 0 && idx < (cfg.limit ?? 1);
+  }
+  /**
+  * Notify-on-release: a singleton run just settled (freeing a slot), so wake the gated waiters that
+  * can now be admitted — immediately, instead of letting them sleep until their ~1s retry timer.
+  * Dispatches up to `limit` of the oldest gated (`suspended` + same singleton tag) waiters by
+  * `(createdAt, id)`; each re-checks admission in `runExecution` and runs only if it actually wins a
+  * slot, so this never breaks the FIFO + race-free guarantees (the durable timer remains the
+  * cross-instance / crash fallback — this just removes the poll latency on the happy path).
+  */
+  async wakeNextSingletons(settled) {
+    const registered = this.workflows.get(versionKey(settled.workflow, settled.workflowVersion)) ?? this.latest.get(settled.workflow);
+    const cfg = registered?.singleton;
+    if (!cfg) return;
+    const tag = settled.tags?.find((t) => t.startsWith("singleton:"));
+    if (!tag) return;
+    const gated = (await this.store.listRuns({
+      tag,
+      workflow: settled.workflow,
+      statuses: [
+        "suspended"
+      ]
+    })).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
+    for (const next of gated.slice(0, cfg.limit ?? 1)) {
+      if (next.wakeAt != null) {
+        await this.store.updateRun(next.id, {
+          wakeAt: void 0,
+          updatedAt: /* @__PURE__ */ new Date()
+        }).catch(() => void 0);
+      }
+      this.runDispatcher.dispatch(next.id);
+    }
+  }
+  async execute(run, fn) {
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion));
+    const lockNow = this.clock();
+    if (run.lockedBy !== this.instanceId || (run.lockedUntil ?? 0) <= lockNow) {
+      if (!await this.store.tryLockRun(run.id, this.instanceId, lockNow + this.leaseMs, lockNow)) {
+        return {
+          runId: run.id,
+          status: run.status
+        };
+      }
+    }
+    const renew = setInterval(() => {
+      void this.store.renewRunLock(run.id, this.instanceId, this.clock() + this.leaseMs).catch(() => void 0);
+    }, Math.max(50, Math.floor(this.leaseMs / 2)));
+    renew.unref?.();
+    try {
+      const result = registered?.remote ? await this.runRemoteExecution(run, registered) : await this.runExecution(run, fn, registered);
+      if (registered?.singleton && (result.status === "completed" || result.status === "failed" || result.status === "cancelled" || result.status === "dead")) {
+        void this.wakeNextSingletons(run).catch(() => void 0);
+      }
+      return result;
+    } finally {
+      clearInterval(renew);
+    }
+  }
+  /**
+  * Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
+  * a workflow task to the worker and awaits its replay) and apply the decision. Mirrors
+  * {@link runExecution}'s settle/suspend; the lease is held by {@link execute}. The result that lands
+  * us back here (a remote step finished, a timer fired) goes through `resume` like any TS workflow.
+  */
+  async runRemoteExecution(run, registered) {
+    const remote = registered.remote;
+    if (run.status === "pending") {
+      await this.store.updateRun(run.id, {
+        status: "running",
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      run.status = "running";
+      this.emit({
+        type: "run.started",
+        runId: run.id,
+        workflow: run.workflow
+      });
+    }
+    if (registered.singleton && !await this.admitSingleton(run, registered.singleton)) {
+      const wakeAt2 = singletonRetryWakeAt(this.clock());
+      await this.store.updateRun(run.id, {
+        status: "suspended",
+        wakeAt: wakeAt2,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.suspended",
+        runId: run.id,
+        workflow: run.workflow
+      });
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: "suspended"
+      };
+    }
+    const history = await this.remoteHistory(run.id);
+    let decision;
+    try {
+      decision = await remote.executor.advance(run, history);
+    } catch (err) {
+      const error = {
+        message: err instanceof Error ? err.message : String(err),
+        stack: err instanceof Error ? err.stack : void 0
+      };
+      await this.store.updateRun(run.id, {
+        status: "failed",
+        error,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.failed",
+        runId: run.id,
+        workflow: run.workflow,
+        error
+      });
+      return {
+        runId: run.id,
+        status: "failed",
+        error
+      };
+    }
+    if (decision.status === "completed") {
+      await this.applyCommands(run, decision.commands);
+      await this.store.updateRun(run.id, {
+        status: "completed",
+        output: decision.output,
+        error: void 0,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.completed",
+        runId: run.id,
+        workflow: run.workflow,
+        output: decision.output
+      });
+      void this.notifyParent(run.id, {
+        ok: true,
+        value: decision.output
+      });
+      return {
+        runId: run.id,
+        status: "completed",
+        output: decision.output
+      };
+    }
+    if (decision.status === "failed") {
+      await this.applyCommands(run, decision.commands);
+      const error = decision.error ?? {
+        message: "workflow failed"
+      };
+      await this.store.updateRun(run.id, {
+        status: "failed",
+        error,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.failed",
+        runId: run.id,
+        workflow: run.workflow,
+        error
+      });
+      void this.notifyParent(run.id, {
+        ok: false,
+        error: error.message
+      });
+      return {
+        runId: run.id,
+        status: "failed",
+        error
+      };
+    }
+    const wakeAt = await this.applyCommands(run, decision.commands);
+    await this.store.updateRun(run.id, {
+      status: "suspended",
+      wakeAt,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "run.suspended",
+      runId: run.id,
+      workflow: run.workflow
+    });
+    return {
+      runId: run.id,
+      status: "suspended"
+    };
+  }
+  /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
+  async remoteHistory(runId) {
+    const checkpoints = await this.store.listCheckpoints(runId);
+    const kindOf = {
+      remote: "call",
+      local: "step",
+      sleep: "timer",
+      signal: "signal"
+    };
+    const events = [];
+    for (const cp of checkpoints) {
+      if (cp.status === "completed" || cp.status === "failed") {
+        if (cp.kind === "signal" && cp.name.startsWith("signal:child:")) {
+          const completion = cp.output;
+          events.push({
+            seq: cp.seq,
+            kind: "child",
+            output: completion?.ok ? completion.value : void 0,
+            error: completion && completion.ok === false ? {
+              message: completion.error
+            } : void 0
+          });
+          continue;
+        }
+        events.push({
+          seq: cp.seq,
+          kind: kindOf[cp.kind] ?? "step",
+          // A signal checkpoint's name is the internal `signal:<token>`, not the workflow-level signal
+          // name the replay used — omit it so the replay matches on seq + kind (its determinism anchor).
+          name: cp.kind === "signal" ? void 0 : cp.name,
+          output: cp.status === "completed" ? cp.output : void 0,
+          error: cp.status === "failed" ? cp.error : void 0
+        });
+      } else if (cp.kind === "sleep" && cp.wakeAt != null && cp.wakeAt <= this.clock()) {
+        events.push({
+          seq: cp.seq,
+          kind: "timer",
+          name: cp.name
+        });
+      }
+    }
+    return events.sort((a, b) => a.seq - b.seq);
+  }
+  /** Apply a turn's commands: persist recorded local steps, dispatch remote calls, schedule timers.
+  *  Returns the earliest timer deadline to suspend on (or undefined — suspended on a result). */
+  async applyCommands(run, commands) {
+    let wakeAt;
+    for (const cmd of commands) {
+      const at = /* @__PURE__ */ new Date();
+      const id = stepId(run.id, cmd.seq);
+      if (cmd.kind === "recordStep") {
+        const startedAt = cmd.startedAt != null ? new Date(cmd.startedAt) : at;
+        const finishedAt = cmd.finishedAt != null ? new Date(cmd.finishedAt) : at;
+        await this.store.saveCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "local",
+          stepId: id,
+          status: cmd.error ? "failed" : "completed",
+          output: cmd.output,
+          error: cmd.error,
+          events: cmd.events && cmd.events.length > 0 ? cmd.events : void 0,
+          attempts: 1,
+          enqueuedAt: startedAt,
+          startedAt,
+          finishedAt
+        });
+        this.emit({
+          type: cmd.error ? "step.failed" : "step.completed",
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "local",
+          output: cmd.output,
+          error: cmd.error
+        });
+      } else if (cmd.kind === "call") {
+        await this.store.saveCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "remote",
+          stepId: id,
+          status: "pending",
+          input: cmd.input,
+          attempts: 1,
+          workerGroup: cmd.group,
+          enqueuedAt: at,
+          startedAt: at,
+          finishedAt: at
+        });
+        await this.pool.dispatch({
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          stepId: id,
+          group: cmd.group,
+          input: cmd.input,
+          traceparent: this.traceparent?.(),
+          context: this.context?.(),
+          attempt: 1
+        }, void 0);
+        this.emit({
+          type: "step.started",
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "remote"
+        });
+      } else if (cmd.kind === "sleep") {
+        const deadline = this.clock() + cmd.ms;
+        await this.store.saveCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: `sleep:${cmd.seq}`,
+          kind: "sleep",
+          stepId: id,
+          status: "pending",
+          attempts: 1,
+          wakeAt: deadline,
+          enqueuedAt: at,
+          startedAt: at,
+          finishedAt: at
+        });
+        wakeAt = wakeAt == null ? deadline : Math.min(wakeAt, deadline);
+      } else if (cmd.kind === "waitSignal") {
+        const buffered = await this.store.takeBufferedSignal(cmd.signal);
+        if (buffered) {
+          await this.store.saveCheckpoint(instantCheckpoint({
+            runId: run.id,
+            seq: cmd.seq,
+            name: `signal:${cmd.signal}`,
+            kind: "signal",
+            output: buffered.payload
+          }));
+          setTimeout(() => void this.resume(run.id).catch(() => void 0), 0);
+        } else {
+          await this.store.putSignalWaiter({
+            token: cmd.signal,
+            runId: run.id,
+            seq: cmd.seq
+          });
+        }
+      } else if (cmd.kind === "startChild") {
+        const childId = `${run.id}.child.${cmd.seq}`;
+        await this.store.putSignalWaiter({
+          token: `child:${childId}`,
+          runId: run.id,
+          seq: cmd.seq
+        });
+        if (!await this.store.getRun(childId)) {
+          queueMicrotask(() => void this.start(cmd.workflow, cmd.input, childId).catch(() => void 0));
+        }
+      } else {
+        throw new Error(`remote workflow command '${cmd.kind}' is not supported yet`);
+      }
+    }
+    return wakeAt;
+  }
+  /** The run body, lease held + renewed by {@link execute}. */
+  async runExecution(run, fn, registered) {
+    if (run.status === "pending") {
+      await this.store.updateRun(run.id, {
+        status: "running",
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      run.status = "running";
+      this.emit({
+        type: "run.started",
+        runId: run.id,
+        workflow: run.workflow
+      });
+    }
+    if (registered?.singleton && !await this.admitSingleton(run, registered.singleton)) {
+      const wakeAt = singletonRetryWakeAt(this.clock());
+      await this.store.updateRun(run.id, {
+        status: "suspended",
+        wakeAt,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.suspended",
+        runId: run.id,
+        workflow: run.workflow
+      });
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: "suspended"
+      };
+    }
+    const compensations = [];
+    const snapshot = await this.store.listCheckpoints(run.id);
+    const replay = /* @__PURE__ */ new Map();
+    for (const cp of snapshot) replay.set(cp.seq, cp);
+    const ctx = createWorkflowCtx(this.ctxHostFor(replay), run.id, compensations, run.workflow);
+    try {
+      const output = await fn(ctx, run.input);
+      await this.store.updateRun(run.id, {
+        status: "completed",
+        output,
+        error: void 0,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.completed",
+        runId: run.id,
+        workflow: run.workflow,
+        output
+      });
+      void this.notifyParent(run.id, {
+        ok: true,
+        value: output
+      });
+      return {
+        runId: run.id,
+        status: "completed",
+        output
+      };
+    } catch (err) {
+      if (err instanceof ContinueAsNew) {
+        await this.store.updateRun(run.id, {
+          status: "completed",
+          output: void 0,
+          error: void 0,
+          updatedAt: /* @__PURE__ */ new Date()
+        });
+        this.emit({
+          type: "run.completed",
+          runId: run.id,
+          workflow: run.workflow
+        });
+        void this.notifyParent(run.id, {
+          ok: true,
+          value: void 0
+        });
+        const nextId = nextContinuationId(run.id);
+        queueMicrotask(() => void this.start(run.workflow, err.input, nextId).catch(() => void 0));
+        return {
+          runId: run.id,
+          status: "completed"
+        };
+      }
+      if (err instanceof WorkflowSuspended) {
+        if (this.cancelRequested.has(run.id)) {
+          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 error2 = {
+            message: "cancelled"
+          };
+          await this.store.updateRun(run.id, {
+            status: "cancelled",
+            error: error2,
+            updatedAt: /* @__PURE__ */ new Date()
+          });
+          this.emit({
+            type: "run.failed",
+            runId: run.id,
+            workflow: run.workflow,
+            error: error2
+          });
+          return {
+            runId: run.id,
+            status: "cancelled",
+            error: error2
+          };
+        }
+        await this.store.updateRun(run.id, {
+          status: "suspended",
+          wakeAt: err.wakeAt,
+          updatedAt: /* @__PURE__ */ new Date()
+        });
+        this.emit({
+          type: "run.suspended",
+          runId: run.id,
+          workflow: run.workflow
+        });
+        return {
+          runId: run.id,
+          status: "suspended"
+        };
+      }
+      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);
+      }
+      await this.store.updateRun(run.id, {
+        status: "failed",
+        error,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.failed",
+        runId: run.id,
+        workflow: run.workflow,
+        error
+      });
+      void this.notifyParent(run.id, {
+        ok: false,
+        error: error.message
+      });
+      return {
+        runId: run.id,
+        status: "failed",
+        error
+      };
+    } finally {
+      await this.store.releaseRunLock(run.id);
+    }
+  }
+  /**
+  * 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.
+  */
+  async runCompensation(run, comp) {
+    const name = `compensate:${comp.name}`;
+    for (let attempt = 1; attempt <= this.compensationRetries; attempt += 1) {
+      const startedAt = Date.now();
+      try {
+        await comp.fn();
+        this.emit({
+          type: "step.completed",
+          runId: run.id,
+          workflow: run.workflow,
+          name,
+          kind: "local",
+          durationMs: Date.now() - startedAt
+        });
+        return;
+      } catch (err) {
+        if (attempt >= this.compensationRetries) {
+          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
+          });
+        }
+      }
+    }
+  }
+  /** 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. */
+  ctxHostFor(replay) {
+    return {
+      store: this.store,
+      replay,
+      clock: this.clock,
+      webhookUrl: this.webhookUrl,
+      startStep: /* @__PURE__ */ __name((s) => this.startStep(s), "startStep"),
+      completeStep: /* @__PURE__ */ __name((s) => this.completeStep(s), "completeStep"),
+      failStep: /* @__PURE__ */ __name((s) => this.failStep(s), "failStep"),
+      callRemote: /* @__PURE__ */ __name((runId, seq, step, input, queue, transport, admission) => this.callRemote(runId, seq, step, input, queue, transport, replay, admission), "callRemote"),
+      // Defer so a fast child can't reentrantly resume a still-running parent.
+      startChild: /* @__PURE__ */ __name((workflow, input, id) => {
+        queueMicrotask(() => void this.start(workflow, input, id).catch(() => void 0));
+      }, "startChild"),
+      signalEntity: /* @__PURE__ */ __name((name, key, op, arg, reply) => {
+        queueMicrotask(() => void this.entities.dispatch(name, key, op, arg, reply).catch(() => void 0));
+      }, "signalEntity"),
+      interceptStep: /* @__PURE__ */ __name((invocation, body) => this.interceptStep(invocation, body), "interceptStep")
+    };
+  }
+  /**
+  * Resume a run paused at a {@link WorkflowCtx.breakpoint} (e.g. the dashboard "continue" button).
+  * Finds the run's pending breakpoint checkpoint and signals it. Returns null if the run isn't
+  * paused at a breakpoint.
+  */
+  async continue(runId) {
+    const checkpoints = await this.store.listCheckpoints(runId);
+    const bp = checkpoints.find(isBreakpoint);
+    if (!bp) return null;
+    return this.signal(breakpointToken(runId, bp.seq), void 0);
+  }
+  /**
+  * Read the latest value a run published for `key` via {@link WorkflowCtx.setEvent} — a
+  * side-effect-free query of a live (or finished) run's state. Returns `undefined` if the run
+  * never published that key. The suspend-model counterpart of a Temporal query.
+  */
+  async getEvent(runId, key) {
+    const name = `event:${key}`;
+    const checkpoints = await this.store.listCheckpoints(runId);
+    let latest;
+    for (const cp of checkpoints) if (cp.name === name) latest = cp.output;
+    return latest;
+  }
+  /**
+  * Register a validator gating `engine.update(runId, name, …)` for runs of `workflow`. The
+  * validator runs BEFORE the update is delivered, so a rejection leaves the run untouched. One
+  * validator per (workflow, update name); registering again replaces it.
+  */
+  registerUpdateValidator(workflow, name, validate) {
+    this.updateValidators.set(`${workflow}:${name}`, validate);
+  }
+  /**
+  * Deliver a validated update to the run waiting at `ctx.onUpdate(name)`. Runs the registered
+  * validator (if any) first: on rejection returns `{ accepted: false, reason }` without disturbing
+  * the run; otherwise delivers `arg` and resumes, returning `{ accepted: true, run }` (`run` is null
+  * if nothing was waiting — a too-early or duplicate update).
+  */
+  async update(runId, name, arg) {
+    const run = await this.store.getRun(runId);
+    if (!run) return {
+      accepted: false,
+      reason: `run ${runId} not found`
+    };
+    const validate = this.updateValidators.get(`${run.workflow}:${name}`);
+    if (validate) {
+      try {
+        const reason = await validate(arg);
+        if (typeof reason === "string" && reason.length > 0) return {
+          accepted: false,
+          reason
+        };
+      } catch (err) {
+        return {
+          accepted: false,
+          reason: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+    const result = await this.signal(`update:${runId}:${name}`, arg);
+    return {
+      accepted: true,
+      run: result
+    };
+  }
+  async callRemote(runId, seq, step, input, queue, transport, replay, admission) {
+    const existing = replay?.get(seq) ?? await this.store.getCheckpoint(runId, seq);
+    if (existing && existing.name !== step.name) {
+      throw new NonDeterminismError(runId, seq, step.name, existing.name);
+    }
+    if (existing?.status === "completed") return existing.output;
+    if (this.pool.size === 0) throw new Error("remote steps require a Transport");
+    if (step.timeoutMs) return this.callRemoteInMemory(runId, seq, step, input, transport);
+    if (existing?.status === "pending") throw new WorkflowSuspended();
+    let attempt = 1;
+    if (existing?.status === "failed") {
+      const maxAttempts = Math.max(1, step.retries ?? 1);
+      const retryable = existing.error?.retryable !== false;
+      if (!retryable || existing.attempts >= maxAttempts) throw new RemoteStepError(existing.error);
+      if (existing.wakeAt == null) {
+        const wakeAt = this.clock() + backoffDelay(existing.attempts, step);
+        await this.store.saveCheckpoint({
+          ...existing,
+          wakeAt
+        });
+        throw new WorkflowSuspended(wakeAt);
+      }
+      if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
+      attempt = existing.attempts + 1;
+    }
+    const id = stepId(runId, seq);
+    const controller = queue ? this.queues.get(queue) : void 0;
+    if (controller) {
+      const decision = controller.tryAdmit({
+        priority: admission?.priority,
+        key: admission?.fairnessKey ?? runId,
+        waiterId: id
+      });
+      if (!decision.ok) throw new WorkflowSuspended(decision.retryAt);
+      this.stepQueue.set(id, queue);
+    }
+    const validInput = step.input.parse(input);
+    const enqueuedAt = /* @__PURE__ */ new Date();
+    await this.store.saveCheckpoint({
+      runId,
+      seq,
+      name: step.name,
+      kind: "remote",
+      stepId: id,
+      status: "pending",
+      input: validInput,
+      attempts: attempt,
+      workerGroup: step.group,
+      enqueuedAt,
+      startedAt: enqueuedAt,
+      finishedAt: enqueuedAt
+    });
+    await this.pool.dispatch({
+      runId,
+      seq,
+      name: step.name,
+      stepId: id,
+      group: step.group,
+      input: validInput,
+      traceparent: this.traceparent?.(),
+      context: this.context?.(),
+      attempt
+    }, transport);
+    this.emit({
+      type: "step.started",
+      runId,
+      seq,
+      name: step.name,
+      kind: "remote"
+    });
+    throw new WorkflowSuspended();
+  }
+  /**
+  * Complete a durable remote step from its worker result and resume the run — runs on whichever
+  * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
+  * A no-op if the checkpoint isn't `pending` (a duplicate or late delivery).
+  */
+  async completeRemoteResult(result) {
+    const cp = await this.store.getCheckpoint(result.runId, result.seq);
+    if (!cp || cp.status !== "pending") return;
+    this.releaseQueueSlot(cp.stepId);
+    const run = await this.store.getRun(result.runId);
+    if (run && (run.status === "cancelled" || run.status === "completed")) return;
+    const finishedAt = /* @__PURE__ */ new Date();
+    const startedAt = result.startedAt ? new Date(result.startedAt) : cp.startedAt;
+    await this.store.saveCheckpoint({
+      ...cp,
+      status: result.status,
+      output: result.status === "completed" ? result.output : cp.output,
+      error: result.error,
+      events: result.events ?? cp.events,
+      startedAt,
+      finishedAt
+    });
+    this.emit({
+      type: result.status === "completed" ? "step.completed" : "step.failed",
+      runId: result.runId,
+      seq: result.seq,
+      name: cp.name,
+      kind: cp.kind,
+      output: result.output,
+      error: result.error,
+      queueMs: startedAt.getTime() - cp.enqueuedAt.getTime(),
+      durationMs: finishedAt.getTime() - startedAt.getTime()
+    });
+    await this.resume(result.runId);
+  }
+  /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
+  releaseQueueSlot(id) {
+    const queue = this.stepQueue.get(id);
+    if (queue === void 0) return;
+    this.stepQueue.delete(id);
+    this.queues.get(queue)?.release();
+  }
+  /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
+  async callRemoteInMemory(runId, seq, step, input, transport) {
+    if (this.pool.size === 0) throw new Error("remote steps require a Transport");
+    const validInput = step.input.parse(input);
+    const id = stepId(runId, seq);
+    const enqueuedAt = /* @__PURE__ */ new Date();
+    this.emit({
+      type: "step.started",
+      runId,
+      seq,
+      name: step.name,
+      kind: "remote"
+    });
+    const maxAttempts = step.timeoutMs ? Math.max(1, step.retries ?? 1) : 1;
+    for (let attempt = 1; ; attempt += 1) {
+      const resultPromise = new Promise((resolve, reject) => {
+        this.pending.set(id, {
+          resolve,
+          reject
+        });
+      });
+      await this.pool.dispatch({
+        runId,
+        seq,
+        name: step.name,
+        stepId: id,
+        group: step.group,
+        input: validInput,
+        traceparent: this.traceparent?.(),
+        context: this.context?.(),
+        attempt
+      }, transport);
+      try {
+        const resolution = step.timeoutMs ? await this.awaitWithHeartbeat(id, resultPromise, step.timeoutMs) : await resultPromise;
+        const output = step.output.parse(resolution.output);
+        const startedAt = resolution.startedAt ? new Date(resolution.startedAt) : enqueuedAt;
+        await this.completeStep({
+          runId,
+          seq,
+          name: step.name,
+          kind: "remote",
+          input: validInput,
+          output,
+          events: resolution.events,
+          attempts: attempt,
+          workerGroup: step.group,
+          enqueuedAt,
+          startedAt
+        });
+        return output;
+      } catch (err) {
+        this.pending.delete(id);
+        if (err instanceof RemoteStepTimeout && attempt < maxAttempts) continue;
+        throw err;
+      }
+    }
+  }
+  /**
+  * Await a remote result, but reject with `RemoteStepTimeout` if neither the result nor a heartbeat
+  * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`) rearms the
+  * window, so a worker that keeps beating stays alive past `timeoutMs`.
+  */
+  awaitWithHeartbeat(id, resultPromise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let timer;
+      const cleanup = /* @__PURE__ */ __name(() => {
+        clearTimeout(timer);
+        this.heartbeatResets.delete(id);
+      }, "cleanup");
+      const arm = /* @__PURE__ */ __name(() => {
+        timer = setTimeout(() => {
+          cleanup();
+          this.pending.delete(id);
+          reject(new RemoteStepTimeout(id, timeoutMs));
+        }, timeoutMs);
+        timer.unref?.();
+      }, "arm");
+      this.heartbeatResets.set(id, () => {
+        clearTimeout(timer);
+        arm();
+      });
+      arm();
+      resultPromise.then((value) => {
+        cleanup();
+        resolve(value);
+      }, (err) => {
+        cleanup();
+        reject(err);
+      });
+    });
+  }
+};
+var RemoteStepError = class extends Error {
+  static {
+    __name(this, "RemoteStepError");
+  }
+  stepError;
+  constructor(stepError) {
+    super(stepError?.message ?? "remote step failed");
+    this.name = "RemoteStepError";
+    this.stepError = stepError;
+  }
+};
+
+// src/remote-step-factory.ts
+function remoteStep(config) {
+  return {
+    ...config,
+    group: config.group ?? config.name.split(".")[0] ?? config.name,
+    __remote: true
+  };
+}
+__name(remoteStep, "remoteStep");
+
+// src/remote-workflow-executor.ts
+var taskCounter = 0;
+var RemoteWorkflowExecutor = class {
+  static {
+    __name(this, "RemoteWorkflowExecutor");
+  }
+  transport;
+  group;
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  subscribed = false;
+  constructor(transport, group, opts = {}) {
+    this.transport = transport;
+    this.group = group;
+    this.opts = opts;
+  }
+  ensureSubscribed() {
+    if (this.subscribed) return;
+    if (!this.transport.onDecision) {
+      throw new Error("transport does not support workflow decisions (onDecision)");
+    }
+    this.subscribed = true;
+    this.transport.onDecision(async (decision) => {
+      const resolve = this.pending.get(decision.taskId);
+      if (resolve) {
+        this.pending.delete(decision.taskId);
+        resolve(decision);
+      }
+    });
+  }
+  async advance(run, history) {
+    if (!this.transport.dispatchWorkflowTask) {
+      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
+    }
+    this.ensureSubscribed();
+    taskCounter += 1;
+    const taskId = `${run.id}:wf:${taskCounter}`;
+    const task = {
+      taskId,
+      runId: run.id,
+      workflow: run.workflow,
+      workflowVersion: run.workflowVersion,
+      input: run.input,
+      history,
+      group: this.group,
+      attempt: 1
+    };
+    const decision = new Promise((resolve, reject) => {
+      this.pending.set(taskId, resolve);
+      if (this.opts.timeoutMs) {
+        const timer = setTimeout(() => {
+          this.pending.delete(taskId);
+          reject(new Error(`workflow task ${taskId} timed out after ${this.opts.timeoutMs}ms`));
+        }, this.opts.timeoutMs);
+        timer.unref?.();
+      }
+    });
+    await this.transport.dispatchWorkflowTask(task);
+    return decision;
+  }
+};
+
+// src/codec-state-store.ts
+var CodecStateStore = class {
+  static {
+    __name(this, "CodecStateStore");
+  }
+  inner;
+  codec;
+  constructor(inner, codec) {
+    this.inner = inner;
+    this.codec = codec;
+  }
+  enc(v) {
+    return v === void 0 ? void 0 : this.codec.encode(v);
+  }
+  dec(v) {
+    return v === void 0 ? void 0 : this.codec.decode(v);
+  }
+  encRun(run) {
+    return {
+      ...run,
+      input: this.enc(run.input),
+      output: this.enc(run.output)
+    };
+  }
+  decRun(run) {
+    return run && {
+      ...run,
+      input: this.dec(run.input),
+      output: this.dec(run.output)
+    };
+  }
+  encCp(cp) {
+    return {
+      ...cp,
+      input: this.enc(cp.input),
+      output: this.enc(cp.output)
+    };
+  }
+  decCp(cp) {
+    return cp && {
+      ...cp,
+      input: this.dec(cp.input),
+      output: this.dec(cp.output)
+    };
+  }
+  ensureSchema() {
+    return this.inner.ensureSchema?.() ?? Promise.resolve();
+  }
+  createRun(run) {
+    return this.inner.createRun(this.encRun(run));
+  }
+  updateRun(runId, patch) {
+    const next = {
+      ...patch
+    };
+    if ("input" in patch) next.input = this.enc(patch.input);
+    if ("output" in patch) next.output = this.enc(patch.output);
+    return this.inner.updateRun(runId, next);
+  }
+  async getRun(runId) {
+    return this.decRun(await this.inner.getRun(runId));
+  }
+  async getCheckpoint(runId, seq) {
+    return this.decCp(await this.inner.getCheckpoint(runId, seq));
+  }
+  saveCheckpoint(checkpoint) {
+    return this.inner.saveCheckpoint(this.encCp(checkpoint));
+  }
+  transaction(work) {
+    if (!this.inner.transaction) {
+      throw new Error("the wrapped store does not support transactions");
+    }
+    return this.inner.transaction((tx) => work({
+      raw: tx.raw,
+      saveCheckpoint: /* @__PURE__ */ __name((cp) => tx.saveCheckpoint(this.encCp(cp)), "saveCheckpoint")
+    }));
+  }
+  async listIncompleteRuns() {
+    return (await this.inner.listIncompleteRuns()).map((r) => this.decRun(r));
+  }
+  async listPendingRuns(limit) {
+    return (await this.inner.listPendingRuns(limit)).map((r) => this.decRun(r));
+  }
+  async listDueTimers(nowMs) {
+    return (await this.inner.listDueTimers(nowMs)).map((r) => this.decRun(r));
+  }
+  tryLockRun(runId, owner, leaseUntilMs, nowMs) {
+    return this.inner.tryLockRun(runId, owner, leaseUntilMs, nowMs);
+  }
+  releaseRunLock(runId) {
+    return this.inner.releaseRunLock(runId);
+  }
+  renewRunLock(runId, owner, leaseUntilMs) {
+    return this.inner.renewRunLock(runId, owner, leaseUntilMs);
+  }
+  putSignalWaiter(waiter) {
+    return this.inner.putSignalWaiter(waiter);
+  }
+  takeSignalWaiter(token) {
+    return this.inner.takeSignalWaiter(token);
+  }
+  listSignalWaiters(prefix) {
+    return this.inner.listSignalWaiters(prefix);
+  }
+  bufferSignal(token, payload) {
+    return this.inner.bufferSignal(token, this.enc(payload));
+  }
+  async takeBufferedSignal(token) {
+    const buffered = await this.inner.takeBufferedSignal(token);
+    return buffered && {
+      payload: this.dec(buffered.payload)
+    };
+  }
+  async listRuns(query) {
+    return (await this.inner.listRuns(query)).map((r) => this.decRun(r));
+  }
+  async listCheckpoints(runId) {
+    return (await this.inner.listCheckpoints(runId)).map((c) => this.decCp(c));
+  }
+};
+
+// src/metrics.ts
+function collectMetrics(engine) {
+  const m = {
+    runs: {
+      started: 0,
+      completed: 0,
+      failed: 0,
+      suspended: 0
+    },
+    steps: {
+      started: 0,
+      completed: 0,
+      failed: 0
+    },
+    byWorkflow: {},
+    stepDuration: {
+      sumMs: 0,
+      count: 0
+    }
+  };
+  const wf = /* @__PURE__ */ __name((name) => {
+    const k = name ?? "unknown";
+    return m.byWorkflow[k] ??= {
+      started: 0,
+      completed: 0,
+      failed: 0
+    };
+  }, "wf");
+  const stop = engine.subscribe((e) => {
+    switch (e.type) {
+      case "run.started":
+        m.runs.started += 1;
+        wf(e.workflow).started += 1;
+        break;
+      case "run.completed":
+        m.runs.completed += 1;
+        wf(e.workflow).completed += 1;
+        break;
+      case "run.failed":
+        m.runs.failed += 1;
+        wf(e.workflow).failed += 1;
+        break;
+      case "run.suspended":
+        m.runs.suspended += 1;
+        break;
+      case "step.started":
+        m.steps.started += 1;
+        break;
+      case "step.completed":
+        m.steps.completed += 1;
+        if (e.durationMs != null) {
+          m.stepDuration.sumMs += e.durationMs;
+          m.stepDuration.count += 1;
+        }
+        break;
+      case "step.failed":
+        m.steps.failed += 1;
+        break;
+    }
+  });
+  return {
+    snapshot: /* @__PURE__ */ __name(() => structuredClone(m), "snapshot"),
+    stop,
+    prometheus: /* @__PURE__ */ __name(() => {
+      const lines = [];
+      lines.push("# TYPE durable_runs_total counter");
+      for (const [k, v] of Object.entries(m.runs)) lines.push(`durable_runs_total{event="${k}"} ${v}`);
+      lines.push("# TYPE durable_steps_total counter");
+      for (const [k, v] of Object.entries(m.steps)) lines.push(`durable_steps_total{event="${k}"} ${v}`);
+      lines.push("# TYPE durable_runs_by_workflow_total counter");
+      for (const [name, v] of Object.entries(m.byWorkflow)) for (const [event, n] of Object.entries(v)) lines.push(`durable_runs_by_workflow_total{workflow="${name}",event="${event}"} ${n}`);
+      lines.push("# TYPE durable_step_duration_ms_sum counter");
+      lines.push(`durable_step_duration_ms_sum ${m.stepDuration.sumMs}`);
+      lines.push("# TYPE durable_step_duration_count counter");
+      lines.push(`durable_step_duration_count ${m.stepDuration.count}`);
+      return `${lines.join("\n")}
+`;
+    }, "prometheus")
+  };
+}
+__name(collectMetrics, "collectMetrics");
+
+// src/scheduler.ts
+var import_node_module = require("module");
+var nodeRequire = (0, import_node_module.createRequire)(__importMetaUrl);
+var defaultSleep = /* @__PURE__ */ __name((ms) => new Promise((r) => setTimeout(r, ms)), "defaultSleep");
+function scheduledRunId(key, everyMs, nowMs) {
+  return `sched:${key}:${Math.floor(nowMs / everyMs)}`;
+}
+__name(scheduledRunId, "scheduledRunId");
+var cronParser;
+function loadCronParser() {
+  if (cronParser) return cronParser;
+  try {
+    cronParser = nodeRequire("cron-parser");
+  } catch {
+    throw new Error('cron schedules need the optional peer dependency "cron-parser" \u2014 install it (e.g. `npm i cron-parser`).');
+  }
+  return cronParser;
+}
+__name(loadCronParser, "loadCronParser");
+function prevCronFireMs(expr, nowMs, timezone = "UTC") {
+  const parser = loadCronParser();
+  const it = parser.parseExpression(expr, {
+    currentDate: new Date(nowMs + 1),
+    tz: timezone
+  });
+  return it.prev().toDate().getTime();
+}
+__name(prevCronFireMs, "prevCronFireMs");
+function scheduleRunIdAt(s, nowMs) {
+  if (s.cron != null) return `sched:${s.key}:${prevCronFireMs(s.cron, nowMs, s.timezone)}`;
+  if (s.everyMs != null) return scheduledRunId(s.key, s.everyMs, nowMs);
+  throw new Error(`schedule "${s.key}" needs either "everyMs" or "cron"`);
+}
+__name(scheduleRunIdAt, "scheduleRunIdAt");
+function scheduleRunIdsAt(s, nowMs) {
+  const current = scheduleRunIdAt(s, nowMs);
+  if (!s.backfill || s.backfill.maxCatchup <= 0) return [
+    current
+  ];
+  const ids = [];
+  if (s.everyMs != null) {
+    const bucket = Math.floor(nowMs / s.everyMs);
+    const oldest = Math.max(0, bucket - s.backfill.maxCatchup);
+    for (let b = oldest; b < bucket; b += 1) ids.push(`sched:${s.key}:${b}`);
+  } else if (s.cron != null) {
+    const prior = [];
+    let cursor = prevCronFireMs(s.cron, nowMs, s.timezone);
+    for (let i = 0; i < s.backfill.maxCatchup; i += 1) {
+      const before = prevCronFireMs(s.cron, cursor - 1, s.timezone);
+      prior.push(`sched:${s.key}:${before}`);
+      cursor = before;
+    }
+    ids.push(...prior.reverse());
+  }
+  ids.push(current);
+  return ids;
+}
+__name(scheduleRunIdsAt, "scheduleRunIdsAt");
+async function runSchedules(engine, schedules, nowMs, opts) {
+  const random = opts?.random ?? Math.random;
+  const sleep = opts?.sleep ?? defaultSleep;
+  const ids = [];
+  for (const s of schedules) {
+    if (s.paused) continue;
+    if (s.overlap === "skip" && s.everyMs) {
+      const prevBucket = Math.floor(nowMs / s.everyMs) - 1;
+      if (prevBucket >= 0) {
+        const prev = await engine.getRun(`sched:${s.key}:${prevBucket}`);
+        if (prev && (prev.status === "running" || prev.status === "suspended")) continue;
+      }
+    }
+    if (s.jitter && s.jitter > 0) await sleep(Math.floor(random() * s.jitter));
+    for (const runId of scheduleRunIdsAt(s, nowMs)) {
+      await engine.start(s.workflow, s.input, runId);
+      ids.push(runId);
+    }
+  }
+  return ids;
+}
+__name(runSchedules, "runSchedules");
+
+// src/search-attributes.ts
+function compare(actual, op, expected) {
+  switch (op) {
+    case "eq":
+      return actual === expected;
+    case "ne":
+      return actual !== expected;
+    case "gt":
+      return actual != null && actual > expected;
+    case "gte":
+      return actual != null && actual >= expected;
+    case "lt":
+      return actual != null && actual < expected;
+    case "lte":
+      return actual != null && actual <= expected;
+  }
+}
+__name(compare, "compare");
+function matchesAttributes(attributes, filters) {
+  if (!filters?.length) return true;
+  if (!attributes) return false;
+  return filters.every((f) => f.key in attributes && compare(attributes[f.key], f.op, f.value));
+}
+__name(matchesAttributes, "matchesAttributes");
+function applyAttributeQuery(rows, query) {
+  const filtered = rows.filter((r) => matchesAttributes(r.searchAttributes, query.attributes));
+  const offset = query.offset ?? 0;
+  const limit = query.limit ?? filtered.length;
+  return filtered.slice(offset, offset + limit);
+}
+__name(applyAttributeQuery, "applyAttributeQuery");
+function normalizeAttributeRows(runId, attributes) {
+  if (!attributes) return [];
+  const out = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (typeof value === "number") {
+      out.push({
+        runId,
+        key,
+        strValue: null,
+        numValue: value
+      });
+    } else if (typeof value === "boolean") {
+      out.push({
+        runId,
+        key,
+        strValue: value ? "true" : "false",
+        numValue: null
+      });
+    } else {
+      out.push({
+        runId,
+        key,
+        strValue: value,
+        numValue: null
+      });
+    }
+  }
+  return out;
+}
+__name(normalizeAttributeRows, "normalizeAttributeRows");
+function sqlComparator(op) {
+  switch (op) {
+    case "eq":
+      return "=";
+    case "ne":
+      return "<>";
+    case "gt":
+      return ">";
+    case "gte":
+      return ">=";
+    case "lt":
+      return "<";
+    case "lte":
+      return "<=";
+  }
+}
+__name(sqlComparator, "sqlComparator");
+function attributeColumnFor(filter) {
+  return typeof filter.value === "number" ? "numValue" : "strValue";
+}
+__name(attributeColumnFor, "attributeColumnFor");
+function attributeOperand(filter) {
+  if (typeof filter.value === "boolean") return filter.value ? "true" : "false";
+  return filter.value;
+}
+__name(attributeOperand, "attributeOperand");
+
+// src/tokens.ts
+var STATE_STORE = Symbol("nestjs-durable:STATE_STORE");
+var TRANSPORT = Symbol("nestjs-durable:TRANSPORT");
+var DURABLE_OPTIONS = Symbol("nestjs-durable:DURABLE_OPTIONS");
+
+// src/testing/in-memory-state-store.ts
+var InMemoryStateStore = class {
+  static {
+    __name(this, "InMemoryStateStore");
+  }
+  runs = /* @__PURE__ */ new Map();
+  checkpoints = /* @__PURE__ */ new Map();
+  signalWaiters = /* @__PURE__ */ new Map();
+  /**
+  * Normalized search-attribute side-table, the in-memory analog of the SQL stores'
+  * `durable_run_attributes`: `key -> (runId -> row)`. Maintained on every create/update so an
+  * attribute query can be pushed DOWN to a key-indexed candidate set instead of scanning every run
+  * and comparing in-process. Mirrors {@link normalizeAttributeRows} so behavior matches the SQL path.
+  */
+  attributeIndex = /* @__PURE__ */ new Map();
+  /** Test/observability hook: how many candidate runs the last attribute query's index produced. */
+  lastAttributeCandidates = 0;
+  key(runId, seq) {
+    return `${runId}:${seq}`;
+  }
+  /** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
+  reindexAttributes(runId, attributes) {
+    for (const byRun of this.attributeIndex.values()) byRun.delete(runId);
+    for (const row of normalizeAttributeRows(runId, attributes)) {
+      let byRun = this.attributeIndex.get(row.key);
+      if (!byRun) {
+        byRun = /* @__PURE__ */ new Map();
+        this.attributeIndex.set(row.key, byRun);
+      }
+      byRun.set(runId, row);
+    }
+  }
+  async createRun(run) {
+    this.runs.set(run.id, {
+      ...run
+    });
+    this.reindexAttributes(run.id, run.searchAttributes);
+  }
+  async updateRun(runId, patch) {
+    const existing = this.runs.get(runId);
+    if (!existing) throw new Error(`run ${runId} not found`);
+    const next = {
+      ...existing,
+      ...patch
+    };
+    this.runs.set(runId, next);
+    if ("searchAttributes" in patch) this.reindexAttributes(runId, next.searchAttributes);
+  }
+  async getRun(runId) {
+    const run = this.runs.get(runId);
+    return run ? {
+      ...run
+    } : null;
+  }
+  async getCheckpoint(runId, seq) {
+    const cp = this.checkpoints.get(this.key(runId, seq));
+    return cp ? {
+      ...cp
+    } : null;
+  }
+  async saveCheckpoint(checkpoint) {
+    this.checkpoints.set(this.key(checkpoint.runId, checkpoint.seq), {
+      ...checkpoint
+    });
+  }
+  async listIncompleteRuns() {
+    return [
+      ...this.runs.values()
+    ].filter((r) => r.status === "running").map((r) => ({
+      ...r
+    }));
+  }
+  async listPendingRuns(limit) {
+    return [
+      ...this.runs.values()
+    ].filter((r) => r.status === "pending").sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id)).slice(0, limit).map((r) => ({
+      ...r
+    }));
+  }
+  async listDueTimers(nowMs) {
+    return [
+      ...this.runs.values()
+    ].filter((r) => r.status === "suspended" && r.wakeAt !== void 0 && r.wakeAt <= nowMs).map((r) => ({
+      ...r
+    }));
+  }
+  async tryLockRun(runId, owner, leaseUntilMs, nowMs) {
+    const run = this.runs.get(runId);
+    if (!run) return false;
+    if (run.lockedUntil !== void 0 && run.lockedUntil > nowMs) return false;
+    run.lockedBy = owner;
+    run.lockedUntil = leaseUntilMs;
+    return true;
+  }
+  async releaseRunLock(runId) {
+    const run = this.runs.get(runId);
+    if (run) {
+      run.lockedBy = void 0;
+      run.lockedUntil = void 0;
+    }
+  }
+  async renewRunLock(runId, owner, leaseUntilMs) {
+    const run = this.runs.get(runId);
+    if (!run || run.lockedBy !== owner) return false;
+    run.lockedUntil = leaseUntilMs;
+    return true;
+  }
+  async putSignalWaiter(waiter) {
+    this.signalWaiters.set(waiter.token, {
+      ...waiter
+    });
+  }
+  async takeSignalWaiter(token) {
+    const waiter = this.signalWaiters.get(token);
+    if (!waiter) return null;
+    this.signalWaiters.delete(token);
+    return {
+      ...waiter
+    };
+  }
+  async listSignalWaiters(prefix) {
+    return [
+      ...this.signalWaiters.values()
+    ].filter((w) => w.token.startsWith(prefix)).map((w) => ({
+      ...w
+    }));
+  }
+  // No real DB transaction (there's no DB) — run the work and save the checkpoint. Exactly-once
+  // across a crash needs a SQL store; this keeps `ctx.transaction` usable in tests / local dev.
+  async transaction(work) {
+    return work({
+      raw: this,
+      saveCheckpoint: /* @__PURE__ */ __name((cp) => this.saveCheckpoint(cp), "saveCheckpoint")
+    });
+  }
+  bufferedSignals = /* @__PURE__ */ new Map();
+  async bufferSignal(token, payload) {
+    const queue = this.bufferedSignals.get(token) ?? [];
+    queue.push(payload);
+    this.bufferedSignals.set(token, queue);
+  }
+  async takeBufferedSignal(token) {
+    const queue = this.bufferedSignals.get(token);
+    if (!queue || queue.length === 0) return null;
+    const payload = queue.shift();
+    if (queue.length === 0) this.bufferedSignals.delete(token);
+    return {
+      payload
+    };
+  }
+  /**
+  * Candidate run ids satisfying ONE attribute predicate, served from {@link attributeIndex} — the
+  * pushdown step. Numeric predicates scan only `numValue` rows under the key; string/boolean ones
+  * scan `strValue` rows. This is the in-memory analog of the SQL EXISTS on `durable_run_attributes`.
+  */
+  candidatesForFilter(f) {
+    const byRun = this.attributeIndex.get(f.key);
+    const out = /* @__PURE__ */ new Set();
+    if (!byRun) return out;
+    const numeric = typeof f.value === "number";
+    const operand = typeof f.value === "boolean" ? f.value ? "true" : "false" : f.value;
+    for (const row of byRun.values()) {
+      const actual = numeric ? row.numValue : row.strValue;
+      if (actual == null) continue;
+      let ok = false;
+      switch (f.op) {
+        case "eq":
+          ok = actual === operand;
+          break;
+        case "ne":
+          ok = actual !== operand;
+          break;
+        case "gt":
+          ok = actual > operand;
+          break;
+        case "gte":
+          ok = actual >= operand;
+          break;
+        case "lt":
+          ok = actual < operand;
+          break;
+        case "lte":
+          ok = actual <= operand;
+          break;
+      }
+      if (ok) out.add(row.runId);
+    }
+    return out;
+  }
+  async listRuns(query) {
+    let runs = [
+      ...this.runs.values()
+    ];
+    if (query.workflow) runs = runs.filter((r) => r.workflow === query.workflow);
+    if (query.status) runs = runs.filter((r) => r.status === query.status);
+    if (query.statuses) runs = runs.filter((r) => query.statuses?.includes(r.status));
+    if (query.tag) runs = runs.filter((r) => r.tags?.includes(query.tag));
+    if (query.attributes?.length) {
+      let candidates = null;
+      for (const f of query.attributes) {
+        const next = this.candidatesForFilter(f);
+        if (candidates == null) {
+          candidates = next;
+        } else {
+          const prev = candidates;
+          candidates = new Set([
+            ...prev
+          ].filter((id) => next.has(id)));
+        }
+        if (candidates.size === 0) break;
+      }
+      const ids = candidates ?? /* @__PURE__ */ new Set();
+      this.lastAttributeCandidates = ids.size;
+      runs = runs.filter((r) => ids.has(r.id));
+    }
+    runs.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? runs.length;
+    return runs.slice(offset, offset + limit).map((r) => ({
+      ...r
+    }));
+  }
+  async listCheckpoints(runId) {
+    return [
+      ...this.checkpoints.values()
+    ].filter((cp) => cp.runId === runId).sort((a, b) => a.seq - b.seq).map((cp) => ({
+      ...cp
+    }));
+  }
+};
+
+// src/testing/in-memory-transport.ts
+var InMemoryTransport = class {
+  static {
+    __name(this, "InMemoryTransport");
+  }
+  handlers = /* @__PURE__ */ new Map();
+  resultHandler;
+  stepEventHandler;
+  controlHandlers = /* @__PURE__ */ new Set();
+  /** Register a fake worker handler for a step name. */
+  handle(name, fn) {
+    this.handlers.set(name, fn);
+  }
+  async dispatch(task) {
+    if (!this.resultHandler) throw new Error("no result handler registered");
+    const result = await runStepHandler(task, this.handlers.get(task.name));
+    setImmediate(() => void this.resultHandler?.(result));
+  }
+  onResult(handler) {
+    this.resultHandler = handler;
+  }
+  onHeartbeat(_handler) {
+  }
+  /** Workflow step lifecycle: deliver to the engine's handler (async, mirroring a real broker). */
+  async dispatchStepEvent(event) {
+    await this.stepEventHandler?.(event);
+  }
+  onStepEvent(handler) {
+    this.stepEventHandler = handler;
+  }
+  // Control plane: broadcast to every registered handler (including the publisher's own — the
+  // engine dedupes by `from`), mirroring how a real broker echoes a publish to all subscribers.
+  async publishControl(msg) {
+    for (const handler of this.controlHandlers) handler(msg);
+  }
+  onControl(handler) {
+    this.controlHandlers.add(handler);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CodecStateStore,
+  ContinueAsNew,
+  DURABLE_OPTIONS,
+  Entities,
+  EventAccumulators,
+  FatalError,
+  InMemoryStateStore,
+  InMemoryTransport,
+  NonDeterminismError,
+  QueueController,
+  RemoteStepError,
+  RemoteStepTimeout,
+  RemoteWorkflowExecutor,
+  STATE_STORE,
+  SignalTimeoutError,
+  SingletonQueueFullError,
+  TRANSPORT,
+  WORKFLOW_NAME_KEY,
+  WorkflowEngine,
+  WorkflowSuspended,
+  applyAttributeQuery,
+  attributeColumnFor,
+  attributeOperand,
+  breakpointToken,
+  collectMetrics,
+  eventMatchOf,
+  eventMatches,
+  eventPrefix,
+  eventToken,
+  matchesAttributes,
+  normalizeAttributeRows,
+  parseDuration,
+  prevCronFireMs,
+  remoteStep,
+  runSchedules,
+  runStepHandler,
+  scheduledRunId,
+  sqlComparator,
+  stepId,
+  workflowName
+});
+//# sourceMappingURL=index.cjs.map