@dudousxd/nestjs-durable-core 0.0.0-beta-20260701163515

package/dist/index.cjs

@@ -0,0 +1,4726 @@
+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,
+  DURABLE_OPTIONS_CANONICAL: () => DURABLE_OPTIONS_CANONICAL,
+  Entities: () => Entities,
+  EventAccumulators: () => EventAccumulators,
+  FatalError: () => FatalError,
+  GatherError: () => GatherError,
+  InMemoryAdmissionBackend: () => InMemoryAdmissionBackend,
+  InMemoryStateStore: () => InMemoryStateStore,
+  InMemoryTransport: () => InMemoryTransport,
+  NonDeterminismError: () => NonDeterminismError,
+  QueueController: () => QueueController,
+  RemoteStepError: () => RemoteStepError,
+  RemoteStepTimeout: () => RemoteStepTimeout,
+  RemoteWorkflowExecutor: () => RemoteWorkflowExecutor,
+  RemoteWorkflowTimeout: () => RemoteWorkflowTimeout,
+  STATE_STORE: () => STATE_STORE,
+  STATE_STORE_CANONICAL: () => STATE_STORE_CANONICAL,
+  SignalTimeoutError: () => SignalTimeoutError,
+  SingletonQueueFullError: () => SingletonQueueFullError,
+  TERMINAL_RUN_STATUSES: () => TERMINAL_RUN_STATUSES,
+  TRANSPORT: () => TRANSPORT,
+  TRANSPORT_CANONICAL: () => TRANSPORT_CANONICAL,
+  WORKFLOW_NAME_KEY: () => WORKFLOW_NAME_KEY,
+  WorkflowEngine: () => WorkflowEngine,
+  WorkflowSuspended: () => WorkflowSuspended,
+  applyAttributeQuery: () => applyAttributeQuery,
+  attributeColumnFor: () => attributeColumnFor,
+  attributeOperand: () => attributeOperand,
+  breakpointToken: () => breakpointToken,
+  collectMetrics: () => collectMetrics,
+  createStepLogger: () => createStepLogger,
+  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,
+  tenantGroup: () => tenantGroup,
+  workflowName: () => workflowName
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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" || this.config.order === "lifo";
+  }
+  /**
+  * 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 this.config.order === "lifo" ? a.seq > b.seq : 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/admission.ts
+var InMemoryAdmissionBackend = class {
+  static {
+    __name(this, "InMemoryAdmissionBackend");
+  }
+  clock;
+  controllers = /* @__PURE__ */ new Map();
+  constructor(clock) {
+    this.clock = clock;
+  }
+  register(config) {
+    this.controllers.set(config.name, new QueueController(config, this.clock));
+  }
+  handles(queue) {
+    return this.controllers.has(queue);
+  }
+  async tryAdmit(queue, item) {
+    const controller = this.controllers.get(queue);
+    if (!controller) return {
+      ok: true
+    };
+    return controller.tryAdmit(item);
+  }
+  async release(queue, _slotId) {
+    this.controllers.get(queue)?.release();
+  }
+};
+
+// 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 nonEmptyEvents(events) {
+  return events && events.length > 0 ? events : void 0;
+}
+__name(nonEmptyEvents, "nonEmptyEvents");
+function stepCheckpoint(p) {
+  return {
+    runId: p.runId,
+    seq: p.seq,
+    name: p.name,
+    kind: p.kind,
+    stepId: stepId(p.runId, p.seq),
+    status: p.status,
+    input: p.input,
+    output: p.output,
+    error: p.error,
+    events: nonEmptyEvents(p.events),
+    attempts: p.attempts,
+    workerGroup: p.workerGroup,
+    wakeAt: p.wakeAt,
+    parallelGroup: p.parallelGroup,
+    enqueuedAt: p.enqueuedAt,
+    startedAt: p.startedAt,
+    finishedAt: p.finishedAt
+  };
+}
+__name(stepCheckpoint, "stepCheckpoint");
+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,
+    parallelGroup: p.parallelGroup,
+    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 RemoteWorkflowTimeout = class extends Error {
+  static {
+    __name(this, "RemoteWorkflowTimeout");
+  }
+  taskId;
+  timeoutMs;
+  constructor(taskId, timeoutMs) {
+    super(`remote workflow task ${taskId} produced no decision within ${timeoutMs}ms \u2014 presumed dropped; re-driving via recovery`);
+    this.name = "RemoteWorkflowTimeout";
+    this.taskId = taskId;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var NonDeterminismError = class extends Error {
+  static {
+    __name(this, "NonDeterminismError");
+  }
+  runId;
+  seq;
+  constructor(runId, seq, expected, recorded) {
+    super(`non-determinism at ${runId}#${seq}: code expects "${expected}" but history recorded "${recorded}". The workflow changed under an in-flight run \u2014 register a new @Workflow version.`);
+    this.name = "NonDeterminismError";
+    this.runId = runId;
+    this.seq = seq;
+  }
+};
+var GatherError = class extends Error {
+  static {
+    __name(this, "GatherError");
+  }
+  failures;
+  constructor(failures, total) {
+    const ids = failures.map((f) => f.id).join(", ");
+    const denom = total ?? failures.length;
+    super(`ctx.all: ${failures.length} of ${denom} child(ren) failed: ${ids}`);
+    this.name = "GatherError";
+    this.failures = failures;
+  }
+};
+var WorkflowSuspended = class extends Error {
+  static {
+    __name(this, "WorkflowSuspended");
+  }
+  /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
+  wakeAt;
+  constructor(wakeAt) {
+    super("workflow suspended");
+    this.name = "WorkflowSuspended";
+    this.wakeAt = wakeAt;
+  }
+};
+var ContinueAsNew = class extends Error {
+  static {
+    __name(this, "ContinueAsNew");
+  }
+  input;
+  constructor(input) {
+    super("workflow continued as new"), this.input = input;
+    this.name = "ContinueAsNew";
+  }
+};
+
+// src/entities.ts
+var ENTITY_WORKFLOW = "__entity";
+var entityRunId = /* @__PURE__ */ __name((name, key) => `entity:${name}:${key}`, "entityRunId");
+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/remote-workflow-executor.ts
+var RemoteWorkflowExecutor = class {
+  static {
+    __name(this, "RemoteWorkflowExecutor");
+  }
+  transport;
+  group;
+  constructor(transport, group, _opts = {}) {
+    this.transport = transport;
+    this.group = group;
+  }
+  /**
+  * Enqueue one workflow turn under the engine-supplied `taskId`. Does NOT await the decision — the
+  * engine has already suspended the run on `taskId` and applies the decision durably via `onDecision`.
+  */
+  async dispatch(run, history, taskId, pendingSignals) {
+    if (!this.transport.dispatchWorkflowTask) {
+      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
+    }
+    const task = {
+      taskId,
+      runId: run.id,
+      workflow: run.workflow,
+      workflowVersion: run.workflowVersion,
+      input: run.input,
+      history,
+      ...pendingSignals ? {
+        pendingSignals
+      } : {},
+      group: this.group,
+      priority: run.priority,
+      attempt: 1
+    };
+    await this.transport.dispatchWorkflowTask(task);
+  }
+};
+
+// src/singleton-gate.ts
+var SINGLETON_RETRY_MS = 1e3;
+var SINGLETON_RETRY_JITTER_MS = 250;
+var SingletonGate = class {
+  static {
+    __name(this, "SingletonGate");
+  }
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /** The tag a singleton run carries, so the gate can find others sharing its key. */
+  tag(cfg, input) {
+    return `singleton:${cfg.key(input)}`;
+  }
+  /** Next wake time for a gated run: the base retry delay jittered to avoid a wakeup stampede. */
+  retryWakeAt() {
+    return this.deps.clock() + SINGLETON_RETRY_MS + Math.floor((Math.random() * 2 - 1) * SINGLETON_RETRY_JITTER_MS);
+  }
+  /**
+  * Reject a start that would grow the same-key backlog past `limit + maxQueueDepth` (counting
+  * `pending`/`running`/`suspended` runs sharing the key in one scan). No-op when no `maxQueueDepth`
+  * is configured.
+  */
+  async assertCapacity(workflow, cfg, input) {
+    if (cfg.maxQueueDepth == null) return;
+    const cap = (cfg.limit ?? 1) + cfg.maxQueueDepth;
+    const queued = await this.deps.store.listRuns({
+      tag: this.tag(cfg, input),
+      workflow,
+      statuses: [
+        "pending",
+        "running",
+        "suspended",
+        "cancelling"
+      ]
+    });
+    if (queued.length >= cap) {
+      throw new SingletonQueueFullError(workflow, cfg.key(input), cfg.maxQueueDepth);
+    }
+  }
+  /**
+  * Whether `run` may run now under its key: it's among the `limit` oldest in-flight (running or
+  * suspended) runs sharing the key, by `(createdAt, id)` order. A consistent store gives every
+  * instance the same ordering, so admission is race-free + FIFO.
+  */
+  async admit(run, cfg) {
+    const inflight = (await this.deps.store.listRuns({
+      tag: this.tag(cfg, run.input),
+      workflow: run.workflow,
+      statuses: [
+        "running",
+        "suspended",
+        "cancelling"
+      ]
+    })).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 settled (freeing a slot), so dispatch the oldest gated
+  * (`suspended` + same tag) waiters now instead of waiting for their ~1s retry timer. Each re-checks
+  * admission in the executor and runs only if it actually wins a slot, so FIFO/race-free guarantees
+  * hold; the durable timer remains the cross-instance/crash fallback.
+  */
+  async wakeNext(settled) {
+    const cfg = this.deps.configFor(settled);
+    if (!cfg) return;
+    const tag = settled.tags?.find((t) => t.startsWith("singleton:"));
+    if (!tag) return;
+    const gated = (await this.deps.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.deps.store.updateRun(next.id, {
+          wakeAt: void 0,
+          updatedAt: /* @__PURE__ */ new Date()
+        }).catch(() => void 0);
+      }
+      this.deps.dispatch(next.id);
+    }
+  }
+};
+
+// src/tenant-group.ts
+function tenantGroup(baseGroup, tenant) {
+  return tenant !== void 0 && tenant !== "" && tenant !== "default" ? `${baseGroup}@${tenant}` : baseGroup;
+}
+__name(tenantGroup, "tenantGroup");
+
+// src/transport-pool.ts
+var TransportPool = class {
+  static {
+    __name(this, "TransportPool");
+  }
+  transports;
+  constructor(transports) {
+    this.transports = transports;
+  }
+  get size() {
+    return this.transports.length;
+  }
+  /**
+  * The primary (first) transport — the one `dispatch` prefers when no `preferId` is pinned. A
+  * {@link RemoteWorkflowExecutor} built by `engine.remote()` rides it (it needs a single
+  * `dispatchWorkflowTask`/`onDecision` Transport, not the whole failover pool). Throws if the pool
+  * is empty — there is nothing to dispatch a remote workflow over.
+  */
+  get primary() {
+    const first = this.transports[0];
+    if (!first) {
+      throw new Error("no transport configured \u2014 engine.remote() needs a transport (or transports)");
+    }
+    return first.transport;
+  }
+  /** 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, onDecision) {
+    for (const { transport } of this.transports) {
+      transport.onResult(onResult);
+      transport.onHeartbeat(onHeartbeat);
+      if (onStepEvent && transport.onStepEvent) {
+        transport.onStepEvent(onStepEvent);
+      }
+      if (onDecision && transport.onDecision) {
+        transport.onDecision(onDecision);
+      }
+    }
+  }
+  /**
+  * 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)
+    };
+  }
+  /**
+  * Register a control-plane `start-run` consumer on every transport that carries the channel. Only
+  * control-plane-side transports implement {@link Transport.onStartRun}; a transport without it is
+  * skipped, so a plain worker/in-process pool is a no-op. Mirrors {@link bind}'s per-transport wiring.
+  */
+  onStartRun(handler) {
+    for (const { transport } of this.transports) {
+      transport.onStartRun?.(handler);
+    }
+  }
+  /** 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
+    ];
+  }
+  /**
+  * Propagate the engine's `namespace` to every transport that partitions by it — so the same
+  * namespace that scopes the store also scopes each transport's queues/keys. A transport that
+  * doesn't partition (no `useNamespace`) is skipped. Idempotent; a transport given an explicit
+  * namespace at construction ignores this (see {@link Transport.useNamespace}).
+  */
+  useNamespace(namespace) {
+    for (const { transport } of this.transports) {
+      transport.useNamespace?.(namespace);
+    }
+  }
+  /** 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
+function normalizeChildOptions(options) {
+  return typeof options === "string" ? {
+    childId: options
+  } : options ?? {};
+}
+__name(normalizeChildOptions, "normalizeChildOptions");
+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, options) => {
+    const { childId, priority } = normalizeChildOptions(options);
+    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, priority);
+    if (!existing) {
+      await writeCheckpoint(instantCheckpoint({
+        runId,
+        seq: current,
+        name: `signal:child:${id}`,
+        kind: "signal",
+        status: "running"
+      }));
+    }
+    throw new WorkflowSuspended();
+  }, "child");
+  const all = /* @__PURE__ */ __name(async (workflow2, inputs, opts) => {
+    if (inputs.length === 0) return [];
+    const mode = opts?.mode ?? "waitAll";
+    const name = workflowName(workflow2);
+    const positions = inputs.map(() => pos.next());
+    const group = `all:${positions[0]}`;
+    const id = /* @__PURE__ */ __name((i) => `${runId}.all.${positions[0]}.${i}`, "id");
+    const existing = await Promise.all(positions.map((seq) => readCheckpoint(seq)));
+    if (mode === "failFast") {
+      for (let i = 0; i < inputs.length; i += 1) {
+        const cp = existing[i];
+        const c = cp?.status === "completed" ? cp.output : null;
+        if (c && c.ok === false) {
+          throw new GatherError([
+            {
+              index: i,
+              id: id(i),
+              error: c.error ?? "unknown"
+            }
+          ], inputs.length);
+        }
+      }
+    }
+    let pending = false;
+    for (let i = 0; i < inputs.length; i += 1) {
+      const cp = existing[i];
+      if (cp?.status === "completed") continue;
+      pending = true;
+      const seq = positions[i];
+      const childId = id(i);
+      await store.putSignalWaiter({
+        token: `child:${childId}`,
+        runId,
+        seq,
+        parallelGroup: group
+      });
+      if (!await store.getRun(childId)) host.startChild(name, inputs[i], childId);
+      if (!cp) {
+        await writeCheckpoint(instantCheckpoint({
+          runId,
+          seq,
+          name: `signal:child:${childId}`,
+          kind: "signal",
+          status: "running",
+          parallelGroup: group
+        }));
+      }
+    }
+    if (pending) throw new WorkflowSuspended();
+    const outputs = [];
+    const failures = [];
+    for (let i = 0; i < inputs.length; i += 1) {
+      const c = existing[i]?.output;
+      if (c && typeof c === "object" && "ok" in c && c.ok === false) {
+        failures.push({
+          index: i,
+          id: id(i),
+          error: c.error ?? "unknown"
+        });
+        outputs.push(void 0);
+      } else {
+        outputs.push(c?.value);
+      }
+    }
+    if (failures.length > 0) throw new GatherError(failures, inputs.length);
+    return outputs;
+  }, "all");
+  const startChild = /* @__PURE__ */ __name(async (workflow2, input, options) => {
+    const { childId, priority } = normalizeChildOptions(options);
+    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, priority);
+    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");
+  const upsertSearchAttributes = /* @__PURE__ */ __name(async (attrs) => {
+    const current = pos.next();
+    const existing = await readCheckpoint(current);
+    if (existing) {
+      if (existing.name !== "searchAttributes") {
+        throw new NonDeterminismError(runId, current, "searchAttributes", existing.name);
+      }
+      return;
+    }
+    await host.upsertSearchAttributes(runId, attrs);
+    await writeCheckpoint(instantCheckpoint({
+      runId,
+      seq: current,
+      name: "searchAttributes",
+      kind: "local",
+      output: attrs
+    }));
+  }, "upsertSearchAttributes");
+  return {
+    runId,
+    step,
+    upsertSearchAttributes,
+    transaction,
+    callEntity,
+    signalEntity,
+    sleep,
+    sleepUntil,
+    continueAsNew,
+    waitForSignal,
+    waitForEvent,
+    task,
+    child,
+    all,
+    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
+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 NamespaceMismatch = class NamespaceMismatch2 extends Error {
+  static {
+    __name(this, "NamespaceMismatch");
+  }
+  constructor() {
+    super("namespace-mismatch");
+  }
+};
+var WorkflowEngine = class {
+  static {
+    __name(this, "WorkflowEngine");
+  }
+  store;
+  /** Ordered transport pool (dispatch + failover). Empty = no remote steps. */
+  pool;
+  controlPlane;
+  clock;
+  instanceId;
+  namespace;
+  leaseMs;
+  maxRecoveryAttempts;
+  remoteAdvanceSilenceMs;
+  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;
+  /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
+  singletons;
+  /** 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();
+  /** "Reset the liveness timer" callbacks keyed by the beat's target — a stepId (in-flight remote step)
+  *  or a runId (in-flight remote workflow turn) — invoked when a matching heartbeat arrives. The two id
+  *  shapes don't collide in practice: a stepId is `${runId}:${seq}`, a run key is the bare runId. */
+  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 admission backend for remote steps (see {@link registerQueue}). */
+  admission;
+  /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
+  queueWaiters = /* @__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;
+  /** When true, route an unregistered workflow to the live worker group of the same name. */
+  remoteByConvention;
+  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.admission = deps.admission ?? new InMemoryAdmissionBackend(this.clock);
+    this.admission.onFreed?.((queue) => this.wakeQueueWaiters(queue));
+    this.instanceId = deps.instanceId ?? globalThis.crypto.randomUUID();
+    this.namespace = deps.namespace;
+    if (this.namespace !== void 0) {
+      this.pool.useNamespace(this.namespace);
+    }
+    this.leaseMs = deps.leaseMs ?? 3e4;
+    this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
+    this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
+    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.remoteByConvention = deps.remoteByConvention ?? false;
+    this.singletons = new SingletonGate({
+      store: this.store,
+      clock: this.clock,
+      dispatch: /* @__PURE__ */ __name((runId) => {
+        this.runDispatcher.dispatch(runId);
+      }, "dispatch"),
+      configFor: /* @__PURE__ */ __name((run) => (this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? this.latest.get(run.workflow))?.singleton, "configFor")
+    });
+    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 resets the liveness window for whatever it targets: an in-flight long STEP (keyed
+      // by stepId, see callRemote) or — when stepId is absent — the in-flight workflow TURN (keyed by
+      // runId). For an INLINE-advance turn the reset is an in-memory callback; for a DISPATCH-suspend
+      // turn there is no in-memory waiter, so a run-scoped beat rearms the suspended turn's durable
+      // re-drive deadline (`wakeAt`) instead, keeping a live worker's turn from being re-dispatched.
+      async (beat) => {
+        const reset = this.heartbeatResets.get(beat.stepId ?? beat.runId);
+        if (reset) {
+          reset();
+          return;
+        }
+        if (beat.stepId === void 0) await this.rearmDecisionDeadline(beat.runId);
+      },
+      // 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);
+      },
+      // A workflow-turn DECISION delivered over the broker — applied durably (by run id) on whatever
+      // instance consumes it, NOT correlated to an in-memory promise on the dispatcher. This is the
+      // multi-instance fix: a point-to-point broker may hand the decision to a non-dispatching instance.
+      async (decision) => {
+        await this.completeRemoteDecision(decision);
+      }
+    );
+    this.pool.onStartRun(async (message) => {
+      await this.start(message.workflow, message.input, message.runId ?? globalThis.crypto.randomUUID(), {
+        namespace: message.tenant,
+        tags: message.tags
+      });
+    });
+    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.
+  *
+  * GROUP-SERVED (uniform dispatch, opt-in): pass `{ group, executor }` to have the engine DISPATCH
+  * this workflow's turns to a worker `group` (via `executor.advance`) instead of running `fn`
+  * inline — exactly as {@link registerRemote} does for a cross-SDK (e.g. Python) body, EXCEPT the
+  * body is a TS `fn` the engine retains so an IN-APP worker on `group` can fetch it by name
+  * ({@link workflowBody}) and run it. This is "one app, both roles": the same process owns the
+  * engine AND consumes its own group. Recovery, timers, singleton, cancel and dead-lettering stay
+  * engine concerns, identical to a remote run. OMIT `group`/`executor` (the default) to keep the
+  * inline fast path — `fn` runs in-process and the run pays zero dispatch round-trips. The first
+  * step toward routing every run through a group with no local/remote flag (Phase 3).
+  */
+  register(name, version, fn, opts) {
+    if (opts?.group == null !== (opts?.executor == null)) {
+      throw new Error(`workflow ${name}@${version}: register({ group, executor }) needs BOTH group and executor (or neither)`);
+    }
+    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,
+      // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
+      // it is NOT confused with the throwing stub `registerRemote` installs for a body-less remote.
+      hasBody: true
+    };
+    if (opts?.group != null && opts?.executor != null) {
+      registered.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);
+    for (const event of opts?.onEvent ?? []) {
+      const subscribers = this.eventTriggers.get(event) ?? /* @__PURE__ */ new Set();
+      subscribers.add(name);
+      this.eventTriggers.set(event, subscribers);
+    }
+  }
+  /**
+  * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
+  * own group to SERVE a group-served `register(..., { group, executor })` workflow (uniform dispatch):
+  * the worker fetches the body by name when it picks up the dispatched {@link WorkflowTask}, replays
+  * it, and returns the {@link WorkflowDecision}. `undefined` for an unregistered name or a body-less
+  * remote (a `registerRemote` / synthesized child carries only a throwing stub, never handed out).
+  */
+  workflowBody(name, version) {
+    const reg = this.workflows.get(versionKey(name, version));
+    return reg?.hasBody ? reg.fn : void 0;
+  }
+  /**
+  * 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);
+  }
+  /**
+  * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+  * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+  * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+  * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+  * `engine.remote('processing', { group: 'processing' })` instead of
+  * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+  *
+  * Defaults the version to `'1'`. All the other {@link registerRemote} options
+  * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+  * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+  * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+  */
+  remote(name, opts) {
+    const { group, version, ...rest } = opts;
+    const executor = new RemoteWorkflowExecutor(this.pool.primary, group);
+    this.registerRemote(name, version ?? "1", {
+      group,
+      executor,
+      ...rest
+    });
+  }
+  /**
+  * 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.admission.register(config);
+  }
+  /** 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);
+    let registered = this.latest.get(name);
+    if (!registered) {
+      const ancestor = await this.findRemoteAncestor(runId);
+      if (ancestor) registered = this.synthesizeRemoteChild(name, ancestor.version, ancestor);
+    }
+    if (!registered) {
+      const conventionRun = {
+        id: runId,
+        workflow: name,
+        workflowVersion: "1",
+        status: "pending",
+        // Stamp the namespace the REAL run will carry (:893) so convention routing resolves the same
+        // tenant-suffixed group the run will dispatch to — an operator starting a tenant's run via the
+        // `onStartRun` wire (opts.namespace = tenant) must find the live `<workflow>@<tenant>` group,
+        // not the bare group. Without this the start-run entry path can't reach a suffixed-only worker.
+        namespace: opts?.namespace ?? this.namespace,
+        input,
+        createdAt: /* @__PURE__ */ new Date(),
+        updatedAt: /* @__PURE__ */ new Date()
+      };
+      registered = await this.resolveRemoteByConvention(conventionRun);
+    }
+    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 ?? [],
+      this.singletons.tag(registered.singleton, input)
+    ] : opts?.tags);
+    if (registered.singleton) {
+      await this.singletons.assertCapacity(name, registered.singleton, input);
+    }
+    const run = {
+      id: runId,
+      workflow: name,
+      workflowVersion: registered.version,
+      status: "pending",
+      namespace: opts?.namespace ?? this.namespace,
+      input,
+      tags,
+      searchAttributes: opts?.searchAttributes,
+      priority: opts?.priority,
+      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
+      };
+    }
+    if (this.namespace !== void 0 && run.namespace !== void 0 && run.namespace !== this.namespace) {
+      await this.store.releaseRunLock(runId);
+      throw new NamespaceMismatch();
+    }
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
+    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));
+  }
+  /**
+  * The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
+  * `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
+  * flat registry FIRST (so an explicit `registerRemote(name, …)` ALWAYS wins, and a registered run
+  * never reaches here); this resolves only the new case: a child spawned by a remote workflow (e.g. a
+  * Python `gather_children` / `start_child` fan-out) of a name the host never `registerRemote`-ed. It
+  * is driven as a remote run on the ancestor's group + the SAME executor instance, so the host needs
+  * no redundant registration per child name.
+  *
+  * RECOMPUTED per resume rather than memoized into `this.workflows`: a synthesized child is not a real
+  * registration and must not leak into `latest`, `knownGroups`, or `sweepTimeouts` (which iterate the
+  * registry); recomputing also stays correct if the ancestor's remote registration is re-pointed at a
+  * new executor across a deploy. Only unregistered runs pay it, so registered workflows pay nothing.
+  */
+  async findInheritedRegistration(run) {
+    const ancestor = await this.findRemoteAncestor(run.id);
+    if (!ancestor) return void 0;
+    return this.synthesizeRemoteChild(run.workflow, run.workflowVersion, ancestor);
+  }
+  /**
+  * A throwaway {@link RegisteredWorkflow} that routes `name@version` as a remote run on the ancestor's
+  * group via the ancestor's SAME executor instance. The executor is group-scoped (it dispatches a
+  * {@link WorkflowTask} carrying `run.workflow`, and the worker picks the body by name), so reusing it
+  * is correct AND required — a second executor on the same group would race the worker for results.
+  * Only `remote` is inherited; the child gets none of the ancestor's singleton/timeout/validator, so
+  * its identity stays its own.
+  */
+  synthesizeRemoteChild(name, version, ancestor) {
+    const remote = ancestor.remote;
+    if (!remote) throw new Error(`workflow ${ancestor.name} is not a remote workflow`);
+    return {
+      name,
+      version,
+      fn: /* @__PURE__ */ __name(() => {
+        throw new Error(`workflow ${name} is remote \u2014 it has no in-process body`);
+      }, "fn"),
+      remote
+    };
+  }
+  /**
+  * When `remoteByConvention` is enabled, attempt to route an unregistered workflow to the live
+  * worker group of the same name: if the transport reports a live heartbeat for group
+  * `run.workflow`, synthesize a throwaway {@link RegisteredWorkflow} that dispatches to that group
+  * over the primary transport. Returns `undefined` when the flag is off or the group is not live.
+  *
+  * Recomputed per call (never memoized into `this.workflows`) so it stays correct if group
+  * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
+  */
+  async resolveRemoteByConvention(run) {
+    if (!this.remoteByConvention) return void 0;
+    const liveGroups = await this.pool.listWorkerGroups();
+    const group = tenantGroup(run.workflow, run.namespace);
+    if (!liveGroups.includes(group)) return void 0;
+    const executor = new RemoteWorkflowExecutor(this.pool.primary, group);
+    return {
+      name: run.workflow,
+      version: run.workflowVersion,
+      fn: /* @__PURE__ */ __name(() => {
+        throw new Error(`remote workflow ${run.workflow} has no local body`);
+      }, "fn"),
+      hasBody: false,
+      remote: {
+        group,
+        executor
+      }
+    };
+  }
+  /**
+  * Walk the parent chain of `childRunId` to the nearest ancestor registered as REMOTE, returning its
+  * registration (or `undefined` if there is none). The parent of an awaited child is found via its
+  * live `child:<childId>` signal waiter — present for as long as the parent is suspended awaiting the
+  * child, i.e. throughout the child's executable lifetime (start, every resume, crash recovery, cancel
+  * cascade), which is exactly when we resolve. A registered-but-LOCAL parent stops the walk (an
+  * unregistered child of a TS workflow is a genuine misconfiguration → skew error); only an
+  * unregistered parent keeps walking, so a child of an inherited child still reaches the remote root.
+  * `visited` guards against a pathological cyclic id graph.
+  */
+  async findRemoteAncestor(childRunId, visited = /* @__PURE__ */ new Set()) {
+    if (visited.has(childRunId)) return void 0;
+    visited.add(childRunId);
+    const parentRunId = await this.findParentRunId(childRunId);
+    if (!parentRunId) return void 0;
+    const parent = await this.store.getRun(parentRunId);
+    if (!parent) return void 0;
+    const parentReg = this.workflows.get(versionKey(parent.workflow, parent.workflowVersion));
+    if (parentReg?.remote) return parentReg;
+    if (parentReg) return void 0;
+    return this.findRemoteAncestor(parent.id, visited);
+  }
+  /**
+  * The run that spawned `childRunId`, via its live `child:<childRunId>` signal waiter — every awaited
+  * child (`ctx.child`, `ctx.all`, a remote `start_child`) suspends its parent on exactly this waiter,
+  * and the waiter is written BEFORE the child is started. Only reached for an UNREGISTERED child, so
+  * registered runs never pay the scan; returns `undefined` once the parent has settled the child (the
+  * waiter is consumed), but by then the child is terminal and no longer resolved.
+  */
+  async findParentRunId(childRunId) {
+    const token = `child:${childRunId}`;
+    for (const waiter of await this.store.listSignalWaiters("child:")) {
+      if (waiter.token === token) return waiter.runId;
+    }
+    return void 0;
+  }
+  /** 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",
+          namespace: this.namespace
+        }),
+        ...await this.store.listRuns({
+          workflow: reg.name,
+          status: "suspended",
+          namespace: this.namespace
+        })
+      ];
+      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(this.namespace)) {
+      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);
+      if (run.status !== "cancelling") {
+        await this.store.updateRun(run.id, {
+          status: "pending",
+          updatedAt: /* @__PURE__ */ new Date()
+        });
+      }
+      await this.runDispatcher.dispatch(run.id);
+      results.push({
+        runId: run.id,
+        status: run.status === "cancelling" ? "cancelling" : "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, this.namespace), 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).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
+  }
+  /**
+  * 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,
+      namespace: run.namespace
+    });
+    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, this.namespace), 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((run) => run.status !== "pending" && run.status !== "running" && run.status !== "cancelling" && !(run.status === "suspended" && run.awaitingDecisionTaskId !== void 0), "isSettled");
+    const toResult = /* @__PURE__ */ __name((run) => ({
+      runId,
+      status: run.status,
+      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)) 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,
+      // Carry the awaiting command's fan group (set when a `ctx.gather_children`/`ctx.all` fan-out
+      // registered this waiter) onto the resolving `signal:child:<id>` checkpoint, so the dashboard
+      // groups the child fan-out vertically instead of rendering it as a sequential chain. Undefined
+      // for an ordinary (non-fan) signal/child await.
+      parallelGroup: waiter.parallelGroup
+    }));
+    return this.resume(waiter.runId).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
+  }
+  /**
+  * 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 (run.status === "cancelling") {
+      return {
+        runId,
+        status: "cancelling"
+      };
+    }
+    if (opts?.compensate && (run.status === "suspended" || run.status === "running")) {
+      this.cancelRequested.add(runId);
+      await this.store.updateRun(runId, {
+        status: "cancelling",
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      run.status = "cancelling";
+      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: "cancelling"
+      };
+    }
+    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.singletons.wakeNext(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;
+  }
+  /**
+  * Hard-delete a run and its entire subtree. Unlike {@link cancel} (which marks a run `cancelled`
+  * but keeps it as history), delete REMOVES the run and all its rows (checkpoints, signal waiters,
+  * search-attribute rows) — it vanishes from {@link getRun} and {@link listRuns}. Use it to purge a
+  * finished run whose data is being deleted (e.g. a pipeline run whose result rows are cleared).
+  *
+  * Cascades depth-first via {@link getRunChildren} so children are gone before the parent (no
+  * orphaned child runs). Prefer {@link cancel} first for a live run — deleting one mid-flight orphans
+  * its worker (its next checkpoint write fails). Returns the number of runs deleted (0 if absent).
+  */
+  async deleteRun(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return 0;
+    let deleted = 0;
+    for (const childId of await this.getRunChildren(runId)) {
+      deleted += await this.deleteRun(childId);
+    }
+    await this.store.deleteRun(runId);
+    return deleted + 1;
+  }
+  /**
+  * 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));
+    }
+    const prefixes = [
+      "signal:child:",
+      "spawn:"
+    ];
+    const childCheckpoints = this.store.listCheckpointsByNamePrefix ? await this.store.listCheckpointsByNamePrefix(parentRunId, prefixes) : (await this.store.listCheckpoints(parentRunId)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+    for (const cp of childCheckpoints) {
+      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);
+    if (event.phase === "running") {
+      await this.store.saveCheckpoint(stepCheckpoint({
+        runId: event.runId,
+        seq: event.seq,
+        name: event.name,
+        kind: "local",
+        status: "running",
+        events: event.events,
+        attempts: 1,
+        enqueuedAt: startedAt,
+        startedAt,
+        finishedAt: startedAt,
+        parallelGroup: event.parallelGroup
+      }));
+      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(stepCheckpoint({
+      runId: event.runId,
+      seq: event.seq,
+      name: event.name,
+      kind: "local",
+      status: failed ? "failed" : "completed",
+      output: failed ? void 0 : event.output,
+      error: failed ? event.error : void 0,
+      events: event.events,
+      attempts: 1,
+      enqueuedAt: startedAt,
+      startedAt,
+      finishedAt: event.finishedAt != null ? new Date(event.finishedAt) : /* @__PURE__ */ new Date(),
+      parallelGroup: event.parallelGroup
+    }));
+    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(stepCheckpoint({
+        runId: step.runId,
+        seq: step.seq,
+        name: step.name,
+        kind: step.kind,
+        status: "running",
+        input: step.input,
+        events: step.events,
+        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(stepCheckpoint({
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      status: "completed",
+      input: step.input,
+      output: step.output,
+      events: step.events,
+      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(stepCheckpoint({
+      runId: step.runId,
+      seq: step.seq,
+      name: step.name,
+      kind: step.kind,
+      status: "failed",
+      input: step.input,
+      error: step.error,
+      events: step.events,
+      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()
+    });
+  }
+  async execute(run, fn) {
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
+    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.singletons.wakeNext(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.
+  */
+  /**
+  * Apply a terminal/suspended transition once: persist the new run status, emit the matching
+  * lifecycle event, and (on completion/failure) wake a waiting parent. Both the TS and remote
+  * executors funnel their completed/failed/suspended outcomes through here so a status update can
+  * never drift from its event or `notifyParent` call. Does NOT touch the run lock — each executor
+  * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
+  */
+  async settleRun(run, outcome) {
+    const updatedAt = /* @__PURE__ */ new Date();
+    if (outcome.kind === "completed") {
+      await this.store.updateRun(run.id, {
+        status: "completed",
+        output: outcome.output,
+        error: void 0,
+        updatedAt
+      });
+      this.emit({
+        type: "run.completed",
+        runId: run.id,
+        workflow: run.workflow,
+        output: outcome.output
+      });
+      void this.notifyParent(run.id, {
+        ok: true,
+        value: outcome.output
+      });
+      return {
+        runId: run.id,
+        status: "completed",
+        output: outcome.output
+      };
+    }
+    if (outcome.kind === "failed") {
+      await this.store.updateRun(run.id, {
+        status: "failed",
+        error: outcome.error,
+        updatedAt
+      });
+      this.emit({
+        type: "run.failed",
+        runId: run.id,
+        workflow: run.workflow,
+        error: outcome.error
+      });
+      void this.notifyParent(run.id, {
+        ok: false,
+        error: outcome.error.message
+      });
+      return {
+        runId: run.id,
+        status: "failed",
+        error: outcome.error
+      };
+    }
+    await this.store.updateRun(run.id, {
+      status: "suspended",
+      wakeAt: outcome.wakeAt,
+      updatedAt
+    });
+    this.emit({
+      type: "run.suspended",
+      runId: run.id,
+      workflow: run.workflow
+    });
+    return {
+      runId: run.id,
+      status: "suspended"
+    };
+  }
+  async runRemoteExecution(run, registered) {
+    if (run.status === "cancelling") {
+      const error = {
+        message: "cancelled"
+      };
+      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
+      });
+      this.notifyCancelled(run.id);
+      if (this.controlPlane) {
+        void this.controlPlane.publishControl({
+          kind: "cancel",
+          runId: run.id,
+          from: this.instanceId
+        }).catch(() => void 0);
+      }
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: "cancelled",
+        error
+      };
+    }
+    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.singletons.admit(run, registered.singleton)) {
+      const wakeAt = this.singletons.retryWakeAt();
+      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 history = await this.remoteHistory(run.id);
+    if (remote.executor.dispatch) {
+      const taskId = `${run.id}:wf:${globalThis.crypto.randomUUID().slice(0, 8)}`;
+      const silenceMs = this.remoteAdvanceSilenceMs;
+      const wakeAt = silenceMs != null ? this.clock() + silenceMs : void 0;
+      await this.store.updateRun(run.id, {
+        status: "suspended",
+        awaitingDecisionTaskId: taskId,
+        wakeAt,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      this.emit({
+        type: "run.suspended",
+        runId: run.id,
+        workflow: run.workflow
+      });
+      await this.store.releaseRunLock(run.id);
+      await remote.executor.dispatch(run, history, taskId);
+      return {
+        runId: run.id,
+        status: "suspended"
+      };
+    }
+    const advanceExecutor = remote.executor.advance;
+    if (!advanceExecutor) {
+      throw new Error(`workflow ${run.workflow}@${run.workflowVersion}: executor implements neither advance nor dispatch`);
+    }
+    let decision;
+    try {
+      const silenceMs = this.remoteAdvanceSilenceMs;
+      const advance = advanceExecutor.call(remote.executor, run, history);
+      decision = silenceMs != null ? await this.awaitWithLivenessDeadline(run.id, advance, silenceMs, () => new RemoteWorkflowTimeout(run.id, silenceMs)) : await advance;
+    } catch (err) {
+      if (err instanceof RemoteWorkflowTimeout) {
+        await this.store.releaseRunLock(run.id);
+        return {
+          runId: run.id,
+          status: "running"
+        };
+      }
+      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
+      };
+    }
+    return this.applyDecision(run, decision);
+  }
+  /**
+  * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
+  * settle (completed/failed/cancelled) or dispatch its blocking ops and suspend (continue). Shared by
+  * the INLINE-advance path ({@link runRemoteExecution}, under the held lease) and the durable
+  * DISPATCH path ({@link completeRemoteDecision}, which holds the lease itself). Idempotent transitions
+  * — the caller has already ensured this is the decision for the currently-awaited turn.
+  */
+  async applyDecision(run, decision) {
+    if (decision.status === "completed") {
+      await this.applyCommands(run, decision.commands);
+      return this.settleRun(run, {
+        kind: "completed",
+        output: decision.output
+      });
+    }
+    if (decision.status === "failed") {
+      await this.applyCommands(run, decision.commands);
+      return this.settleRun(run, {
+        kind: "failed",
+        error: decision.error ?? {
+          message: "workflow failed"
+        }
+      });
+    }
+    if (decision.status === "cancelled") {
+      await this.applyCommands(run, decision.commands);
+      await this.store.updateRun(run.id, {
+        status: "cancelled",
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      return {
+        runId: run.id,
+        status: "cancelled"
+      };
+    }
+    const fresh = await this.store.getRun(run.id);
+    if (fresh && (fresh.status === "cancelled" || fresh.status === "completed" || fresh.status === "dead")) {
+      return {
+        runId: run.id,
+        status: fresh.status,
+        output: fresh.output,
+        error: fresh.error
+      };
+    }
+    const wakeAt = await this.applyCommands(run, decision.commands);
+    return this.settleRun(run, {
+      kind: "suspended",
+      wakeAt
+    });
+  }
+  /** 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(stepCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "local",
+          status: cmd.error ? "failed" : "completed",
+          output: cmd.output,
+          error: cmd.error,
+          events: cmd.events,
+          attempts: 1,
+          enqueuedAt: startedAt,
+          startedAt,
+          finishedAt,
+          // Carry the worker's `parallelGroup` (a Python `ctx.gather` tags every step in the fan with
+          // the same group) onto the checkpoint, so the dashboard can render the steps as one parallel
+          // group instead of a sequential list. Additive: undefined for ordinary sequential steps.
+          parallelGroup: cmd.parallelGroup
+        }));
+        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") {
+        if (await this.store.getCheckpoint(run.id, cmd.seq)) continue;
+        await this.store.saveCheckpoint(stepCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: cmd.name,
+          kind: "remote",
+          status: "pending",
+          input: cmd.input,
+          attempts: 1,
+          workerGroup: cmd.group,
+          enqueuedAt: at,
+          startedAt: at,
+          finishedAt: at,
+          // A `ctx.gather_calls([...])` fan-out stamps every dispatched `call` in the fan with the
+          // same group, so the dashboard renders the remote steps as one parallel fan (parity with
+          // the gathered `recordStep`/`startChild` tags). Undefined for a lone sequential `ctx.call`.
+          parallelGroup: cmd.parallelGroup
+        }));
+        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(stepCheckpoint({
+          runId: run.id,
+          seq: cmd.seq,
+          name: `sleep:${cmd.seq}`,
+          kind: "sleep",
+          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,
+          // A `ctx.gather_children`/`ctx.all` fan-out stamps every `startChild` in the fan with the same
+          // group. Thread it onto the waiter so the child's terminal `signal:child:<id>` checkpoint
+          // (written by engine.signal when the child notifies the parent) carries the group and the
+          // dashboard renders the fan as one parallel group. Undefined for a lone (non-fan) child.
+          parallelGroup: cmd.parallelGroup
+        });
+        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;
+  }
+  /**
+  * Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
+  * exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
+  * suspended, hit continue-as-new, or threw — so a cancel is never lost just because the body didn't
+  * stop at a suspension point. Clears the in-memory cancel flag.
+  */
+  async compensateAndCancel(run, compensations) {
+    this.cancelRequested.delete(run.id);
+    for (let i = compensations.length - 1; i >= 0; i -= 1) {
+      const comp = compensations[i];
+      if (comp) await this.runCompensation(run, comp);
+    }
+    const error = {
+      message: "cancelled"
+    };
+    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
+    });
+    return {
+      runId: run.id,
+      status: "cancelled",
+      error
+    };
+  }
+  /** The run body, lease held + renewed by {@link execute}. */
+  async runExecution(run, fn, registered) {
+    if (run.status === "cancelling") this.cancelRequested.add(run.id);
+    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 (run.status !== "cancelling" && registered?.singleton && !await this.singletons.admit(run, registered.singleton)) {
+      const wakeAt = this.singletons.retryWakeAt();
+      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);
+      if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+      return this.settleRun(run, {
+        kind: "completed",
+        output
+      });
+    } catch (err) {
+      if (err instanceof ContinueAsNew) {
+        if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+        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)) return this.compensateAndCancel(run, compensations);
+        return this.settleRun(run, {
+          kind: "suspended",
+          wakeAt: err.wakeAt
+        });
+      }
+      if (this.cancelRequested.has(run.id)) return this.compensateAndCancel(run, compensations);
+      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);
+      }
+      return this.settleRun(run, {
+        kind: "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, priority) => {
+        queueMicrotask(() => void this.start(workflow, input, id, {
+          priority
+        }).catch(() => void 0));
+      }, "startChild"),
+      // Shallow-merge into the run's searchAttributes (the ctx primitive makes this exactly-once).
+      upsertSearchAttributes: /* @__PURE__ */ __name(async (runId, attrs) => {
+        const run = await this.store.getRun(runId);
+        await this.store.updateRun(runId, {
+          searchAttributes: {
+            ...run?.searchAttributes ?? {},
+            ...attrs
+          },
+          updatedAt: /* @__PURE__ */ new Date()
+        });
+      }, "upsertSearchAttributes"),
+      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}`;
+    if (this.store.getLatestCheckpointByName) {
+      const latest2 = await this.store.getLatestCheckpointByName(runId, name);
+      return latest2?.output;
+    }
+    let latest;
+    for (const cp of await this.store.listCheckpoints(runId)) 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);
+    if (queue && this.admission.handles(queue)) {
+      const decision = await this.admission.tryAdmit(queue, {
+        priority: admission?.priority,
+        key: admission?.fairnessKey ?? runId,
+        waiterId: id
+      });
+      if (!decision.ok) {
+        const waiters = this.queueWaiters.get(queue) ?? /* @__PURE__ */ new Set();
+        waiters.add(runId);
+        this.queueWaiters.set(queue, waiters);
+        throw new WorkflowSuspended(decision.retryAt);
+      }
+      this.queueWaiters.get(queue)?.delete(runId);
+      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?.(),
+      priority: admission?.priority,
+      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;
+    void this.releaseQueueSlot(cp.stepId).catch(() => void 0);
+    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).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
+  }
+  /**
+  * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
+  * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
+  * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
+  * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
+  * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
+  * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
+  */
+  async completeRemoteDecision(decision) {
+    const run = await this.store.getRun(decision.runId);
+    if (!run || run.awaitingDecisionTaskId !== decision.taskId) return;
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead") return;
+    if (this.namespace !== void 0 && run.namespace !== void 0 && run.namespace !== this.namespace) {
+      return;
+    }
+    const nowMs = this.clock();
+    if (!await this.store.tryLockRun(decision.runId, this.instanceId, nowMs + this.leaseMs, nowMs)) {
+      return;
+    }
+    const renew = setInterval(() => {
+      void this.store.renewRunLock(decision.runId, this.instanceId, this.clock() + this.leaseMs).catch(() => void 0);
+    }, Math.max(50, Math.floor(this.leaseMs / 2)));
+    renew.unref?.();
+    try {
+      const fresh = await this.store.getRun(decision.runId);
+      if (!fresh || fresh.awaitingDecisionTaskId !== decision.taskId) return;
+      if (fresh.status === "cancelled" || fresh.status === "completed" || fresh.status === "dead") {
+        return;
+      }
+      await this.store.updateRun(decision.runId, {
+        awaitingDecisionTaskId: void 0,
+        wakeAt: void 0,
+        updatedAt: /* @__PURE__ */ new Date()
+      });
+      fresh.awaitingDecisionTaskId = void 0;
+      await this.applyDecision(fresh, decision);
+    } finally {
+      clearInterval(renew);
+      await this.store.releaseRunLock(decision.runId);
+    }
+  }
+  /**
+  * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
+  * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
+  * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
+  */
+  async rearmDecisionDeadline(runId) {
+    const silenceMs = this.remoteAdvanceSilenceMs;
+    if (silenceMs == null) return;
+    const run = await this.store.getRun(runId);
+    if (!run || run.status !== "suspended" || run.awaitingDecisionTaskId === void 0) return;
+    await this.store.updateRun(runId, {
+      wakeAt: this.clock() + silenceMs,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /**
+  * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
+  * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
+  * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
+  */
+  wakeQueueWaiters(queue) {
+    const waiters = this.queueWaiters.get(queue);
+    if (!waiters || waiters.size === 0) return;
+    const runIds = [
+      ...waiters
+    ];
+    waiters.clear();
+    for (const runId of runIds) void this.resume(runId).catch(() => void 0);
+  }
+  /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
+  async releaseQueueSlot(id) {
+    const queue = this.stepQueue.get(id);
+    if (queue === void 0) return;
+    this.stepQueue.delete(id);
+    await this.admission.release(queue, id);
+  }
+  /** 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 `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
+  * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
+  * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
+  * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
+  * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
+  */
+  awaitWithLivenessDeadline(id, resultPromise, timeoutMs, onTimeout) {
+    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();
+          reject(onTimeout());
+        }, timeoutMs);
+        timer.unref?.();
+      }, "arm");
+      this.heartbeatResets.set(id, () => {
+        clearTimeout(timer);
+        arm();
+      });
+      arm();
+      resultPromise.then((value) => {
+        cleanup();
+        resolve(value);
+      }, (err) => {
+        cleanup();
+        reject(err);
+      });
+    });
+  }
+  /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
+  *  `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
+  awaitWithHeartbeat(id, resultPromise, timeoutMs) {
+    return this.awaitWithLivenessDeadline(id, resultPromise, timeoutMs, () => {
+      this.pending.delete(id);
+      return new RemoteStepTimeout(id, timeoutMs);
+    });
+  }
+};
+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/interfaces.ts
+var TERMINAL_RUN_STATUSES = [
+  "completed",
+  "failed",
+  "cancelled",
+  "dead"
+];
+
+// 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/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));
+  }
+  deleteRun(runId) {
+    return this.inner.deleteRun(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(namespace) {
+    return (await this.inner.listIncompleteRuns(namespace)).map((r) => this.decRun(r));
+  }
+  async listPendingRuns(limit, namespace) {
+    return (await this.inner.listPendingRuns(limit, namespace)).map((r) => this.decRun(r));
+  }
+  async listDueTimers(nowMs, namespace) {
+    return (await this.inner.listDueTimers(nowMs, namespace)).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));
+  }
+  async getLatestCheckpointByName(runId, name) {
+    if (this.inner.getLatestCheckpointByName) {
+      const cp = await this.inner.getLatestCheckpointByName(runId, name);
+      return cp ? this.decCp(cp) : void 0;
+    }
+    let latest;
+    for (const cp of await this.inner.listCheckpoints(runId)) if (cp.name === name) latest = cp;
+    return latest ? this.decCp(latest) : void 0;
+  }
+  async listCheckpointsByNamePrefix(runId, prefixes) {
+    const matches = this.inner.listCheckpointsByNamePrefix ? await this.inner.listCheckpointsByNamePrefix(runId, prefixes) : (await this.inner.listCheckpoints(runId)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+    return matches.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";
+    let entry = m.byWorkflow[k];
+    if (!entry) {
+      entry = {
+        started: 0,
+        completed: 0,
+        failed: 0
+      };
+      m.byWorkflow[k] = entry;
+    }
+    return entry;
+  }, "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.for("nestjs-durable:STATE_STORE");
+var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
+var DURABLE_OPTIONS = Symbol.for("nestjs-durable:DURABLE_OPTIONS");
+var STATE_STORE_CANONICAL = Symbol.for("@dudousxd/nestjs-durable:state-store");
+var TRANSPORT_CANONICAL = Symbol.for("@dudousxd/nestjs-durable:transport");
+var DURABLE_OPTIONS_CANONICAL = Symbol.for("@dudousxd/nestjs-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;
+  /**
+  * Test/observability hook: how many checkpoint rows the LAST checkpoint read materialized (the rows
+  * actually returned to the caller). `listCheckpoints` returns all rows for the run; the targeted
+  * {@link getLatestCheckpointByName} / {@link listCheckpointsByNamePrefix} return only the matches —
+  * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
+  */
+  lastCheckpointRowsRead = 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,
+      namespace: run.namespace ?? "default"
+    });
+    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 deleteRun(runId) {
+    this.runs.delete(runId);
+    for (const [key, cp] of this.checkpoints) {
+      if (cp.runId === runId) this.checkpoints.delete(key);
+    }
+    for (const [token, waiter] of this.signalWaiters) {
+      if (waiter.runId === runId) this.signalWaiters.delete(token);
+    }
+    this.reindexAttributes(runId, void 0);
+  }
+  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(namespace) {
+    return [
+      ...this.runs.values()
+    ].filter((r) => (r.status === "running" || r.status === "cancelling") && (namespace === void 0 || r.namespace === namespace)).map((r) => ({
+      ...r
+    }));
+  }
+  async listPendingRuns(limit, namespace) {
+    return [
+      ...this.runs.values()
+    ].filter((r) => r.status === "pending" && (namespace === void 0 || r.namespace === namespace)).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id)).slice(0, limit).map((r) => ({
+      ...r
+    }));
+  }
+  async listDueTimers(nowMs, namespace) {
+    return [
+      ...this.runs.values()
+    ].filter((r) => r.status === "suspended" && r.wakeAt !== void 0 && r.wakeAt <= nowMs && (namespace === void 0 || r.namespace === namespace)).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.namespace !== void 0) runs = runs.filter((r) => r.namespace === query.namespace);
+    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) {
+    const rows = [
+      ...this.checkpoints.values()
+    ].filter((cp) => cp.runId === runId).sort((a, b) => a.seq - b.seq).map((cp) => ({
+      ...cp
+    }));
+    this.lastCheckpointRowsRead = rows.length;
+    return rows;
+  }
+  async getLatestCheckpointByName(runId, name) {
+    let latest;
+    for (const cp of this.checkpoints.values()) {
+      if (cp.runId !== runId || cp.name !== name) continue;
+      if (!latest || cp.seq > latest.seq) latest = cp;
+    }
+    this.lastCheckpointRowsRead = latest ? 1 : 0;
+    return latest ? {
+      ...latest
+    } : void 0;
+  }
+  async listCheckpointsByNamePrefix(runId, prefixes) {
+    const rows = [
+      ...this.checkpoints.values()
+    ].filter((cp) => cp.runId === runId && prefixes.some((p) => cp.name.startsWith(p))).sort((a, b) => a.seq - b.seq).map((cp) => ({
+      ...cp
+    }));
+    this.lastCheckpointRowsRead = rows.length;
+    return rows;
+  }
+};
+
+// src/testing/in-memory-transport.ts
+var InMemoryTransport = class {
+  static {
+    __name(this, "InMemoryTransport");
+  }
+  handlers = /* @__PURE__ */ new Map();
+  resultHandler;
+  heartbeatHandler;
+  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) {
+    this.heartbeatHandler = handler;
+  }
+  /** Test hook: deliver a liveness heartbeat to the engine, as a real broker would on its channel. */
+  async emitHeartbeat(beat) {
+    await this.heartbeatHandler?.(beat);
+  }
+  /** 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,
+  DURABLE_OPTIONS_CANONICAL,
+  Entities,
+  EventAccumulators,
+  FatalError,
+  GatherError,
+  InMemoryAdmissionBackend,
+  InMemoryStateStore,
+  InMemoryTransport,
+  NonDeterminismError,
+  QueueController,
+  RemoteStepError,
+  RemoteStepTimeout,
+  RemoteWorkflowExecutor,
+  RemoteWorkflowTimeout,
+  STATE_STORE,
+  STATE_STORE_CANONICAL,
+  SignalTimeoutError,
+  SingletonQueueFullError,
+  TERMINAL_RUN_STATUSES,
+  TRANSPORT,
+  TRANSPORT_CANONICAL,
+  WORKFLOW_NAME_KEY,
+  WorkflowEngine,
+  WorkflowSuspended,
+  applyAttributeQuery,
+  attributeColumnFor,
+  attributeOperand,
+  breakpointToken,
+  collectMetrics,
+  createStepLogger,
+  eventMatchOf,
+  eventMatches,
+  eventPrefix,
+  eventToken,
+  matchesAttributes,
+  normalizeAttributeRows,
+  parseDuration,
+  prevCronFireMs,
+  remoteStep,
+  runSchedules,
+  runStepHandler,
+  scheduledRunId,
+  sqlComparator,
+  stepId,
+  tenantGroup,
+  workflowName
+});
+//# sourceMappingURL=index.cjs.map